Gradle

To get started with Pekko gRPC, read the client or server introductions.

Configuring plugin

This plugin is a wrapper for protobuf-gradle-plugin and uses it for .proto files processing and code generation. Most of the settings could be configured using related setting of protobuf-gradle-plugin itself. Consult protobuf-gradle-plugin documentation for details.

The plugin can generate either Java or Scala classes, and then server and or client for the corresponding language. By default, both client and server are generated and Java or Scala is autodetected depending on the presence of source files with language extension in src/main.

Installation

To consume this plugin, you will need to update the consuming project’s build.gradle to include the mavenCentral repository.

pluginManagement {
    repositories {
        gradlePluginPortal()
        mavenCentral()
    }
}

Available plugin options

Following options are available for configuring the plugin code generation. Names and default values are provided.

build.gradle
pekkoGrpc {
    generateClient = true
    generateServer = true
    generatePlay = false
    usePlayActions = false
    serverPowerApis = false
    scala3Sources = false
    extraGenerators = []
}

Generating server “power APIs”

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

build.gradle
pekkoGrpc {
  ...
  serverPowerApis = true
}

Generating Scala 3 sources

For Scala projects, set scala3Sources to generate Scala 3-friendly sources:

build.gradle
pekkoGrpc {
  ...
  scala3Sources = true
}

Protoc version

The version and the location of protoc can be changed using protobuf-gradle-plugin settings.

Proto source directory

By default the plugin looks for .proto files under

  • src/main/protobuf
  • src/main/proto
  • app/protobuf
  • app/proto

Loading .proto files from other directories could be configured using settings of protobuf-gradle-plugin.

Loading proto files from artifacts

In gRPC it is common to make the version of the protocol you are supporting explicit by duplicating the proto definitions in your project.

This is supported by protobuf-gradle-plugin and explained here.

JDK support

Pekko gRPC requires JDK 17 or later. ALPN support is built into the supported JDKs; no external ALPN agent is required.

Starting your Pekko gRPC server from gradle

Build script needs a custom task

build.gradle
task runServer(type: JavaExec) {
  classpath = sourceSets.main.runtimeClasspath
  main = 'com.example.helloworld.GreeterServer'
}

Then, the server can then be started from the command line with:

./gradlew runServer

Play Framework support

See the Play gRPC documentation for details.