Some pain points in particular:
- Migrating WORKSPACE to MODULE.bazel sometimes is not as straightforward as Bzlmod Migration Guide | Bazel suggested. For example, use_repo("<mod_extension>", "<external_repo>") is not evaluated immediately (by design, I know), which means that one cannot call register_toolchains("@<external_repo>//toolchain:*") immediately after in in MODULE.bazel, unlike its equivalent in the legacy WORKSPACE file. A non-working example of this: hexdae/bazel-arm-none-eabi: ARM none eabi gcc embedded toolchain for Bazel (github.com). If I missed anything, please advise, as I am still confused on this;
- Many code examples and documents related to custom toolchain setup found on Google are largely based on the --crosstool_top toolchain setups. It's not immediately obvious how to convert them to the newer Platform based approach.
- There are often many layers of obscure Bazel function calls with dynamic file generations to implement a custom toolchain, making the code quite difficult to follow and understand. It's unclear to me whether all the indirections are absolutely necessary, or because the code creators did not fully understand Bazel and created working codes after many trials & errors.
- Toolchain and platform setup is one of the most important foundational pieces of a a build system. It's complicated by nature, but the official documentation and code examples are lacking, making it difficult for users to fully understand and leverage Bazel's power.
As a former Googler who had used Blaze for nearly 10 years, I didn't really appreciate how great Blaze/Bazel was until after leaving Alphabet and started using CMake. Bazel has make the build system end-user's life so much easier, such that I didn't really have to pay much attention to it, and just used it to get my job done. But now as a build system admin trying to setup custom toolchains and platforms, I find it much harder to grasp. I would greatly appreciate it if the Bazel team would come up with a comprehensive code example based on the latest bzlmod and platform designs, to perform the necessary steps below for a custom toolchain setup, e.g.:
- How to specify external HTTP or Git repos in MODULE.bazel to download the build tools, similar to bazel-arm-none-eabi/deps.bzl at master · hexdae/bazel-arm-none-eabi (github.com)
- How to specify custom BUILD files associated with the external repos downloaded in the previous step to various compiler/linker/etc tools in a toolchain for major host/execution OS'es (e.g. Linux, Windows and MacOS);
- How to properly define target platforms associated with the toolchains defined in the previous step;
- Simple hello world build target examples to show how the code can be compiled against different target environments on different host/execution environments.
I feel this may be a major pain point for many companies to adopt Bazel as their build system. If the Bazel's custom toolchain and platform setup design can be simplified, and/or its documentation enriched with more comprehensive working code examples, it would make Bazel more accessible to a much wider user base. Thanks for reading my long post. I hope at least some points would make sense to you.
Regards,
HaiXin