Kroto+

The Kroto+ Developer Hub

Welcome to the Kroto+ developer hub. You'll find comprehensive guides and documentation to help you start working with Kroto+ as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

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.

FieldTypeLabelDescription
grpc_stub_extsGrpcStubExtsGenOptionsrepeatedConfiguration entries for the gRPC Stub Extensions code generator.
mock_servicesMockServicesGenOptionsrepeatedConfiguration entries for the Mock Service code generator.
proto_buildersProtoBuildersGenOptionsrepeatedConfiguration entries for the Proto Builders code generator.
extendable_messagesExtendableMessagesGenOptionsrepeatedConfiguration entries for the Extendable Messages code generator.
insertionsInsertionsGenOptionsrepeatedConfiguration entries for the Protoc Insertions code generator.
generator_scriptsGeneratorScriptsGenOptionsrepeatedConfiguration entries for the Generator Scripts code generator.
grpc_coroutinesGrpcCoroutinesGenOptionsrepeatedConfiguration 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.

FieldTypeLabelDescription
filterFileFilterFilter 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_namestringThe name of the field that will hold a reference to the pseudo companion object
companion_class_namestringThe name to use for the class declaration of the pseudo companion object
companion_extendsstringThe 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_implementsstringThe 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.

FieldTypeLabelDescription
include_pathstringrepeatedList 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_pathstringrepeatedList 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.

FieldTypeLabelDescription
filterFileFilterFilter used for limiting the input files that are processed by the code generator The default filter will match true against all input files.
script_pathstringrepeatedList 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_bundlestringPath to the jar containing precompile scripts.

GrpcCoroutinesGenOptions

Configuration used by the gRPC Coroutines code generator.

FieldTypeLabelDescription
filterFileFilterFilter 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.

FieldTypeLabelDescription
filterFileFilterFilter used for limiting the input files that are processed by the code generator The default filter will match true against all input files.
support_coroutinesboolEnable 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.

FieldTypeLabelDescription
filterFileFilterFilter used for limiting the input files that are processed by the code generator The default filter will match true against all input files.
entryInsertionsGenOptions.EntryrepeatedList of configurations to be applied to the file filter.

InsertionsGenOptions.Entry

Configuration to apply to the files matched by the file filter.

FieldTypeLabelDescription
pointInsertionPointThe protoc insertion point at which the generated code will be inserted.
contentstringrepeatedString 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_pathstringrepeatedList 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_bundlestringPath to the jar containing precompile scripts.

MockServicesGenOptions

Configuration used by the Mock Services code generator.

FieldTypeLabelDescription
filterFileFilterFilter 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_objectboolBy default, mock services are generated as an open class but an object can be generated instead.
generate_service_listboolFlag for generating a static collection of the Mock Services created. Useful when registering mock services to a GrpcServerRule during unit tests.
service_list_packagestringThe java package at which the mock server list should reside.
service_list_namestringThe name of the property at which the mock server list will be initialized at.

ProtoBuildersGenOptions

Configuration used by the Proto Builders code generator.

FieldTypeLabelDescription
filterFileFilterFilter used for limiting the input files that are processed by the code generator The default filter will match true against all input files.
unwrap_buildersboolBy 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_markersboolTag 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

NameNumberDescription
UNKNOWN0
INTERFACE_EXTENDS1
MESSAGE_IMPLEMENTS2
BUILDER_IMPLEMENTS3
BUILDER_SCOPE4
CLASS_SCOPE5
ENUM_SCOPE6
OUTER_CLASS_SCOPE7

Scalar Value Types

.proto TypeNotesC++ TypeJava TypePython Type
doubledoubledoublefloat
floatfloatfloatfloat
int32Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead.int32intint
int64Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead.int64longint/long
uint32Uses variable-length encoding.uint32intint/long
uint64Uses variable-length encoding.uint64longint/long
sint32Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s.int32intint
sint64Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s.int64longint/long
fixed32Always four bytes. More efficient than uint32 if values are often greater than 2^28.uint32intint
fixed64Always eight bytes. More efficient than uint64 if values are often greater than 2^56.uint64longint/long
sfixed32Always four bytes.int32intint
sfixed64Always eight bytes.int64longint/long
boolboolbooleanboolean
stringA string must always contain UTF-8 encoded or 7-bit ASCII text.stringStringstr/unicode
bytesMay contain any arbitrary sequence of bytes.stringByteStringstr

Updated about a year ago

Configuration File


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.