Document how to build with Bazel

[jdcormie]

Add .bazelversion files so that workflows and contributors automatically use the same supported/tested version of bazel.

examples/ needs its own copy because it's technically a separate workspace. This could have been a symlink but decided against this to avoid causing problems on Windows. I guess technically examples could use a different version ...

[ejona86]

We don't have an officially supported bazel version. We support the two most recent major versions of bazel, which would be 8.x and 9.x. That allows the Bazel version and gRPC version to be upgraded separately. It would be okay for us to require an upgrade from 8.6 to 8.7 since that should be easy for users, but we've not needed to do that much.

When running locally, I'm generally using the newest Bazel since that is what will be installed on my machine. This change will prevent testing on the newer version.

[jdcormie]

We don't have an officially supported bazel version. We support the two most recent major versions of bazel, which would be 8.x and 9.x. That allows the Bazel version and gRPC version to be upgraded separately.

Makes sense, thanks. I do think most contributors won't care about the Bazel version, though. My goal is to document just one simple build command that almost never has to change. Good to know that we intend to support those two latest Bazel versions but there's value in letting contributors use the exact same known-working version that our CI workflows actually test. For example, 9.x fails for me at HEAD with:

ERROR: /usr/local/google/home/jdcormie/.cache/bazel/_bazel_jdcormie/adec8d7cdb47247666b8a6a775025019/external/rules_go+/go/private/rules/cgo.bzl:191:22: The CcInfo symbol has been removed, add the following to your BUILD/bzl file:
load("@rules_cc//cc/common:cc_info.bzl", "CcInfo")

presumably because CI doesn't test it.

It would be okay for us to require an upgrade from 8.6 to 8.7 since that should be easy for users, but we've not needed to do that much.

Cool. If we did require a Bazel version upgrade, we could update .bazelversion and insulate most contributors from the change. They could just keep typing the same Bazel build command just like they can already do with gradlew.

When running locally, I'm generally using the newest Bazel since that is what will be installed on my machine. This change will prevent testing on the newer version.

You can actually use an environment variable to override .bazelversion. Try:

USE_BAZEL_VERSION=9.x gbazelisk build //api

I'll update the docs to mention this.

[ejona86]

For example, 9.x seems to be failing at HEAD because:

FWIW, 9.0 works. 9.1 fails. It is called out in the 9.1 release notes https://github.com/bazelbuild/bazel/releases/tag/9.1.0 . Looks like something that we do want to fix for our own development.

but there's value in letting contributors use the exact same known-working version that our CI workflows actually test

Not as much as with Gradle. With Bazel our users actually run our build. With Gradle they get pre-built JARs and never use our build. So we really need to support many versions and shouldn't just be using one.

Historically I used the latest Bazel for development and the oldest for CI. That was before we had a matrix. Things shifted due to bzlmod and workspace. But I think instead we'd want to add another version to the CI. .bazelversion overrides the version of bazel you're using, even without bazelisk (regular Bazel observes the file).

I think .bazelversion makes a lot of sense for applications. For libraries... seems more limited, because it ignores the fact that we can't choose the version. If we're going to do this, I think we must add a CI that tests with the other version we support. And we must not do it for examples, as it will produce a very poor experience and leave the wrong impression that we only support one version. But I'm not wild about it still.

Note that Bazel has been in a bit worse shape right now because I haven't been able to build locally. No matter the version of Bazel I used, it would fail to link C++ with a relocation refers to discarded section error. (Turns out to be gcc gsframe issue and I need to use clang to workaround.)

[jdcormie]

Historically I used the latest Bazel for development and the oldest for CI. That was before we had a matrix. Things shifted due to bzlmod and workspace.

OK I didn't realize Bazel 9.x was expected to work. It broke the build for me and wasn't covered by CI so I assumed the latest and greatest was something we should protect contributors from.

But I think instead we'd want to add another version to the CI.

Great. I sent you #12817

I think .bazelversion makes a lot of sense for applications. For libraries... seems more limited, because it ignores the fact that we can't choose the version. If we're going to do this, I think we must add a CI that tests with the other version we support. And we must not do it for examples, as it will produce a very poor experience and leave the wrong impression that we only support one version. But I'm not wild about it still.

Makes sense. As above, I don't actually care about .bazelversion per se so I dropped this part.

Note that Bazel has been in a bit worse shape right now because I haven't been able to build locally. No matter the version of Bazel I used, it would fail to link C++ with a relocation refers to discarded section error. (Turns out to be gcc gsframe issue and I need to use clang to workaround.)

Yes I noticed this too. I've been working around it by setting -c opt.