rustc-dev-guide: update bootstrap tracing docs · rust-lang/rust@97efda6 (original) (raw)
1
1
`# Debugging bootstrap
`
2
2
``
3
``
`-
FIXME: this page could be expanded
`
``
3
`+
FIXME: this section should be expanded
`
4
4
``
5
5
`` ## tracing in bootstrap
``
6
6
``
`` @@ -10,21 +10,69 @@ Bootstrap has conditional [tracing][tracing] setup to provide structured loggi
``
10
10
``
11
11
`` ### Enabling tracing output
``
12
12
``
13
``
`` -
Bootstrap will conditionally enable tracing output if the BOOTSTRAP_TRACING env var is set.
``
``
13
`` +
Bootstrap will conditionally build tracing support and enable tracing output if the BOOTSTRAP_TRACING env var is set.
``
14
14
``
15
``
`-
Example usage:
`
``
15
`+
Basic usage
`
``
16
+
``
17
`+
Example basic usage[^just-trace]:
`
``
18
+
``
19
`` +
[^just-trace]: It is not recommend to use just BOOTSTRAP_TRACING=TRACE because that will dump everything at TRACE level, including logs intentionally gated behind custom targets as they are too verbose even for TRACE level by default.
``
16
20
``
17
21
```` ```bash
`18`
``
`-
$ BOOTSTRAP_TRACING=TRACE ./x build library --stage 1
`
``
`22`
`+
$ BOOTSTRAP_TRACING=bootstrap=TRACE ./x build library --stage 1
`
``
`23`
```` +
```
``
24
+
``
25
`+
Example output[^unstable]:
`
``
26
+
``
27
```
``
28
`+
$ BOOTSTRAP_TRACING=bootstrap=TRACE ./x check src/bootstrap/
`
``
29
`+
Building bootstrap
`
``
30
`+
Compiling bootstrap v0.0.0 (/home/joe/repos/rust/src/bootstrap)
`
``
31
`` +
Finished dev profile [unoptimized] target(s) in 2.74s
``
``
32
`+
DEBUG bootstrap parsing flags
`
``
33
`+
bootstrap::core::config::flags::Flags::parse args=["check", "src/bootstrap/"]
`
``
34
`+
DEBUG bootstrap parsing config based on flags
`
``
35
`+
DEBUG bootstrap creating new build based on config
`
``
36
`+
bootstrap::Build::build
`
``
37
`+
TRACE bootstrap setting up job management
`
``
38
`+
TRACE bootstrap downloading rustfmt early
`
``
39
`+
bootstrap::handling hardcoded subcommands (Format, Suggest, Perf)
`
``
40
`+
DEBUG bootstrap not a hardcoded subcommand; returning to normal handling, cmd=Check { all_targets: false }
`
``
41
`+
DEBUG bootstrap handling subcommand normally
`
``
42
`+
bootstrap::executing real run
`
``
43
`+
bootstrap::(1) executing dry-run sanity-check
`
``
44
`+
bootstrap::(2) executing actual run
`
``
45
`+
Checking stage0 library artifacts (x86_64-unknown-linux-gnu)
`
``
46
`` +
Finished release profile [optimized + debuginfo] target(s) in 0.04s
``
``
47
`+
Checking stage0 compiler artifacts {rustc-main, rustc_abi, rustc_arena, rustc_ast, rustc_ast_ir, rustc_ast_lowering, rustc_ast_passes, rustc_ast_pretty, rustc_attr_data_structures, rustc_attr_parsing, rustc_baked_icu_data, rustc_borrowck, rustc_builtin_macros, rustc_codegen_llvm, rustc_codegen_ssa, rustc_const_eval, rustc_data_structures, rustc_driver, rustc_driver_impl, rustc_error_codes, rustc_error_messages, rustc_errors, rustc_expand, rustc_feature, rustc_fluent_macro, rustc_fs_util, rustc_graphviz, rustc_hir, rustc_hir_analysis, rustc_hir_pretty, rustc_hir_typeck, rustc_incremental, rustc_index, rustc_index_macros, rustc_infer, rustc_interface, rustc_lexer, rustc_lint, rustc_lint_defs, rustc_llvm, rustc_log, rustc_macros, rustc_metadata, rustc_middle, rustc_mir_build, rustc_mir_dataflow, rustc_mir_transform, rustc_monomorphize, rustc_next_trait_solver, rustc_parse, rustc_parse_format, rustc_passes, rustc_pattern_analysis, rustc_privacy, rustc_query_impl, rustc_query_system, rustc_resolve, rustc_sanitizers, rustc_serialize, rustc_session, rustc_smir, rustc_span, rustc_symbol_mangling, rustc_target, rustc_trait_selection, rustc_traits, rustc_transmute, rustc_ty_utils, rustc_type_ir, rustc_type_ir_macros, stable_mir} (x86_64-unknown-linux-gnu)
`
``
48
`` +
Finished release profile [optimized + debuginfo] target(s) in 0.23s
``
``
49
`+
Checking stage0 bootstrap artifacts (x86_64-unknown-linux-gnu)
`
``
50
`+
Checking bootstrap v0.0.0 (/home/joe/repos/rust/src/bootstrap)
`
``
51
`` +
Finished release profile [optimized + debuginfo] target(s) in 0.64s
``
``
52
`` +
DEBUG bootstrap checking for postponed test failures from test --no-fail-fast
``
``
53
`+
Build completed successfully in 0:00:08
`
19
54
```` ```
`20`
`55`
``
`21`
``
`-
Example output[^experimental]:
`
``
`56`
`+
#### Controlling log output
`
``
`57`
`+`
``
`58`
`` +
The env var `BOOTSTRAP_TRACING` accepts a [`tracing` env-filter][tracing-env-filter].
``
``
`59`
`+`
``
`60`
`+
There are two orthogonal ways to control which kind of logs you want:
`
`22`
`61`
``
`23`
``
`-
`
``
`62`
`` +
1. You can specify the log **level**, e.g. `DEBUG` or `TRACE`.
``
``
`63`
`` +
2. You can also control the log **target**, e.g. `bootstrap` or `bootstrap::core::config` vs custom targets like `CONFIG_HANDLING`.
``
``
`64`
`` +
- Custom targets are used to limit what is output when `BOOTSTRAP_TRACING=bootstrap=TRACE` is used, as they can be too verbose even for `TRACE` level by default. Currently used custom targets:
``
``
`65`
`` +
- `CONFIG_HANDLING`
``
`24`
`66`
``
`25`
``
`-
[^experimental]: This shows what's *possible* with the infra in an experimental implementation.
`
``
`67`
`` +
The `TRACE` filter will enable *all* `trace` level or less verbose level tracing output.
``
`26`
`68`
``
`27`
``
`` -
The env var `BOOTSTRAP_TRACING` accepts a [`tracing` env-filter][tracing-env-filter]. The `TRACE` filter will enable *all* `trace` level or less verbose level tracing output.
``
``
`69`
`` +
You can of course combine them (custom target logs are typically gated behind `TRACE` log level additionally):
``
``
`70`
`+`
``
`71`
```` +
```bash
``
72
`+
$ BOOTSTRAP_TRACING=CONFIG_HANDLING=TRACE ./x build library --stage 1
`
``
73
```
``
74
+
``
75
`+
[^unstable]: This output is always subject to further changes.
`
28
76
``
29
77
`[tracing-env-filter]: https://docs.rs/tracing-subscriber/0.3.19/tracing_subscriber/filter/struct.EnvFilter.html
`
30
78
``
`` @@ -73,28 +121,6 @@ For #[instrument], it's recommended to:
``
73
121
`` - Explicitly pick an instrumentation name via name = ".." to distinguish between e.g. run of different steps.
``
74
122
`- Take care to not cause diverging behavior via tracing, e.g. building extra things only when tracing infra is enabled.
`
75
123
``
76
``
`` -
Enabling tracing bootstrap feature in rust-analyzer
``
``
124
`+
rust-analyzer integration?
`
77
125
``
78
``
`` -
You can adjust your settings.json's rust-analyzer.check.overrideCommand and rust-analyzer.cargo.buildScripts.overrideCommand if you want to also enable logging cargo feature by default in your editor. This is mostly useful if you want proper r-a completions and such when working on bootstrap itself.
``
79
``
-
80
``
```json
81
``
`-
"rust-analyzer.check.overrideCommand": [
`
82
``
`` -
"BOOTSTRAP_TRACING=1", // <- BOOTSTRAP_TRACING=1 won't enable tracing filter, but it will activate bootstrap's tracing feature
``
83
``
`-
"python3",
`
84
``
`-
"x.py",
`
85
``
`-
"check",
`
86
``
`-
"--json-output",
`
87
``
`-
"--build-dir=build-rust-analyzer"
`
88
``
`-
],
`
89
``
```
90
``
-
91
``
```json
92
``
`-
"rust-analyzer.cargo.buildScripts.overrideCommand": [
`
93
``
`-
"BOOTSTRAP_TRACING=1", // <- note this
`
94
``
`-
"python3",
`
95
``
`-
"x.py",
`
96
``
`-
"check",
`
97
``
`-
"--json-output",
`
98
``
`-
"--build-dir=build-rust-analyzer"
`
99
``
`-
],
`
100
``
```
``
126
`` +
Unfortunately, because bootstrap is a rust-analyzer.linkedProjects, you can't ask r-a to check/build bootstrap itself with tracing feature enabled to get relevant completions, due to lack of support as described in https://github.com/rust-lang/rust-analyzer/issues/8521.
``