diff options
Diffstat (limited to 'docs/pages/9 - Contrib Modules.md')
-rw-r--r-- | docs/pages/9 - Contrib Modules.md | 51 |
1 files changed, 51 insertions, 0 deletions
diff --git a/docs/pages/9 - Contrib Modules.md b/docs/pages/9 - Contrib Modules.md new file mode 100644 index 00000000..0360cc75 --- /dev/null +++ b/docs/pages/9 - Contrib Modules.md @@ -0,0 +1,51 @@ +## Contrib Modules + +### ScalaPB + +This module allows [ScalaPB](https://scalapb.github.io) to be used in Mill builds. ScalaPB is a [Protocol Buffers](https://developers.google.com/protocol-buffers/) compiler plugin that generates Scala case classes, encoders and decoders for protobuf messages. + +To declare a module that uses ScalaPB you can extend the `mill.contrib.scalapblib.ScalaPBModule` trait when defining your module. + +This creates a Scala module which compiles `.proto` files in the `protobuf` folder of the module with ScalaPB and adds the resulting `.scala` sources to your module's `generatedSources`. + +```scala +// build.sc +import mill._, scalalib._, contrib.scalapblib.__ + +object example extends ScalaPBModule { + def scalaVersion = "2.12.6" + def scalaPBVersion = "0.7.4" +} +``` + +This defines a project with the following layout: + +``` +build.sc +example/ + src/ + protobuf/ + resources/ +``` + +#### Configuration options + +* scalaPBVersion (mandatory) - The ScalaPB version `String` e.g. `"0.7.4"` + +* scalaPBFlatPackage - A `Boolean` option which determines whether the `.proto` file name should be appended as the final segment of the package name in the generated sources. + +* scalaPBJavaConversions - A `Boolean` option which determines whether methods for converting between the generated Scala classes and the Protocol Buffers Java API classes should be generated. + +* scalaPBGrpc - A `Boolean` option which determines whether [grpc](https://grpc.io) stubs should be generated. + +* scalaPBSingleLineToProtoString - A `Boolean` option which determines whether the generated `.toString` methods should use a single line format. + +If you'd like to configure the options that are passed to the ScalaPB compiler directly, you can override the `scalaPBOptions` task, for example: + +```scala +object example extends ScalaPBModule { + def scalaVersion = "2.12.6" + def scalaPBVersion = "0.7.4" + override def scalaPBOptions = "flat_package,java_conversions" +} +``` |