It can be configured to just generate either server or client like so:
// This is the default - both client and server akkaGrpcGeneratedSources := Seq(AkkaGrpc.Client, AkkaGrpc.Server) // only client akkaGrpcGeneratedSources := Seq(AkkaGrpc.Client) // only server akkaGrpcGeneratedSources := Seq(AkkaGrpc.Server)
What language to generate stubs for is also configurable:
// default is Scala only akkaGrpcGeneratedLanguages := Seq(AkkaGrpc.Scala) // Java only akkaGrpcGeneratedLanguages := Seq(AkkaGrpc.Java) // Generate both Java and Scala API's. // By default the 'flat_package' option is enabled so that generated // package names are consistent between Scala and Java. // With both languages enabled we disable that option to avoid name conflicts akkaGrpcGeneratedLanguages := Seq(AkkaGrpc.Scala, AkkaGrpc.Java) akkaGrpcCodeGeneratorSettings := akkaGrpcCodeGeneratorSettings.value.filterNot(_ == "flat_package")
By default, the plugin will run generators against
.proto sources in the
Compile directories (
src/main/protobuf), as well as the
Test ones (
src/test/protobuf) if there are any.
The settings documented above can have different values for each configuration, allowing you for example to generate in
Test (and in
Test only) client stubs for a service defined in
Compile. If you want to do this, you have to inherit the
.proto definitions from
Compile over to
Test / akkaGrpcGeneratedSources := Seq(AkkaGrpc.Client) Test / PB.protoSources ++= (Compile / PB.protoSources).value
If you have other configurations with
.proto sources (for example
IntegrationTest), you must first declare them and enable the plugin on them:
configs(IntegrationTest) Defaults.itSettings AkkaGrpcPlugin.configSettings(IntegrationTest) IntegrationTest / akkaGrpcGeneratedLanguages := Seq(AkkaGrpc.Java) IntegrationTest / PB.protoSources ++= (Compile / PB.protoSources).value
To additionally generate server “power APIs” that have access to request metadata, as described here, set the
akkaGrpcCodeGeneratorSettings += "server_power_apis"
The sbt plugin for Akka-gRPC uses ScalaPB and
sbt-protoc. It is possible to tune these libraries if the provided defaults don’t suit your needs.
Passing generator parameters to the underlying ScalaPB generators can be done through
akkaGrpcCodeGeneratorSettings setting, any specified options will be passed to all underlying generators that are enabled. By default this setting contains the
akkaGrpcCodeGeneratorSettings += "single_line_to_proto_string"
Available parameters are listed in the ScalaPB documentation.
To tune the
sbt-protoc additional options such as the proto source directory you can configure them like this:
.settings( inConfig(Compile)(Seq( excludeFilter in PB.generate := "descriptor.proto" )) )
The above, for example, removes
descriptor.proto from the list of files to be processed.
By default protobuf files are looked for in
src/main/proto). You can configure where your
.proto files are located like this:
// "sourceDirectory in Compile" is "src/main", so this adds "src/main/proto_custom": inConfig(Compile)(Seq( PB.protoSources += sourceDirectory.value / "proto_custom" ))
Instead of duplicating the
.proto definitions between server and client projects, you can add artifacts that contain proto definitions to your build:
libraryDependencies += "com.example" %% "my-grpc-service" % "1.0.0" % "protobuf-src"
This adds just the
.proto resources to the build, so code generation can happen locally in your project.
It is also possible to add the
.proto resources as ‘external’ includes, assuming that the artifact also contains the correct generated classes for this API. This is not always possible, since the upstream artifact may not contain any generated classes or may contain classes that were were generated in a way that is incompatible with your intended use. To include an artifact as an external protobuf source, add it like:
libraryDependencies += "com.example" %% "my-grpc-service" % "1.0.0" % "protobuf"
If you want to use TLS-based negotiation on JDK 8 versions prior to 1.8.0_251, the server requires a special Java agent for ALPN.
See the Akka HTTP docs about HTTP/2) for more information.
You can start your gRPC application as usual with: