52 lines
2.5 KiB
Markdown
52 lines
2.5 KiB
Markdown
# About
|
|
|
|
This documents some useful tools, concepts, and debugging strategies for bazel toolchains.
|
|
This information was gathered while developing the WASI SDK toolchain.
|
|
|
|
# Concepts
|
|
|
|
[Toolchain](https://bazel.build/extending/toolchains#debugging-toolchains) and [Platform](https://bazel.build/extending/platforms) 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](https://bazel.build/rules/lib/builtins/transition) 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](https://bazel.build/docs/cc-toolchain-config-reference#using-action-config) instead of the tool paths attribute because of, [possibly historical, lack of support for remote resources in tool paths](https://stackoverflow.com/questions/73504780/bazel-reference-binaries-from-packages-in-custom-toolchain-definition/73505313#73505313).
|
|
|
|
# Debugging tools
|
|
|
|
## Toolchain Debugging
|
|
|
|
```bash
|
|
bazel ... --toolchain_resolution_debug=.* ...
|
|
```
|
|
|
|
The above flag can be used to debug toolchain resolution as bazel tries to automatically satisfy constraints.
|
|
|
|
## Debugging Remote Resources
|
|
|
|
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.
|
|
|
|
```bash
|
|
find $(bazel info output_base) -name THING
|
|
```
|
|
|
|
Note: this command is directory dependent because output_base is per bazel instance.
|
|
|
|
## Debugging Bazel Compilation Actions
|
|
|
|
```bash
|
|
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.
|
|
|
|
## Debugging on Engflow
|
|
|
|
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.
|