fix: bzlmod users don't need to register toolchain (#75)

* fix: bzlmod users don't need to register toolchain

The toolchains_protoc MODULE file registers the protoc toolchain itself.

* docs: clarify ordering

Author: alexeagle

.github/workflows/release_prep.sh

@@ -22,20 +22,16 @@ cat << EOF
 2. Add to your \`MODULE.bazel\` file:
 
 \`\`\`starlark
+# NB: this must come BEFORE bazel_dep(name = "protobuf") because they register the from-source toolchain,
+# and the first registration wins.
 bazel_dep(name = "toolchains_protoc", version = "${TAG:1}")
 
 # Optional: choose a version of protoc rather than the latest.
 protoc = use_extension("@toolchains_protoc//protoc:extensions.bzl", "protoc")
 protoc.toolchain(
-    # Creates a repository to satisfy well-known-types dependencies such as
-    # deps=["@com_google_protobuf//:any_proto"]
-    google_protobuf = "com_google_protobuf",
     # Pin to any version of protoc
     version = "v26.0",
 )
-use_repo(protoc, "com_google_protobuf", "toolchains_protoc_hub")
-
-register_toolchains("@toolchains_protoc_hub//:all")
 \`\`\`
 
 ## Using WORKSPACE

README.md

@@ -56,6 +56,16 @@ Enable the toolchain support by adding this to `.bazelrc`:
 common --incompatible_enable_proto_toolchain_resolution
 ```
 
+Make sure this module wins the toolchain registration for the
+[`@rules_proto//proto:toolchain_type` symbol](https://github.com/bazelbuild/rules_proto/blob/74961e561111a3510d5c25233477b950379ae06d/proto/BUILD#L58), either by ensuring the `bazel_dep` for `toolchains_protoc` is listed BEFORE the one for `protobuf`, or explicitly register the toolchain in your own `MODULE.bazel`:
+
+```
+# Override the toolchain registration from the protobuf module
+protoc = use_extension("@toolchains_protoc//protoc:extensions.bzl", "protoc")
+use_repo(protoc, "toolchains_protoc_hub")
+register_toolchains("@toolchains_protoc_hub//:all")
+```
+
 ### For each language, follow these steps
 
 Since the user installs the proto runtimes through their existing package manager setup,
@@ -99,8 +109,11 @@ See `examples` for several language rules like `py_proto_library` and `java_prot
 
 ### Troubleshooting
 
-What if you still see that protoc is compiling? This means that there is still a transitive dependency on the
-`com_google_protobuf` module, likely from some macro call in your `WORKSPACE` file.
+What if you still see that protoc is compiling?
+
+1. Check that toolchains_protoc `bazel_dep` is BEFORE `protobuf`, see Installation above.
+1. This could mean that there is still a transitive dependency on the
+   `com_google_protobuf` module, likely from some macro call in your `WORKSPACE` file.
 
 > TODO: explain how to track down where the `com_google_protobuf` dependency is coming from.
 

examples/.bazelrc

@@ -7,6 +7,8 @@ common --host_platform=//tools:no_cgo_host_platform
 common --@aspect_rules_ts//ts:skipLibCheck=always
 common --@aspect_rules_ts//ts:default_to_tsc_transpiler
 
+common --java_runtime_version=remotejdk_11
+
 # Ensure that we don't accidentally build protobuf or gRPC
 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

examples/MODULE.bazel

@@ -37,9 +37,7 @@ protoc.toolchain(
     # Demonstrate overriding the default version
     version = "v28.0",
 )
-use_repo(protoc, "com_google_protobuf", "toolchains_protoc_hub")
-
-register_toolchains("@toolchains_protoc_hub//:all")
+use_repo(protoc, "com_google_protobuf")
 
 # NB: the `:all` here is critical, because `proto_lang_toolchain` expands into two targets:
 # - proto_lang_toolchain rule [name]