View on GitHub

ScalaPB

Protocol Buffer Compiler for Scala

ScalaPB

ScalaPB is a protocol buffer compiler (protoc) plugin for Scala. It will generate Scala case classes, parsers and serializers for your protocol buffers.

ScalaPB is hosted on Github.

Main features

  • Built on top of Google’s protocol buffer compiler to ensure perfect compatibility with the language specification.

  • Supports both proto2 and proto3.

  • Nested updates are easy by using lenses:

val newOrder = order.update(_.creditCard.expirationYear := 2015)
  • Generated case classes can co-exist alongside the Java-generated code (the class names will not clash). This allows gradual transition from Java to Scala.

  • Can optionally generate conversion methods between the Java generated version of Protocol Buffers to the Scala generated version. This makes it possible to migrate your project gradually.

  • New: Supports for Oneof’s that were introduced in Protocol Buffers 2.6.0.

  • Newer: Supports Scala.js (in 0.5.x).

  • Newer Supports gRPC (in 0.5.x).

  • Newest: Supports SparkSQL (in 0.5.23).

  • Newest: Supports converting to and from JSON (in 0.5.x).

  • Newest: Supports User-defined options (in 0.5.29).

To automatically generate Scala case classes for your messages add ScalaPB’s sbt plugin to your project. Create a file named project/scalapb.sbt containing the following line:

addSbtPlugin("com.thesamet" % "sbt-protoc" % "0.99.11")

libraryDependencies += "com.trueaccord.scalapb" %% "compilerplugin" % "0.6.2"

Add the following line to your build.sbt:

PB.targets in Compile := Seq(
  scalapb.gen() -> (sourceManaged in Compile).value
)

// (optional) If you need scalapb/scalapb.proto or anything from
// google/protobuf/*.proto
libraryDependencies += "com.trueaccord.scalapb" %% "scalapb-runtime" % com.trueaccord.scalapb.compiler.Version.scalapbVersion % "protobuf"

ScalaPB looks for protocol buffer files in src/main/protobuf, but this can be customized. Running the compile command in sbt will both generate Scala sources from your protos and compile them.

For additional configuration options, see ScalaPB SBT Settings.

Running Standalone Using spbc

If you would like to compile protocol buffers into Scala outside SBT, you can use spbc (ScalaPB compiler).

The first step, is to download the latest version from the ScalaPB releases page on Github.

Unzip the file, and inside you will find two scripts: bin/spbc (and bin/spbc.bat) that can be used on Unix/Linux/Mac OS X (and Windows, respectively).

spbc is used exactly like protoc. In fact, spbc calls protoc, though it passes to it a script that serves as the Scala plugin. Here is an example command line to invoke it:

bin/spbc my.proto --scala_out=.

If you would like to pass additional options, like java_conversions, flat_package, or single_line_to_string, it can be done like this:

bin/spbc my.proto --scala_out=OPT1,OPT2:path/to/output/dir/

where OPT1,OPT2 is a comma-separated list of options. For example:

bin/spbc my.proto --scala_out=flat_package,java_conversions:.

Questions? Comments?

Feel free to post to our mailing list. Found a bug? Missing a feature? Report on Github.

Next:

Read about the Generated Code.