bazel/docs/toolchain.md
This documents some useful tools, concepts, and debugging strategies for bazel toolchains. This information was gathered while developing the WASI SDK toolchain.
Toolchain and Platform are the core relevant concepts. Toolchains define the tools used to compile, and the platform defines either the execution platform (for the compilation/compiler tools) and target platform (for the binary). Bazel tries to search for a toolchain based on these constraints.
We also made use of transitions which allow bazel to reconfigure itself before building a target to avoid passing irrelevant or incorrect compiler flags (e.g. WASI SDK doesn't support shared objects). Similarly, we used actions instead of the tool paths attribute because of, possibly historical, lack of support for remote resources in tool paths.
bazel ... --toolchain_resolution_debug=.* ...
The above flag can be used to debug toolchain resolution as bazel tries to automatically satisfy constraints.
Toolchains may be remotely fetched, but the directory structure of the build environment after these remote resources are fetched may not be clear.
bazel info can be used to find the bazel directory and inspect it bazel info output_base.
Note: this may be different depending on your configuration and level of sandboxing.
This is particularly useful when used in combination with the find command as shown below.
find $(bazel info output_base) -name THING
Note: this command is directory dependent because output_base is per bazel instance.
bazel ... -s ...
This will show verbose output such as cd actions and compiler/linker invocations. Note: bazel may recast paths relative to the exec directory.
Engflow has a lot of helpful views showing remote execution stats and the remote file structure. We don't intent to duplicate their documentation but be careful as some of their data (particularly remotely executed actions) may not be accurate immediately after execution.