Configuration File
Setting The Configuration File Path
The protoc-gen-kroto-plus
plugin needs a configuration file to be passed in order to be able to enable and configure its built in code generators. This is done by setting passing in a protoc plugin option to protoc-gen-kroto-plus
in the following format, ConfigPath=path/to/configFile.yaml
plugins{
id 'com.google.protobuf' version '0.8.6'
}
protobuf {
protoc { artifact = "com.google.protobuf:protoc:$protobufVersion"}
plugins {
kroto {
artifact = "com.github.marcoferrer.krotoplus:protoc-gen-kroto-plus:$krotoPlusVersion"
}
}
generateProtoTasks {
def krotoConfig = file("krotoPlusConfig.asciipb") // Or .json, .yaml, .yml
all().each{ task ->
// Adding the config file to the task inputs lets UP-TO-DATE checks
// include changes to configuration
task.inputs.files krotoConfig
task.plugins {
kroto {
outputSubDir = "java"
option "ConfigPath=$krotoConfig"
}
}
}
}
}
plugins{
id("com.google.protobuf") version "0.8.6"
}
protobuf {
protoc { artifact = "com.google.protobuf:protoc:$protobufVersion"}
plugins {
id("kroto") {
artifact = "com.github.marcoferrer.krotoplus:protoc-gen-kroto-plus:$krotoPlusVersion"
}
}
generateProtoTasks {
val krotoConfig = file("krotoPlusConfig.asciipb") // Or .json
all().forEach { task ->
// Adding the config file to the task inputs lets UP-TO-DATE checks
// include changes to configuration
task.inputs.files(krotoConfig)
task.plugins {
id("kroto") {
outputSubDir = "java"
option("ConfigPath=$krotoConfig")
}
}
}
}
}
<plugin>
<groupId>org.xolstice.maven.plugins</groupId>
<artifactId>protobuf-maven-plugin</artifactId>
<version>0.6.1</version>
<configuration>
<protocArtifact>com.google.protobuf:protoc:3.6.1:exe:${os.detected.classifier}</protocArtifact>
</configuration>
<executions>
<execution>
<goals><goal>compile</goal></goals>
</execution>
<execution>
<id>grpc-java</id>
<goals><goal>compile-custom</goal></goals>
<configuration>
<pluginId>grpc-java</pluginId>
<pluginArtifact>io.grpc:protoc-gen-grpc-java:1.17.1:exe:${os.detected.classifier}</pluginArtifact>
</configuration>
</execution>
<execution>
<id>kroto-plus</id>
<goals>
<goal>compile-custom</goal>
</goals>
<configuration>
<pluginId>kroto-plus</pluginId>
<pluginArtifact>com.github.marcoferrer.krotoplus:protoc-gen-kroto-plus:${krotoPlusVersion}:jar:jvm8</pluginArtifact>
<pluginParameter>ConfigPath=${project.basedir}/krotoPlusConfig.asciipb</pluginParameter>
</configuration>
</execution>
</executions>
</plugin>
Supported Formats
The configuration file used by protoc-gen-kroto-plus
allows users to enable and configure any code generator exposed by the plugin. The configuration schema is backed by a protobuf message named CompilerConfig and supports three common formats, JSON, YAML, PROTO Text (asciipb). The following example shows three equivalent configurations, with each being written in a different supported format.
protoBuilders:
- filter:
excludePath:
- google/*
unwrapBuilders: true
useDslMarkers: true
grpcStubExts:
- supportCoroutines: true
grpcCoroutines: [{}]
extendableMessages:
- filter:
excludePath:
- google/*
mockServices:
- implementAsObject: true
generateServiceList: true
serviceListPackage: com.my.package
serviceListName: MyMockServices
generatorScripts:
- scriptPath:
- helloThere.kts
scriptBundle: kp-scripts/build/libs/kp-scripts.jar
insertions:
- entry:
- point: MESSAGE_IMPLEMENTS
content:
- com.my.Interface<{{message_type}}>
- point: BUILDER_IMPLEMENTS
content:
- com.my.Interface<{{message_type}}>
- point: CLASS_SCOPE
scriptPath:
- kp-scripts/src/main/kotlin/extendableMessages.kts
{
"protoBuilders": [
{
"filter": {
"excludePath": ["google/*"]
},
"unwrapBuilders": true,
"useDslMarkers": true
}
],
"grpcStubExts": [
{
"supportCoroutines": true
}
],
"grpcCoroutines": [{}],
"extendableMessages": [
{
"filter": {
"excludePath": ["google/*"]
}
}
],
"mockServices": [
{
"implementAsObject": true,
"generateServiceList": true,
"serviceListPackage": "com.my.package",
"serviceListName": "MyMockServices"
}
],
"generatorScripts": [
{
"scriptPath": ["helloThere.kts"],
"scriptBundle": "kp-scripts/build/libs/kp-scripts.jar"
}
],
"insertions": [
{
"entry": [
{
"point": "MESSAGE_IMPLEMENTS",
"content": ["com.my.Interface<{{message_type}}>"]
},
{
"point": "BUILDER_IMPLEMENTS",
"content": ["com.my.Interface<{{message_type}}>"]
},
{
"point": "CLASS_SCOPE",
"scriptPath": ["kp-scripts/src/main/kotlin/extendableMessages.kts"]
}
]
}
]
}
proto_builders {
filter { exclude_path: "google/*" }
unwrap_builders: true
use_dsl_markers: true
}
grpc_stub_exts {
support_coroutines: true
}
grpc_coroutines { }
generator_scripts {
script_path: "helloThere.kts"
script_bundle: "kp-scripts/build/libs/kp-scripts.jar"
}
insertions {
filter {
include_path: "jojo/bizarre/adventure/character/*"
}
entry {
point: MESSAGE_IMPLEMENTS
script_path: "extendableMessages.kts"
script_bundle: "kp-scripts/build/libs/kp-scripts.jar"
}
entry {
point: BUILDER_IMPLEMENTS
script_path: "extendableMessages.kts"
script_bundle: "kp-scripts/build/libs/kp-scripts.jar"
}
entry {
point: CLASS_SCOPE
script_path: "extendableMessages.kts"
script_bundle: "kp-scripts/build/libs/kp-scripts.jar"
}
entry {
point: OUTER_CLASS_SCOPE
script_path: "kp-scripts/src/main/kotlin/sampleInsertionScript.kts"
}
}
Configuration Schema
CompilerConfig
Message backing the root of a Kroto+ configuration file.
Field | Type | Label | Description |
---|---|---|---|
grpc_stub_exts | GrpcStubExtsGenOptions | repeated | Configuration entries for the gRPC Stub Extensions code generator. |
mock_services | MockServicesGenOptions | repeated | Configuration entries for the Mock Service code generator. |
proto_builders | ProtoBuildersGenOptions | repeated | Configuration entries for the Proto Builders code generator. |
extendable_messages | ExtendableMessagesGenOptions | repeated | Configuration entries for the Extendable Messages code generator. |
insertions | InsertionsGenOptions | repeated | Configuration entries for the Protoc Insertions code generator. |
generator_scripts | GeneratorScriptsGenOptions | repeated | Configuration entries for the Generator Scripts code generator. |
grpc_coroutines | GrpcCoroutinesGenOptions | repeated | Configuration entries for the Grpc Coroutines code generator. |
ExtendableMessagesGenOptions
Configuration used by the Extendable Messages
code generator. Since this code generator relies on the protoc insertion point API, its outputDir must match that of the protoc java plugin.
Field | Type | Label | Description |
---|---|---|---|
filter | FileFilter | Filter used for limiting the input files that are processed by the code generator The default filter will match true against all input files. | |
companion_field_name | string | The name of the field that will hold a reference to the pseudo companion object | |
companion_class_name | string | The name to use for the class declaration of the pseudo companion object | |
companion_extends | string | The FQ name of the class that the pseudo companion object should extend. Currently limited to classes with at least one no-args contructor. Referencing the current message type, use the value {{message_type}} . This is useful when you want to use the current message as a generic type param. ie. com.krotoplus.example.MyCompanionInterface<{{message_type}}, {{message_type}}.Builder> | |
companion_implements | string | The FQ name of an interface the pseudo companion object should implement. Referencing the current message type, use the value {{message_type}} . This is useful when you want to use the current message as a generic type param. ie. com.krotoplus.example.MyCompanionInterface<{{message_type}}, {{message_type}}.Builder> |
FileFilter
Represent a filter used for including and excluding source files from being processed by a code generator. It is inclusive by default, so all paths compared against its default instance will be included as input to a generator and processed.
Field | Type | Label | Description |
---|---|---|---|
include_path | string | repeated | List of file paths to include as inputs for a code generator. A valid value starts from the root package directory of the source file. Globs are supported ie. krotoplus/compiler/config.proto krotoplus/* **/compiler/con.proto |
exclude_path | string | repeated | List of file paths to exclude as inputs for a code generator. a valid value start from the root package directory of the source file. Globs are supported ie. google/* |
GeneratorScriptsGenOptions
Configuration used by the Generator Scripts
code generator.
Field | Type | Label | Description |
---|---|---|---|
filter | FileFilter | Filter used for limiting the input files that are processed by the code generator The default filter will match true against all input files. | |
script_path | string | repeated | List of paths to kotlin script files to execute for this configuration. The scripts are compile at runtime by an embedded kotlin compiler. This comes at the cost of performance. Paths for scripts compiled at run time must be relative to the path of the configuration file. ie. kp-scripts/src/main/kotlin/sampleInsertionScript.kts For a more performant option for script execution, precompiled scripts are supported. Paths for precompile scripts need to match their location in the supplied jar. ie. sampleInsertionScript.kts |
script_bundle | string | Path to the jar containing precompile scripts. |
GrpcCoroutinesGenOptions
Configuration used by the gRPC Coroutines
code generator.
Field | Type | Label | Description |
---|---|---|---|
filter | FileFilter | Filter used for limiting the input files that are processed by the code generator The default filter will match true against all input files. |
GrpcStubExtsGenOptions
Configuration used by the gRPC Stub Extensions
code generator.
Field | Type | Label | Description |
---|---|---|---|
filter | FileFilter | Filter used for limiting the input files that are processed by the code generator The default filter will match true against all input files. | |
support_coroutines | bool | Enable code generation for coroutine supporting service stub extensions. This options generates code that relies on the artifact kroto-plus-coroutines |
InsertionsGenOptions
Configuration used by the Protoc Insertions
code generator. Since this code generator relies on the protoc insertion point API, its outputDir must match that of the protoc java plugin.
Field | Type | Label | Description |
---|---|---|---|
filter | FileFilter | Filter used for limiting the input files that are processed by the code generator The default filter will match true against all input files. | |
entry | InsertionsGenOptions.Entry | repeated | List of configurations to be applied to the file filter. |
InsertionsGenOptions.Entry
Configuration to apply to the files matched by the file filter.
Field | Type | Label | Description |
---|---|---|---|
point | InsertionPoint | The protoc insertion point at which the generated code will be inserted. | |
content | string | repeated | String literal of content to be set at the insertion point. Referencing the current message type, use the value {{message_type}} . This is useful when you want to use the current message as a generic type param. ie. com.krotoplus.example.MyCompanionInterface<{{message_type}}, {{message_type}}.Builder> |
script_path | string | repeated | List of paths to kotlin script files to execute for this configuration. The scripts are compile at runtime by an embedded kotlin compiler. This comes at the cost of performance.Paths for scripts compiled at run time must be relative to the path of the configuration file. ie. kp-scripts/src/main/kotlin/sampleInsertionScript.kts For a more performant option for script execution, precompiled scripts are supported. Paths for precompile scripts need to match their location in the supplied jar. ie. sampleInsertionScript.kts |
script_bundle | string | Path to the jar containing precompile scripts. |
MockServicesGenOptions
Configuration used by the Mock Services
code generator.
Field | Type | Label | Description |
---|---|---|---|
filter | FileFilter | Filter used for limiting the input files that are processed by the code generator The default filter will match true against all input files. | |
implement_as_object | bool | By default, mock services are generated as an open class but an object can be generated instead. | |
generate_service_list | bool | Flag for generating a static collection of the Mock Services created. Useful when registering mock services to a GrpcServerRule during unit tests. | |
service_list_package | string | The java package at which the mock server list should reside. | |
service_list_name | string | The name of the property at which the mock server list will be initialized at. |
ProtoBuildersGenOptions
Configuration used by the Proto Builders
code generator.
Field | Type | Label | Description |
---|---|---|---|
filter | FileFilter | Filter used for limiting the input files that are processed by the code generator The default filter will match true against all input files. | |
unwrap_builders | bool | By default the generated utility methods for building messages are wrapped in an object similar to a proto outer class. For better ergonomics with code generated using java_multiple_files = false the builders can be unwrapped and generated at the root scope of the output file. This option is not compatible with java_multiple_files = true and nested messages since the generated code would produce class name collisions | |
use_dsl_markers | bool | Tag java builder classes with a kotlin interface annotated with @DslMarker. This requires the kroto-plus output directory to match the generated java classes directory. Using @DslMarker provides safer and predictable dsl usage. |
InsertionPoint
Name | Number | Description |
---|---|---|
UNKNOWN | 0 | |
INTERFACE_EXTENDS | 1 | |
MESSAGE_IMPLEMENTS | 2 | |
BUILDER_IMPLEMENTS | 3 | |
BUILDER_SCOPE | 4 | |
CLASS_SCOPE | 5 | |
ENUM_SCOPE | 6 | |
OUTER_CLASS_SCOPE | 7 |
Scalar Value Types
.proto Type | Notes | C++ Type | Java Type | Python Type |
---|---|---|---|---|
double | double | double | float | |
float | float | float | float | |
int32 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. | int32 | int | int |
int64 | Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. | int64 | long | int/long |
uint32 | Uses variable-length encoding. | uint32 | int | int/long |
uint64 | Uses variable-length encoding. | uint64 | long | int/long |
sint32 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. | int32 | int | int |
sint64 | Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. | int64 | long | int/long |
fixed32 | Always four bytes. More efficient than uint32 if values are often greater than 2^28. | uint32 | int | int |
fixed64 | Always eight bytes. More efficient than uint64 if values are often greater than 2^56. | uint64 | long | int/long |
sfixed32 | Always four bytes. | int32 | int | int |
sfixed64 | Always eight bytes. | int64 | long | int/long |
bool | bool | boolean | boolean | |
string | A string must always contain UTF-8 encoded or 7-bit ASCII text. | string | String | str/unicode |
bytes | May contain any arbitrary sequence of bytes. | string | ByteString | str |
Updated almost 5 years ago