Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

extend bootstrap related documentations #1563

Merged
merged 1 commit into from
Jan 31, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 53 additions & 11 deletions src/building/bootstrapping.md
Original file line number Diff line number Diff line change
Expand Up @@ -411,17 +411,17 @@ you can tell the bootstrap shim to print all env variables by adding `-vvv` to y

This is an incomplete reference for the outputs generated by bootstrap:

| Stage 0 Action | Output |
|-----------------------------------------------------------|----------------------------------------------|
| `beta` extracted | `build/HOST/stage0` |
| `stage0` builds `bootstrap` | `build/bootstrap` |
| `stage0` builds `test`/`std` | `build/HOST/stage0-std/TARGET` |
| copy `stage0-std` (HOST only) | `build/HOST/stage0-sysroot/lib/rustlib/HOST` |
| `stage0` builds `rustc` with `stage0-sysroot` | `build/HOST/stage0-rustc/HOST` |
| copy `stage0-rustc` (except executable) | `build/HOST/stage0-sysroot/lib/rustlib/HOST` |
| build `llvm` | `build/HOST/llvm` |
| `stage0` builds `codegen` with `stage0-sysroot` | `build/HOST/stage0-codegen/HOST` |
| `stage0` builds `rustdoc`, `clippy`, `miri`, with `stage0-sysroot` | `build/HOST/stage0-tools/HOST` |
| Stage 0 Action | Output |
| ------------------------------------------------------------------ | -------------------------------------------- |
| `beta` extracted | `build/HOST/stage0` |
| `stage0` builds `bootstrap` | `build/bootstrap` |
| `stage0` builds `test`/`std` | `build/HOST/stage0-std/TARGET` |
| copy `stage0-std` (HOST only) | `build/HOST/stage0-sysroot/lib/rustlib/HOST` |
| `stage0` builds `rustc` with `stage0-sysroot` | `build/HOST/stage0-rustc/HOST` |
| copy `stage0-rustc` (except executable) | `build/HOST/stage0-sysroot/lib/rustlib/HOST` |
| build `llvm` | `build/HOST/llvm` |
| `stage0` builds `codegen` with `stage0-sysroot` | `build/HOST/stage0-codegen/HOST` |
| `stage0` builds `rustdoc`, `clippy`, `miri`, with `stage0-sysroot` | `build/HOST/stage0-tools/HOST` |

`--stage=0` stops here.

Expand All @@ -448,3 +448,45 @@ This is an incomplete reference for the outputs generated by bootstrap:
| copy `rustdoc` | `build/HOST/stage2/bin` |

`--stage=2` stops here.

### Clarification of build command's stdout

In this part, we will investigate the build command's stdout in an action
(similar, but more detailed and complete documentation compare to topic above).
When you execute `x.py build --dry-run` command, the build output will be something
like the following:

```text
Building stage0 library artifacts (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu)
Copying stage0 library from stage0 (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu / x86_64-unknown-linux-gnu)
Building stage0 compiler artifacts (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu)
Copying stage0 rustc from stage0 (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu / x86_64-unknown-linux-gnu)
Assembling stage1 compiler (x86_64-unknown-linux-gnu)
Building stage1 library artifacts (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu)
Copying stage1 library from stage1 (x86_64-unknown-linux-gnu -> x86_64-unknown-linux-gnu / x86_64-unknown-linux-gnu)
Building stage1 tool rust-analyzer-proc-macro-srv (x86_64-unknown-linux-gnu)
Building rustdoc for stage1 (x86_64-unknown-linux-gnu)
```

#### Building stage0 {std,compiler} artifacts

These steps use the provided (downloaded, usually) compiler to compile the
local Rust source into libraries we can use.

#### Copying stage0 {std,rustc}

This copies the library and compiler artifacts from Cargo into
`stage0-sysroot/lib/rustlib/{target-triple}/lib`

#### Assembling stage1 compiler

This copies the libraries we built in "building stage0 ... artifacts" into
the stage1 compiler's lib directory. These are the host libraries that the
compiler itself uses to run. These aren't actually used by artifacts the new
compiler generates. This step also copies the rustc and rustdoc binaries we
generated into `build/$HOST/stage/bin`.

The stage1/bin/rustc is a fully functional compiler, but it doesn't yet have
any libraries to link built binaries or libraries to. The next 3 steps will
provide those libraries for it; they are mostly equivalent to constructing
the stage1/bin compiler so we don't go through them individually.
21 changes: 21 additions & 0 deletions src/building/suggested.md
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,27 @@ You can also use `--keep-stage 1` when running tests. Something like this:
- Initial test run: `./x.py test tests/ui`
- Subsequent test run: `./x.py test tests/ui --keep-stage 1`

## Using incremental compilation

You can further enable the `--incremental` flag to save additional
time in subsequent rebuilds:

```bash
./x.py test tests/ui --incremental --test-args issue-1234
```

If you don't want to include the flag with every command, you can
enable it in the `config.toml`:

```toml
[rust]
incremental = true
```

Note that incremental compilation will use more disk space than usual.
If disk space is a concern for you, you might want to check the size
of the `build` directory from time to time.

## Fine-tuning optimizations

Setting `optimize = false` makes the compiler too slow for tests. However, to
Expand Down
4 changes: 4 additions & 0 deletions src/getting-started.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,10 @@ serious development work. In particular, `./x.py build` and `./x.py test`
provide many ways to compile or test a subset of the code, which can save a lot
of time.

Also, note that `x.py` supports all kinds of path suffixes for `compiler`, `library`,
and `src/tools` directories. So, you can simply run `x.py test tidy` instead of
`x.py test src/tools/tidy`. Or, `x.py build std` instead of `x.py build library/std`.

jyn514 marked this conversation as resolved.
Show resolved Hide resolved
[rust-analyzer]: ./building/suggested.html#configuring-rust-analyzer-for-rustc

See the chapters on [building](./building/how-to-build-and-run.md),
Expand Down
5 changes: 5 additions & 0 deletions src/tests/compiletest.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,11 @@ See the [Adding new tests](adding.md) chapter for a tutorial on creating a new
test, and the [Running tests](running.md) chapter on how to run the test
suite.

Compiletest itself tries to avoid running tests when the artifacts
that are involved (mainly the compiler) haven't changed. You can use
`x test --test-args --force-rerun` to rerun a test even when none of the
inputs have changed.

## Test suites

All of the tests are in the [`tests`] directory.
Expand Down
21 changes: 0 additions & 21 deletions src/tests/running.md
Original file line number Diff line number Diff line change
Expand Up @@ -175,27 +175,6 @@ By passing `--pass $mode`, you can reduce the testing time. For each
mode, please see [Controlling pass/fail
expectations](ui.md#controlling-passfail-expectations).

## Using incremental compilation

You can further enable the `--incremental` flag to save additional
time in subsequent rebuilds:

```bash
./x.py test tests/ui --incremental --test-args issue-1234
```

If you don't want to include the flag with every command, you can
enable it in the `config.toml`:

```toml
[rust]
incremental = true
```

Note that incremental compilation will use more disk space than usual.
If disk space is a concern for you, you might want to check the size
of the `build` directory from time to time.

## Running tests with different "compare modes"

UI tests may have different output depending on certain "modes" that
Expand Down