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	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	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	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