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.