|
1 | 1 | # Debugging bootstrap |
2 | 2 |
|
| 3 | +There are two main ways to debug bootstrap itself. The first is through println logging, and the second is through the `tracing` feature. |
| 4 | + |
3 | 5 | > FIXME: this section should be expanded |
4 | 6 | |
| 7 | +## `println` logging |
| 8 | + |
| 9 | +Bootstrap has extensive unstructured logging. Most of it is gated behind the `--verbose` flag (pass `-vv` for even more detail). |
| 10 | + |
| 11 | +If you want to know which `Step` ran a command, you could invoke bootstrap like so: |
| 12 | + |
| 13 | +``` |
| 14 | +$ ./x dist rustc --dry-run -vv |
| 15 | +learning about cargo |
| 16 | +running: RUSTC_BOOTSTRAP="1" "/home/jyn/src/rust2/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "metadata" "--format-version" "1" "--no-deps" "--manifest-path" "/home/jyn/src/rust2/Cargo.toml" (failure_mode=Exit) (created at src/bootstrap/src/core/metadata.rs:81:25, executed at src/bootstrap/src/core/metadata.rs:92:50) |
| 17 | +running: RUSTC_BOOTSTRAP="1" "/home/jyn/src/rust2/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "metadata" "--format-version" "1" "--no-deps" "--manifest-path" "/home/jyn/src/rust2/library/Cargo.toml" (failure_mode=Exit) (created at src/bootstrap/src/core/metadata.rs:81:25, executed at src/bootstrap/src/core/metadata.rs:92:50) |
| 18 | +> Assemble { target_compiler: Compiler { stage: 1, host: x86_64-unknown-linux-gnu } } |
| 19 | + > Libdir { compiler: Compiler { stage: 1, host: x86_64-unknown-linux-gnu }, target: x86_64-unknown-linux-gnu } |
| 20 | + > Sysroot { compiler: Compiler { stage: 1, host: x86_64-unknown-linux-gnu }, force_recompile: false } |
| 21 | +Removing sysroot /home/jyn/src/rust2/build/tmp-dry-run/x86_64-unknown-linux-gnu/stage1 to avoid caching bugs |
| 22 | + < Sysroot { compiler: Compiler { stage: 1, host: x86_64-unknown-linux-gnu }, force_recompile: false } |
| 23 | + < Libdir { compiler: Compiler { stage: 1, host: x86_64-unknown-linux-gnu }, target: x86_64-unknown-linux-gnu } |
| 24 | +... |
| 25 | +``` |
| 26 | + |
| 27 | +This will go through all the recursive dependency calculations, where `Step`s internally call `builder.ensure()`, without actually running cargo or the compiler. |
| 28 | + |
| 29 | +In some cases, even this may not be enough logging (if so, please add more!). In that case, you can omit `--dry-run`, which will show the normal output inline with the debug logging: |
| 30 | + |
| 31 | +``` |
| 32 | + c Sysroot { compiler: Compiler { stage: 0, host: x86_64-unknown-linux-gnu }, force_recompile: false } |
| 33 | +using sysroot /home/jyn/src/rust2/build/x86_64-unknown-linux-gnu/stage0-sysroot |
| 34 | +Building stage0 library artifacts (x86_64-unknown-linux-gnu) |
| 35 | +running: cd "/home/jyn/src/rust2" && env ... RUSTC_VERBOSE="2" RUSTC_WRAPPER="/home/jyn/src/rust2/build/bootstrap/debug/rustc" "/home/jyn/src/rust2/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "build" "--target" "x86_64-unknown-linux-gnu" "-Zbinary-dep-depinfo" "-Zroot-dir=/home/jyn/src/rust2" "-v" "-v" "--manifest-path" "/home/jyn/src/rust2/library/sysroot/Cargo.toml" "--message-format" "json-render-diagnostics" |
| 36 | + 0.293440230s INFO prepare_target{force=false package_id=sysroot v0.0.0 (/home/jyn/src/rust2/library/sysroot) target="sysroot"}: cargo::core::compiler::fingerprint: fingerprint error for sysroot v0.0.0 (/home/jyn/src/rust2/library/sysroot)/Build/TargetInner { name_inferred: true, ..: lib_target("sysroot", ["lib"], "/home/jyn/src/rust2/library/sysroot/src/lib.rs", Edition2021) } |
| 37 | +... |
| 38 | +``` |
| 39 | + |
| 40 | +In most cases this should not be necessary. |
| 41 | + |
| 42 | +TODO: we should convert all this to structured logging so it's easier to control precisely. |
| 43 | + |
5 | 44 | ## `tracing` in bootstrap |
6 | 45 |
|
7 | 46 | Bootstrap has conditional [`tracing`][tracing] setup to provide structured logging. |
@@ -53,11 +92,11 @@ Checking stage0 bootstrap artifacts (x86_64-unknown-linux-gnu) |
53 | 92 | Build completed successfully in 0:00:08 |
54 | 93 | ``` |
55 | 94 |
|
56 | | -#### Controlling log output |
| 95 | +#### Controlling tracing output |
57 | 96 |
|
58 | 97 | The env var `BOOTSTRAP_TRACING` accepts a [`tracing` env-filter][tracing-env-filter]. |
59 | 98 |
|
60 | | -There are two orthogonal ways to control which kind of logs you want: |
| 99 | +There are two orthogonal ways to control which kind of tracing logs you want: |
61 | 100 |
|
62 | 101 | 1. You can specify the log **level**, e.g. `DEBUG` or `TRACE`. |
63 | 102 | 2. You can also control the log **target**, e.g. `bootstrap` or `bootstrap::core::config` vs custom targets like `CONFIG_HANDLING`. |
|
0 commit comments