Skip to content

Commit 1e32114

Browse files
KobzolKobzol
committed
Merge from rustc
2 parents c89935f + 9ee223d commit 1e32114

File tree

9 files changed

+118
-5
lines changed

9 files changed

+118
-5
lines changed

Diff for: ‎src/SUMMARY.md

+1
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,7 @@
7575
- [Prologue](./building/bootstrapping/intro.md)
7676
- [What Bootstrapping does](./building/bootstrapping/what-bootstrapping-does.md)
7777
- [How Bootstrap does it](./building/bootstrapping/how-bootstrap-does-it.md)
78+
- [Debugging bootstrap](./building/bootstrapping/debugging-bootstrap.md)
7879

7980
# High-level Compiler Architecture
8081

Diff for: ‎src/backend/debugging.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ These tools include:
5656

5757
By default, the Rust build system does not check for changes to the LLVM source code or
5858
its build configuration settings. So, if you need to rebuild the LLVM that is linked
59-
into `rustc`, first delete the file `llvm-finished-building`, which should be located
59+
into `rustc`, first delete the file `.llvm-stamp`, which should be located
6060
in `build/<host-triple>/llvm/`.
6161

6262
The default rustc compilation pipeline has multiple codegen units, which is

Diff for: ‎src/building/bootstrapping/debugging-bootstrap.md

+100
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Debugging bootstrap
2+
3+
> FIXME: this page could be expanded
4+
5+
## `tracing` in bootstrap
6+
7+
Bootstrap has conditional [`tracing`][tracing] setup to provide structured logging.
8+
9+
[tracing]: https://docs.rs/tracing/0.1.41/tracing/index.html
10+
11+
### Enabling `tracing` output
12+
13+
Bootstrap will conditionally enable `tracing` output if the `BOOTSTRAP_TRACING` env var is set.
14+
15+
Example usage:
16+
17+
```bash
18+
$ BOOTSTRAP_TRACING=TRACE ./x build library --stage 1
19+
```
20+
21+
Example output[^experimental]:
22+
23+
![Example bootstrap tracing output](./debugging-bootstrap/tracing-output-example.png)
24+
25+
[^experimental]: This shows what's *possible* with the infra in an experimental implementation.
26+
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.
28+
29+
[tracing-env-filter]: https://docs.rs/tracing-subscriber/0.3.19/tracing_subscriber/filter/struct.EnvFilter.html
30+
31+
### Using `tracing` in bootstrap
32+
33+
Both `tracing::*` macros and the `tracing::instrument` proc-macro attribute need to be gated behind `tracing` feature. Examples:
34+
35+
```rs
36+
#[cfg(feature = "tracing")]
37+
use tracing::{instrument, trace};
38+
39+
struct Foo;
40+
41+
impl Step for Foo {
42+
type Output = ();
43+
44+
#[cfg_attr(feature = "tracing", instrument(level = "trace", name = "Foo::should_run", skip_all))]
45+
fn should_run(run: ShouldRun<'_>) -> ShouldRun<'_> {
46+
#[cfg(feature = "tracing")]
47+
trace!(?run, "entered Foo::should_run");
48+
49+
todo!()
50+
}
51+
52+
#[cfg_attr(
53+
feature = "tracing",
54+
instrument(
55+
level = "trace",
56+
name = "Foo::run",
57+
skip_all,
58+
fields(compiler = ?builder.compiler),
59+
),
60+
)]
61+
fn run(self, builder: &Builder<'_>) -> Self::Output {
62+
#[cfg(feature = "tracing")]
63+
trace!(?run, "entered Foo::run");
64+
65+
todo!()
66+
}
67+
}
68+
```
69+
70+
For `#[instrument]`, it's recommended to:
71+
72+
- Gate it behind `trace` level for fine-granularity, possibly `debug` level for core functions.
73+
- Explicitly pick an instrumentation name via `name = ".."` to distinguish between e.g. `run` of different steps.
74+
- Take care to not cause diverging behavior via tracing, e.g. building extra things only when tracing infra is enabled.
75+
76+
### Enabling `tracing` bootstrap feature in rust-analyzer
77+
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+
```

Diff for: ‎src/building/bootstrapping/debugging-bootstrap/tracing-output-example.png

137 KB
Loading

Diff for: ‎src/building/bootstrapping/intro.md

+3
Original file line numberDiff line numberDiff line change
@@ -17,5 +17,8 @@ In this section, we give a high-level overview of
1717
[what Bootstrap does](./what-bootstrapping-does.md), followed by a high-level
1818
introduction to [how Bootstrap does it](./how-bootstrap-does-it.md).
1919

20+
Additionally, see [debugging bootstrap](./debugging-bootstrap.md) to learn
21+
about debugging methods.
22+
2023
[boot]: https://en.wikipedia.org/wiki/Bootstrapping_(compilers)
2124
[ocaml-compiler]: https://github.com/rust-lang/rust/tree/ef75860a0a72f79f97216f8aaa5b388d98da6480/src/boot

Diff for: ‎src/building/optimized-build.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -126,4 +126,4 @@ Here is an example of how can `opt-dist` be used locally (outside of CI):
126126
[`Environment`]: https://github.com/rust-lang/rust/blob/ee451f8faccf3050c76cdcd82543c917b40c7962/src/tools/opt-dist/src/environment.rs#L5
127127

128128
> Note: if you want to run the actual CI pipeline, instead of running `opt-dist` locally,
129-
> you can execute `DEPLOY=1 src/ci/docker/run.sh dist-x86_64-linux`.
129+
> you can execute `python3 src/ci/github-actions/ci.py run-local dist-x86_64-linux`.

Diff for: ‎src/tests/ci.md

+1-2
Original file line numberDiff line numberDiff line change
@@ -299,8 +299,7 @@ platform’s custom [Docker container]. This has a lot of advantages for us:
299299
- We can avoid reinstalling tools (like QEMU or the Android emulator) every time
300300
thanks to Docker image caching.
301301
- Users can run the same tests in the same environment locally by just running
302-
`src/ci/docker/run.sh image-name`, which is awesome to debug failures. Note
303-
that there are only linux docker images available locally due to licensing and
302+
`python3 src/ci/github-actions/ci.py run-local <job-name>`, which is awesome to debug failures. Note that there are only linux docker images available locally due to licensing and
304303
other restrictions.
305304

306305
The docker images prefixed with `dist-` are used for building artifacts while

Diff for: ‎src/tests/directives.md

+2-1
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,8 @@ for more details.
9494
| Directive | Explanation | Supported test suites | Possible values |
9595
|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------|----------------------------------------------|-----------------------------------------------------------------------------------------|
9696
| `check-run-results` | Check run test binary `run-{pass,fail}` output snapshot | `ui`, `crashes`, `incremental` if `run-pass` | N/A |
97-
| `error-pattern` | Check that output contains a regex pattern | `ui`, `crashes`, `incremental` if `run-pass` | Regex |
97+
| `error-pattern` | Check that output contains a specific string | `ui`, `crashes`, `incremental` if `run-pass` | String |
98+
| `regex-error-pattern` | Check that output contains a regex pattern | `ui`, `crashes`, `incremental` if `run-pass` | Regex |
9899
| `check-stdout` | Check `stdout` against `error-pattern`s from running test binary[^check_stdout] | `ui`, `crashes`, `incremental` | N/A |
99100
| `normalize-stderr-32bit` | Normalize actual stderr (for 32-bit platforms) with a rule `"<raw>" -> "<normalized>"` before comparing against snapshot | `ui`, `incremental` | `"<RAW>" -> "<NORMALIZED>"`, `<RAW>`/`<NORMALIZED>` is regex capture and replace syntax |
100101
| `normalize-stderr-64bit` | Normalize actual stderr (for 64-bit platforms) with a rule `"<raw>" -> "<normalized>"` before comparing against snapshot | `ui`, `incremental` | `"<RAW>" -> "<NORMALIZED>"`, `<RAW>`/`<NORMALIZED>` is regex capture and replace syntax |

Diff for: ‎src/tests/docker.md

+9
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,15 @@ Some additional notes about using the Docker images:
4545
containers. With the container name, run `docker exec -it <CONTAINER>
4646
/bin/bash` where `<CONTAINER>` is the container name like `4ba195e95cef`.
4747

48+
The approach described above is a relatively low-level interface for running the Docker images
49+
directly. If you want to run a full CI Linux job locally with Docker, in a way that is as close to CI as possible, you can use the following command:
50+
51+
```bash
52+
python3 src/ci/github-actions/ci.py run-local <job-name>
53+
# For example:
54+
python3 src/ci/github-actions/ci.py run-local dist-x86_64-linux-alt
55+
```
56+
4857
[Docker]: https://www.docker.com/
4958
[`src/ci/docker`]: https://github.com/rust-lang/rust/tree/master/src/ci/docker
5059
[`src/ci/docker/run.sh`]: https://github.com/rust-lang/rust/blob/master/src/ci/docker/run.sh

0 commit comments

Comments
 (0)