Protobuf compatibility findings and suggestions

[mbland]

As a side quest to #1482, I've been experimenting with trying to update the Protobuf library beyond version 21.7, released 2022-09-29. The reason is that I anticipate potential complications after the Bzlmod update lands if users have later Protobuf versions in their MODULE.bazel dependency graph.

I've discovered the following details, which we may need to communicate to users through release notes and/or other documentation. Here are the combinations of various dependencies that work with one another. The first row is the current combination.

Protobuf	abseil-cpp	Bazel 6	ScalaPB	Scala
v21.7	20220623.1	✅	0.9.0	All
v21.7	20220623.1	✅	0.9.8	All
v21.7	20220623.1	✅	0.11.17	>= 2.12
v25.5	20240722.0	with --cxxopt	0.9.8	All
v25.5	20240722.0	with --cxxopt	0.11.17	>= 2.12
>= v28.2	20240722.0	with --cxxopt	1.0.0-alpha.1	>= 2.12

Suggestions

I'd suggest updating the .bazelversion to 7.4.0 and bumping Protobuf to v25.5. My reasoning is that these changes would bring rules_scala closer to recent Bazel and Protobuf updates, without potentially breaking existing users.

If we decide to build with Bazel 7 by default instead of Bazel 6, the Protobuf recompilation sensitivity won't be as much of an issue. In my experience, after merging #1619, #1620, and #1622, I haven't found any other Bazel 6 and 7 incompatibilities outside of building newer Protobuf versions.

It would be nice to bump to ScalaPB 1.0.0-alpha.1 to use the latest Protobuf v28.3. However, it seems like that might be too big a bump for existing users right now.

Takeaways

ScalaPB and the scala_proto_aspect are sensitive to the Protobuf version

The scala_proto_library rule uses an aspect that delegates to the protoc-bridge generator framework to generate code. protoc-bridge itself isn't very sensitive, but the ScalaPB.ScalaPbCodeGenerator implementations to which it delegates are very sensitive to the Protobuf library version.

See the protoc-bridge explanation section below for details on why this is the case.

The Protobuf Bazel module remaining at compatibility_level 1 is a problem

All current versions of the Protobuf Bazel module, from before 21.7 and up to the current 29.0-rc2.bcr.1, have a compatibility_level of 1. This means that all modules in the Bzlmod/MODULE.bazel dependency graph will resolve to a single Protobuf version, regardless of its major version number.

This means that rules_scala locks scala_proto users to the maximum Protobuf version that it supports (or to a minimum of v28.2 with ScalaPB 1.0.0-alpha.1). While already true when using WORKSPACE, this will also be the case under Bzlmod, until a Protobuf module release with a different compatibility_level.

Protobuf >= v22 requires C++14 or greater, --cxxopt flags in Bazel 6

Protobuf v22 dropped C++11 support, requiring C++14 or greater. This corresponds to the update in abseil-cpp from 20220623.2, the last to support C++11, to 20230125.0, the first to require C++14.

This is not a problem for Bazel 7. Bazel 6, however, does not use a C++14 or greater toolchain out of the box.

To build these more recent versions of abseil-cpp and Protobuf under Bazel 6, I've added these .bazelrc flags from bazelbuild/bazel#20785 in commit 03d4e20 from mbland/rules_scala:

build:linux --cxxopt=-std=c++17
build:linux --host_cxxopt=-std=c++17
build:macos --cxxopt=-std=c++17
build:macos --host_cxxopt=-std=c++17
build:windows --cxxopt=/std=c++17
build:windows --host_cxxopt=/std=c++17

--cxxopt flags in Bazel 6 cause Protobuf to rebuild more frequently

Protobuf is already notoriously sensitive to recompilation.

• Stack Overflow: bazel recompiles protobuf more than necessary suggests a sensitivity to build config flags in particular.
• Protobuf repo recompilation sensitivity bazel#7095 explains the sensitivity of C++ toolchains in general to PATH, not just the Protobuf toolchain.

This recompilation became so bad, I thought test_scalafmt from test_cross_build.sh was hanging. It was actually recompiling Protobuf on every bazel run invocation. (I've since filed #1646 to resolve this.)

Protobuf v25.5 is the highest version compatible with ScalaPB 0.9.8, 0.11.17

I was able to confirm this by iterating through different configurations of the test_scala_version test case from test_version.sh. I used the RULES_SCALA_TEST_ONLY environment variable from #1646 and the test_version.sh changes from commit ff1a079 from mbland/rules_scala to do this fairly easily.

There is no combination that works with Protobuf v26 or v27

I was able to confirm this using the same methodolgy...

No Protobuf version < v28.2 works with ScalaPB 1.0.0-alpha.1

...as I was able to confirm this as well.

Working branches

I was able to reach the above conclusions by building up changes in the following branches:

• bzlmod-update-protocbridge-and-grpc: bumps ScalaPB to 0.9.8 for Scala 2.11 and 0.11.17 for Scala 2.12 and above
• bzlmod-update-abseil-cpp-and-protobuf:
  • first bumps Protobuf to v25.5 and abseil-cpp to 20240722.0, with Bazel 6 compiler flags in .bazelrc
  • then bumps ScalaPB to 1.0.0-alpha.1 and Protobuf to v28.3

protoc-bridge explanation

scala_proto_library uses scala_proto_aspect, which uses the scripts.ScalaPBWorker class from src/scala/scripts/ScalaPBWorker.scala, which calls ProtocBridge.runWithGenerators. This function ultimately runs generator classes in separate threads via Futures. It then runs protoc with --plugin flags pointing at shell wrappers communicating with these generator Futures over a local pipe.

The ScalaPB jars required by the generators (not so much the protoc-bridge framework itself) must be compatible with the current Protobuf library version. Not just with the protobuf-java Maven artifact, which can be a new as you like, but with the build's actual Protobuf repository that provides protoc. Otherwise, ScalaPB code will throw exceptions like java.lang.NoSuchMethodError or java.lang.IllegalAccessError.

For example, from the #1624 commit message:

Exception in thread "main" java.lang.NoSuchMethodError:
  'boolean com.google.protobuf.GeneratedMessageV3.isStringEmpty(java.lang.Object)'

From the #1630 commit message:

--jvm_extra_protobuf_generator_out: java.lang.NoSuchMethodError:
  'java.lang.Object com.google.protobuf.DescriptorProtos$MessageOptions.getExtension(com.google.protobuf.GeneratedMessage$GeneratedExtension)'
    at scalapb.compiler.DescriptorImplicits$ExtendedMessageDescriptor.messageOptions(DescriptorImplicits.scala:532)

From the #1637 commit message:

--jvm_extra_protobuf_generator_out: java.lang.IllegalAccessError:
  class scalapb.options.Scalapb$ScalaPbOptions tried to access method
  'com.google.protobuf.LazyStringArrayList
    com.google.protobuf.LazyStringArrayList.emptyList()'
  (scalapb.options.Scalapb$ScalaPbOptions and
   com.google.protobuf.LazyStringArrayList are in unnamed module
   of loader 'app')

From commit 6f702a6 from mbland/rules_scala, which I plan to submit when bumping to ScalaPB 0.11.17:

--scala_out: java.lang.NoSuchMethodError:
  'void com.google.protobuf.Descriptors$FileDescriptor.internalBuildGeneratedFileFrom(java.lang.String[],
    com.google.protobuf.Descriptors$FileDescriptor[],
    com.google.protobuf.Descriptors$FileDescriptor$InternalDescriptorAssigner)'
      at scalapb.options.compiler.Scalapb.<clinit>(Scalapb.java:10592)

The changes from #1637 and the last commit above catch ScalaPB generator exceptions and return the stack trace as a proper error response. This is how I collected the stack traces above. Without these changes, the build hangs on uncaught exceptions, since the scripts.ScalaPBWorker will wait forever for a dead generator to respond.

Here's an example of a scripts.ScalaPBWorker command generated when building scala_proto_library targets in //test/proto/..., with long path prefixes and many jar paths elided:

.../scalapb_worker.runfiles/io_bazel_rules_scala/../remotejdk11_.../bin/java
  -classpath
    .../io_bazel_rules_scala/src/scala/scripts/scalapb_worker.jar:
    .../io_bazel_rules_scala/src/scala/scripts/scalapb_worker_lib.jar:
    [ ...protobuf, core Scala, and ScalaPB jars... ]
  -DGEN_jvm_extra_protobuf_generator=
   scalarules.test.extra_protobuf_generator.ExtraProtobufGenerator
  -DGEN_scala=scripts.ScalaPbCodeGenerator
  -DPROTOC=bazel-out/.../bin/external/com_google_protobuf/protoc
  -DJARS=
    .../bin/test/src/main/scala/scalarules/test/extra_protobuf_generator/extra_protobuf_generator.jar:
    [ ...protobuf, core Scala, and ScalaPB jars... ]
  scripts.ScalaPBWorker --persistent_worker

The scripts.ScalaPBWorker class calling ProtocBridge.runWithGenerators launches protoc processes like this, with $VARDIR representing the generated /var path:

bazel-out/.../bin/external/com_google_protobuf/protoc
  --plugin=protoc-gen-scala=$VARDIR/protocbridge11068409970088580527
  --plugin=protoc-gen-jvm_extra_protobuf_generator=
    $VARDIR/protocbridge7908074065015031242
  --jvm_extra_protobuf_generator_out
    bazel-out/.../bin/test/proto/
    test2_jvm_extra_protobuf_generator_scalapb.srcjar
  --jvm_extra_protobuf_generator_opt grpc,single_line_to_proto_string
  --scala_out bazel-out/.../bin/test/proto/test2_scala_scalapb.srcjar
  --scala_opt grpc,single_line_to_proto_string
  --descriptor_set_in
    bazel-out/.../bin/test/proto2/test-descriptor-set.proto.bin:
    bazel-out/.../bin/test/proto/test2-descriptor-set.proto.bin
  test/proto/test2.proto

Notice the --plugin= flags above, which specify scripts generated by protoc-bridge that look like this:

#!/bin/sh
set -e
cat /dev/stdin > "$VARDIR/protopipe-14656650241271353812/input"
cat "$VARDIR/protopipe-14656650241271353812/output"

This command will show the scripts.ScalaPBWorker parent process, all the plugin script child processes, and the cat "$VARDIR/protopipe-.../output" grandchild processes if they're still running:

ps -ef | grep -E '[p]roto(cbridge|pipe)'

Without the aforementioned changes, you have to kill the build with CTRL-C when it hangs. bazel shutdown will then clean up the processes that haven't yet become zombified, but such zombified processes must be cleaned up with:

ps -ef | grep -E '[p]roto(cbridge|pipe)' | awk '{print $2}' | xargs kill

[mbland]

I just ran a small experiment to confirm my understanding of how potential Bzlmod users could accommodate our Protobuf dependency and theirs, whereby they rely on a version that isn't currently compatible with rules_scala. The mechanism relies on:

• the repo_name parameter of bazel_dep
• the multiple_version_override directive

I created a new repo consisting of only the following three files:

.bazelversion (for Bazelisk):

7.4.1

MODULE.bazel:

module(name = "multiple-module-repo-experiment")

bazel_dep(
    name = "protobuf",
    version = "21.7",
    repo_name = "com_google_protobuf",
)

bazel_dep(
    name = "protobuf",
    version = "28.3",
)

multiple_version_override(
    module_name = "protobuf",
    versions = ["21.7", "28.3"],
)

BUILD:

load("@com_google_protobuf//:protobuf.bzl", "cc_proto_library")
load("@protobuf//bazel:proto_library.bzl", "proto_library")

This builds successfully and produces the following repos:

$ ls -ld "$(bazel info output_base)"/external/protobuf*
drwxr-xr-x  54 user  group  1728 Nov 19 14:18 .../external/protobuf~v21.7/
drwxr-xr-x  66 user  group  2112 Nov 19 14:18 .../external/protobuf~v28.3/

So we'd need to put in the release notes or documentation something like the following:

• If your repository doesn't use Protobuf, uses Protobuf v21.7 to v25.5, or doesn't use the scala_proto or scalafmt toolchains from rules_scala, there's nothing to do.
• Projects using Protobuf v26 and higher must use something like the MODULE.bazel stanza above to accommodate both its own required Protobuf version and that required by rules_scala.
• The bazel_dep for the rules_scala version must specify repo_name = "com_google_protobuf", or some other name not used by the host project.
• Per the multiple_version_override documentation, this only applies to the main repository; it does not convey to other repositories that depend on the repository using the multiple_version_override.

---

I also confirmed that multiple_version_override would be required even if the compatibility_level of the Protobuf module versions were different. I extended my experiment to try it with rules_erlang. I added the following to MODULE.bazel:

bazel_dep(
    name = "rules_erlang",
    version = "2.5.2",
    repo_name = "rules_erlang_v2",
)

bazel_dep(
    name = "rules_erlang",
    version = "3.16.0",
)

and the following to BUILD:

load("@rules_erlang_v2//:erlang_app.bzl", "test_erlang_app")
load("@rules_erlang//:erlang_app.bzl", "erlang_app")

Without multiple_version_override, the build failed with:

$ bazel build //:all                                                                          

ERROR: Error computing the main repository mapping:
  <root> depends on [email protected] with compatibility level 3,
  but <root> depends on [email protected] with compatibility level 2
  which is different                           

Then I added the following to MODULE.bazel, and it worked:

multiple_version_override(
    module_name = "rules_erlang",
    versions = ["2.5.2", "3.16.0"],
)

And we can see the different repo versions in this case, too:

$ ls -ld "$(bazel info output_base)"/external/rules_erlang*

drwxr-xr-x  34 user  group  1088 Nov 19 16:07 .../external/rules_erlang~v2.5.2/
drwxr-xr-x  60 user  group  1920 Nov 19 16:07 .../external/rules_erlang~v3.16.0/

---

At least in the rules_erlang case, where the compatibility_levels were different, we got an error message up front pointing at the problem. Without it, we potentially have to decipher a cryptic build breakage and diagnose the root cause, as I demonstrated in the original issue description.

[mbland]

Just filed scalapb/ScalaPB#1771 to see about applying fixes upstream to avoid scalapb.ScalaPbCodeGenerator hangs.

[mbland]

Bazel 8 further complicates things. See #1652 for details, and bazelbuild/bazel#24235 for a cross reference.

Repeating most of my summary from the latter issue for convenience:

Most of the Bazel 8 and rules_java 8 incompatibilities can be easily addressed once Bzlmodification lands, and what I think is the only remaining one may be resolved by a protobuf-java:4.29.0 release (without -RC2).

The tradeoffs are that users will be forced to upgrade to Protobuf v28.3 under Bazel 6 and 7, and Protobuf v29 under Bazel 8. , and the load("@rules_java") statements required by Bazel 8 will break WORKSPACE users for good. Then again, that may be all the more reason to suggest folks migrate to Bzlmod sooner than later.

Update: I've scratched out that last statement, because as noted in #1652, I could get a WORKSPACE build under Bazel 8 to reach the same failure point as the Bzlmod build. But these changes broke in what appears to be an unresolvable way under Bazel 7.4.1.

[mbland]

I've confirmed in my replace-custom-scalapb-wrappers-with-protoc-bridge-0.9.8 branch that the recently released protoc-bridge 0.9.8 resolves scalapb/ScalaPB#1771 (i.e., protoc-bridge catches scalapb.ScalaPbCodeGenerator errors, so we don't have to). I've since closed that issue, and will send a pull request containing the changes from this branch eventually.

[mbland]

Here are some detailed findings from my replace-custom-scalapb-wrappers-with-protoc-bridge-0.9.8 branch, specifically mbland@2d7b891, regarding our handling of ScalaPB's compilerplugin, protoc-gen, and protoc-bridge artifacts. Please see that commit message for even more details.

Scala 3 artifacts and compilerplugin_3's dependency on protoc-gen_2.13

The _3 versions of the most recent ScalaPB artifacts are only available for Scala 3.3 and later, and compilerplugin_3 currently still depends on protoc-gen_2.13.

Building Scala 3.3 and later versions with compilerplugin_3 and protoc-bridge_3 artifacts (instead of protoc-bridge_2.13 artifacts) produces the following build failure:

$ RULES_SCALA_TEST_ONLY="test_scala_version 3.6.2" \
    ./test_thirdparty_version.sh

[ ...snip... ]

ERROR: third_party/test/proto/BUILD.bazel:4:14:
  ProtoScalaPBRule
  third_party/test/proto/proto_jvm_extra_protobuf_generator_scalapb.srcjar
  failed: (Exit 1): scalapb_worker failed: error executing command
  (from target //third_party/test/proto:proto)
  bazel-out/darwin_arm64-opt-exec-2B5CBBC6/bin/src/scala/scripts/scalapb_worker
    ... (remaining 2 arguments skipped)

--scala_out: java.lang.NoClassDefFoundError:
  Could not initialize class scalapb.ScalaPbCodeGenerator$
    at scripts.ScalaPbCodeGenerator$.process(ScalaPbCodeGeneratorWrapper.scala:8)
    at protocgen.CodeGenApp.run(CodeGenApp.scala:48)
    at protocgen.CodeGenApp.run$(CodeGenApp.scala:41)
    at scripts.ScalaPbCodeGenerator$.run(ScalaPbCodeGeneratorWrapper.scala:5)
    at protocgen.CodeGenApp.run(CodeGenApp.scala:33)
    at protocgen.CodeGenApp.run$(CodeGenApp.scala:32)
    at scripts.ScalaPbCodeGenerator$.run(ScalaPbCodeGeneratorWrapper.scala:5)
    at protocbridge.frontend.PluginFrontend$.runWithBytes(PluginFrontend.scala:48)
    at protocbridge.frontend.PluginFrontend$.runWithInputStream(PluginFrontend.scala:113)
    [ ...snip... ]

protoc-bridge 0.9.8 with a new try/catch block vs. 0.7.14 for Scala 2.11

The initial motivation for that commit was to try to eliminate the need for the custom scripts.ScalaPbCodeGenerator implementation by upgrading to protoc-bridge 0.9.8. This version contains a change to catch any Throwable objects raised by a generator implementation in protocbridge.frontend.PluginFrontend.runWithInputStream().

This change originally came from scalapb/protoc-bridge#367 (exact lines).

I closed scalapb/ScalaPB#1771 as a result, and reexamined the try/catch blocks added in #1630 and #1637, and the scripts.ScalaPBCodeGenerator implementations added in #1648.

However, the last protoc-bridge version to support Scala 2.11 is 0.7.14. Scala 2.11 won't be able to use protoc-bridge 0.9.8, so we still need to catch any Throwables ourselves. This includes the catch blocks from the Scala 2.11 scripts.ScalaPbCodeGenerator and scalarules.test.extra_protobuf_generator.ExtraProtobufGenerator.run.

try/catch blocks

In protoc-bridge 0.9.7 and 0.9.8, protocbridge.ProtocCodeGenerator declares a run() method with no implementation (and no try/catch block).

In protoc-gen 0.9.7 and 0.9.8, protogen.CodeGenApp implements protocbridge.ProtocCodeGenerator, and CodeGenApp.run() wraps a call to CodeGenApp.process() inside a try/catch block.

scalapb.ScalaPbCodeGenerator from compilerplugin 0.11.17 extends CodeGenApp and implements process(). For this version of ScalaPbCodeGenerator, available in Scala 2.12 and later, there's no need for a try/catch wrapper on our end.

However, the last available compilerplugin version for Scala 2.11 is 0.9.8. scalapb.ScalaPbCodeGenerator from that version implements protocbridge.ProtocCodeGenerator and has a try/catch in its run() method. However, the Scalapb.registerAllExtensions(registry) call on line 14 lies outside this block, producing the crash described in #1648 (23ae356). This is why we need the Scala 2.11 implementation of scripts.ScalaPbCodeGenerator.

rules_scala/src/scala/scripts/ScalaPbCodeGeneratorWrapper_2_11.scala

Lines 5 to 18 in 23ae356

	override def run(req: Array[Byte]): Array[Byte] = {
	try {
	scalapb.ScalaPbCodeGenerator.run(req)
	} catch {
	case e: Throwable =>
	val b = CodeGeneratorResponse.newBuilder
	val stackStream = new java.io.ByteArrayOutputStream
	e.printStackTrace(new java.io.PrintStream(stackStream))
	b.setError(stackStream.toString())
	b.build.toByteArray
	}
	}

$ bazel build --repo_env=SCALA_VERSION=2.11.12 //proto:test_proto

ERROR: .../test_version/test_scala_version_1731169107/proto/BUILD:14:14:
  ProtoScalaPBRule proto/test3_scala_scalapb.srcjar failed: (Exit 1):
  scalapb_worker failed: error executing command
  (from target //proto:test3)

bazel-out/.../bin/external/io_bazel_rules_scala/src/scala/scripts/scalapb_worker
  ... (remaining 2 arguments skipped)

--scala_out: java.lang.NoSuchMethodError:
  'void com.google.protobuf.Descriptors$FileDescriptor.internalBuildGeneratedFileFrom(java.lang.String[],
    com.google.protobuf.Descriptors$FileDescriptor[],
    com.google.protobuf.Descriptors$FileDescriptor$InternalDescriptorAssigner)'
      at scalapb.options.compiler.Scalapb.<clinit>(Scalapb.java:10592)
====> at scalapb.ScalaPbCodeGenerator$.run(ScalaPbCodeGenerator.scala:14)
      at scalapb.ScalaPbCodeGenerator$.run(ScalaPbCodeGenerator.scala:10)
      at scripts.ScalaPbCodeGenerator$.run(ScalaPbCodeGeneratorWrapper_2_11.scala:8)
      at protocbridge.frontend.PluginFrontend$$anonfun$runWithBytes$2.apply(PluginFrontend.scala:52)
      at protocbridge.frontend.PluginFrontend$$anonfun$runWithBytes$2.apply(PluginFrontend.scala:52)
      at scala.util.Try$.apply(Try.scala:192)
      at protocbridge.frontend.PluginFrontend$.runWithBytes(PluginFrontend.scala:51)
      at protocbridge.frontend.PluginFrontend$.runWithInputStream(PluginFrontend.scala:103)
      [ ...snip...]

scalarules.test.extra_protobuf_generator.ExtraProtobufGenerator, also extends ProtocCodeGenerator directly, instead of implementing CodeGenApp (so it also builds with Scala 2.11). This is why ExtraProtobufGenerator.run() hangs when we remove the try/catch block and run with protoc-bridge 0.9.7 and protobuf > v25.5, even with later Scala versions.

rules_scala/test/src/main/scala/scalarules/test/extra_protobuf_generator/ExtraProtobufGenerator.scala

Lines 47 to 67 in 23ae356

	object ExtraProtobufGenerator extends ProtocCodeGenerator {
	override def run(req: Array[Byte]): Array[Byte] = {
	val b = CodeGeneratorResponse.newBuilder
	try {
	val registry = ExtensionRegistry.newInstance()
	Scalapb.registerAllExtensions(registry)
	val request = CodeGeneratorRequest.parseFrom(req)
	handleCodeGeneratorRequest(request, b)
	} catch {
	case e: Throwable =>
	// Yes, we want to catch _all_ errors and send them back to the
	// requestor. Otherwise uncaught errors will cause the generator to
	// die and the worker invoking it to hang.
	val stackStream = new java.io.ByteArrayOutputStream
	e.printStackTrace(new java.io.PrintStream(stackStream))
	b.setError(stackStream.toString())
	}
	b.build.toByteArray
	}

Keeping scripts.ScalaPbCodeGenerator for Scala 2.11 compatibility

Since scalapb.ScalaPbCodeGenerator from compilerplugin 0.11.17 implements CodeGenApp, scripts.ScalaPbCodeGenerator for Scala 2.12 should be unnecessary. The only reason we need it is to maintain the same interface as the Scala 2.11 implementation.

rules_scala/src/scala/scripts/BUILD

Lines 26 to 36 in 23ae356

	scala_library(
	name = "scalapb_codegenerator_wrapper",
	srcs = select_for_scala_version(
	any_2_11 = ["ScalaPbCodeGeneratorWrapper_2_11.scala"],
	since_2_12 = ["ScalaPbCodeGeneratorWrapper.scala"],
	),
	visibility = ["//visibility:public"],
	deps = [
	"//scala_proto:scalapb_worker_deps",
	],
	)

rules_scala/scala_proto/scala_proto_toolchain.bzl

Lines 83 to 85 in 23ae356

	"main_generator": attr.string(
	default = "scripts.ScalaPbCodeGenerator",
	),

rules_scala/scala_proto/scala_proto_toolchain.bzl

Lines 113 to 120 in 23ae356

	"_main_generator_dep": attr.label(
	default = Label(
	"//src/scala/scripts:scalapb_codegenerator_wrapper",
	),
	allow_single_file = True,
	executable = False,
	cfg = "exec",
	),