sbt

To add the sbt plugin and Akka gRPC dependencies to a project

// in project/plugins.sbt:
resolvers += "Akka library repository".at("https://repo.akka.io/<your token>/secure")
addSbtPlugin("com.lightbend.akka.grpc" % "sbt-akka-grpc" % "2.5.11")
//
// in build.sbt:
resolvers += "Akka library repository".at("resolvers += "Akka library repository".at("https://repo.akka.io/<your token>/secure")")
enablePlugins(AkkaGrpcPlugin)

For a step by step getting started with Akka gRPC read the client or server introductions.

Configuring what to generate

It can be configured to just generate either server or client like so:

copysource// 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:

copysource* // 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")

Filtering generated services

You can filter which services to generate client or server code for independently, using include and exclude glob patterns. The patterns match against the full gRPC service name (e.g., com.example.MyService).

// Only generate client code for services matching these patterns
akkaGrpcClientInclude := Seq("com.example.*", "com.myapp.MyService")

// Exclude services from client code generation (applied after include)
akkaGrpcClientExclude := Seq("com.example.internal.*")

// Only generate server code for services matching these patterns
akkaGrpcServerInclude := Seq("com.example.MyService")

// Exclude services from server code generation (applied after include)
akkaGrpcServerExclude := Seq("com.example.internal.*")

The trait/interface is generated for any service that passes either the client or server filter.

If include is empty, all services are included. The exclude patterns are applied to the result of include.

Examples: - * matches any service name - com.example.* matches any service whose name starts with com.example. (including services in nested packages such as com.example.sub.MyService, since * matches across .) - com.example.MyService matches a specific service

Patterns must not contain commas (the brace-alternation syntax {A,B} is therefore not supported). To match several explicit names, list them as separate entries:

akkaGrpcServerInclude := Seq("com.example.Foo", "com.example.Bar")

Configurations

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:

copysourceTest / 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:

copysourceconfigs(IntegrationTest)
Defaults.itSettings
AkkaGrpcPlugin.configSettings(IntegrationTest)

IntegrationTest / akkaGrpcGeneratedLanguages := Seq(AkkaGrpc.Java)
IntegrationTest / PB.protoSources ++= (Compile / PB.protoSources).value

Generating server “power APIs”

To additionally generate server “power APIs” that have access to request metadata, as described here, set the server_power_apis option:

akkaGrpcCodeGeneratorSettings += "server_power_apis"

Passing parameters to the generators

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.

ScalaPB settings

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 flat_package parameter.

akkaGrpcCodeGeneratorSettings += "single_line_to_proto_string"

Using a local protoc command

Akka gRPC uses the protoc tool to pass .proto definitions to various code generation components, via ScalaPB’s sbt-protoc and protoc-jar. This will automatically download the right protoc for your system during the build.

If protoc-jar fails to download protoc for your system, for example because it is not available for your architecture or due to network restrictions, you can explicitly specify a local protoc executable instead:

PB.protocExecutable := file("/usr/local/bin/protoc")

Available parameters are listed in the ScalaPB documentation.

sbt-protoc settings

To tune the sbt-protoc additional options such as the proto source directory you can configure them like this:

  .settings(
    inConfig(Compile)(Seq(
      PB.generate / excludeFilter := "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/protobuf (and src/main/proto). You can configure where your .proto files are located like this:

// "Compile / sourceDirectory" is "src/main", so this adds "src/main/proto_custom":
inConfig(Compile)(Seq(
  PB.protoSources += sourceDirectory.value / "proto_custom"
))

Loading proto files from artifacts

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

Starting your Akka gRPC server from sbt

You can start your gRPC application as usual with:

sbt "runMain io.grpc.examples.helloworld.GreeterServer"