From 426dbdb5da0ca8b362e37e6858da70c3f8af93c0 Mon Sep 17 00:00:00 2001 From: Protobuf Team Bot Date: Wed, 21 Jan 2026 14:06:53 -0800 Subject: [PATCH] Update the debugging playbook to add a section on prebuilt protoc issues. PiperOrigin-RevId: 859255451 --- content/news/2026-01-16.md | 6 ++++ content/support/debugging-playbook.md | 45 +++++++++++++++++++++++++++ 2 files changed, 51 insertions(+) create mode 100644 content/support/debugging-playbook.md diff --git a/content/news/2026-01-16.md b/content/news/2026-01-16.md index ff53b902..6bec503b 100644 --- a/content/news/2026-01-16.md +++ b/content/news/2026-01-16.md @@ -33,5 +33,11 @@ There are some use cases in which using the prebuilt protoc is not recommended: * You are making changes to protoc, itself, and want to ensure that those changes are tested. +### Troubleshooting + +For information on troubleshooting the prebuilt protoc compiler configuration, +see +[Bazel: Resolving Issues with Prebuilt Protoc](/support/debugging-playbook#prebuilt-protoc) + For more information on other changes in Bazel 9 that affect Protocol Buffers, see https://bazel.build/about/roadmap. diff --git a/content/support/debugging-playbook.md b/content/support/debugging-playbook.md new file mode 100644 index 00000000..1f2a9c8c --- /dev/null +++ b/content/support/debugging-playbook.md @@ -0,0 +1,45 @@ ++++ +title = "Debugging" +weight = 915 +description = "Debugging common issues in Protocol Buffers." +type = "docs" ++++ + +Frequently asked questions and debugging scenarios encountered by protobuf +users. + + + +## Bazel: Resolving Issues with Prebuilt Protoc {#prebuilt-protoc} + +As mentioned in [this news article](/news/2026-01-16), +Bazel 7 and later support builds that use a prebuilt protoc. When everything is +configured correctly, this can save a lot of time building, reduce logging +volume, and eliminate the need for C++ toolchain in non-C++ implementations. + +To prevent protoc compilation from source, add the following to your `.bazelrc` +file: + +```bazel +common --per_file_copt=external/.*protobuf.*@--PROTOBUF_WAS_NOT_SUPPOSED_TO_BE_BUILT +common --host_per_file_copt=external/.*protobuf.*@--PROTOBUF_WAS_NOT_SUPPOSED_TO_BE_BUILT +common --per_file_copt=external/.*grpc.*@--GRPC_WAS_NOT_SUPPOSED_TO_BE_BUILT +common --host_per_file_copt=external/.*grpc.*@--GRPC_WAS_NOT_SUPPOSED_TO_BE_BUILT +``` + +When there are hard-coded references to `@com_google_protobuf//:protoc` that are +reachable by the dependency graph, protoc will force it to be built for those +cases, negating this benefit. To resolve this, you'll need to find where the +dependencies are and request that those rulesets be updated. + +To find where you depend on protoc, use the following command: + +```none +bazel cquery 'somepath("//...", "@com_google_protobuf//:all")' +``` + +**Note:** Prebuilts are only available for our standard set of platforms. Anyone +on a nonstandard platform will have to build protoc from source.