bazel
bazel copied to clipboard
bazelbuild
Request to revamp Bazel Toolchain & Platform pages and code examples for v7.0.0
Page link:
https://bazel.build/versions/7.0.0/concepts/platforms
Problem description (include actual vs expected text, if applicable):
@katre per John's suggestion from the bazel-discuss@ thread: https://groups.google.com/g/bazel-discuss/c/eScnfnQU21I/m/0WoTeabZAQAJ (sorry I can't find a CC field in the issue creation template, so using @ instead).
Bazel is an awesome build system, which I didn't realize until after leaving Alphabet and started using CMake. Most of the Bazel documentation pages are clearly written and easy to follow (Kudos to the documentation team!), but one thing that I have been struggling with is the Toolchain and Platform setup. It's arguably the most complicated piece of the Bazel setup, but also the most critical and fundamental piece, therefore I think they deserve some special attention.
For example, https://bazel.build/versions/7.0.0/concepts/platforms, instead of describing how to "Migrating to Platforms", could the Bazel team consider providing a complete end-to-end working example based on Bazel v.7.0.0, including:
- Using MODULES.bazel, not the deprecated WORKSPACE file to setup external repositories based on HTTPS or Git repos where tool chain compiler/linker/etc are pulled in dynamically during the build time;
- Toolchain setup and registration based on different host and target environments (e.g. for building C/C++ applications on Linux/Mac/Windows for targets running on x64, ARM64 or custom processors based on step 1 above);
- Platform setup based on the toolchains created in the previous step;
- Hello-world examples of compiling the same code on different host environments and for different target environments.
Since I could not figure out the complete setup after reading https://bazel.build/versions/7.0.0/concepts/platforms, I've tried its "See Also" section at the bottom of the page, but:
- Configurable Builds - Part 1 is 4 years old and provides only part 1, and part 2 is missing;
- Platforms is very short and doesn't show how its toolchains are set up;
- Toolchains is quite detailed, but I find it a bit hard to follow, and I can't figure out how to use compilers/linkers/etc from the externally downloaded modules;
And the remaining links all point to out-dated docs that are more than 4 years old, and most code examples I tried are no longer working:
Just FYI, these are some relevant pages and videos that I found online that helped me better understand the toolchains and platform setup, but I have not been able to develop a thorough understanding to be able to write my own custom toolchains and platforms, partly b/c most of those examples are based on the deprecated WORKSPACE file, not the new MODULES.bazel file, and toolchains and platforms examples are separated, though they are closely related to each other:
- Bazel Tutorial: Configure C++ Toolchains
- examples/bzlmod/04-local_config_and_register_toolchains at main · bazelbuild/examples (github.com)
- hexdae/bazel-arm-none-eabi: ARM none eabi gcc embedded toolchain for Bazel (github.com) **(This is the closest to what I want to do, but reusing it as an external module turns out to be much more complicated and fragile than I expected, and the way its toolchains are setup also seem quite convoluted. I wonderif there are more straightforward ways to do this from the Bazel team's PoV? **
- https://github.com/uber/hermetic_cc_toolchain
- https://www.youtube.com/watch?v=5ugdNGVjSRQ
- https://www.youtube.com/watch?v=CrfQaZjuj_Y
I greatly appreciate the attention you put into this request. Please let me know if there is anything that I can help with. I am be happy to contribute to open source projects and repos to demonstrate how to set up and use Bazel toolchains and platforms.
Best Regards, HaiXin
Where do you see this issue? (include link to specific section of the page, if applicable)
No response
Any other information you'd like to share?
No response
Seconded! The documentations are outdated and that is such a shame. When Bazel works it seems to work really well, but when it doesn't, it is really hard to figure out what should happen. Especially for newcomers. I have made a small project using it, wanted to add proper toolchains following guide: https://bazel.build/tutorials/ccp-toolchain-config, but nothing is as written in the guide. No errors when it says I should get an error, but disregarding that even after I have completed the whole thing it still simply ignored all the configuration that I have done, silently, and tried to use the default GCC toolchain instead.
Seconded! The documentations are outdated and that is such a shame. When Bazel works it seems to work really well, but when it doesn't, it is really hard to figure out what should happen. Especially for newcomers. I have made a small project using it, wanted to add proper toolchains following guide: https://bazel.build/tutorials/ccp-toolchain-config, but nothing is as written in the guide. No errors when it says I should get an error, but disregarding that even after I have completed the whole thing it still simply ignored all the configuration that I have done, silently, and tried to use the default GCC toolchain instead.
I had the same problem. I rolled bazel back back to version 6.5 in order to follow the documentation.
