mirror
/
rustc-dev-guide
mirror of https://github.com/rust-lang/rustc-dev-guide.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update docs to match the new x.py defaults (#813)

This commit is contained in:
Joshua Nelson 2020-07-28 15:20:00 -04:00 committed by GitHub
parent 593facff2a
commit 879ca582de
9 changed files with 66 additions and 86 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
README.md
View File

@ -132,7 +132,7 @@ git submodule update --remote src/doc/rustc-dev-guide
git add -u git add -u
git commit -m "Update rustc-dev-guide" git commit -m "Update rustc-dev-guide"
# Note that you can use -i, which is short for --incremental, in the following command # Note that you can use -i, which is short for --incremental, in the following command
./x.py test --incremental --stage 1 src/doc/rustc-dev-guide # This is optional and should succeed anyway ./x.py test --incremental src/doc/rustc-dev-guide # This is optional and should succeed anyway
# Open a PR in rust-lang/rust # Open a PR in rust-lang/rust
``` ```

5
src/building/compiler-documenting.md
View File

@ -9,11 +9,14 @@ since documentation is more about the content.
## Document everything ## Document everything
This uses the beta rustdoc, which usually but not always has the same output
as stage 1 rustdoc.
```bash ```bash
./x.py doc ./x.py doc
``` ```
## If you want to avoid the whole Stage 2 build ## If you want to be sure that the links behave the same as on CI
```bash ```bash
./x.py doc --stage 1 ./x.py doc --stage 1

44
src/building/how-to-build-and-run.md
View File

@ -62,19 +62,6 @@ debug = true
# compiler. # compiler.
codegen-units = 0 codegen-units = 0
# Debuginfo level for most of Rust code, corresponds to the `-C debuginfo=N` option of `rustc`.
# `0` - no debug info
# `1` - line tables only - sufficient to generate backtraces that include line
# information and inlined functions, set breakpoints at source code
# locations, and step through execution in a debugger.
# `2` - full debug info with variable and type information
# Can be overridden for specific subsets of Rust code (rustc, std or tools).
# Debuginfo for tests run with compiletest is not controlled by this option
# and needs to be enabled separately with `debuginfo-level-tests`.
#
# Defaults to 2 if debug is true
debuginfo-level = 1
# Whether to always use incremental compilation when building rustc # Whether to always use incremental compilation when building rustc
incremental = true incremental = true
@ -147,10 +134,9 @@ To read more about the bootstrap process, [read this chapter][bootstrap].
## Building the Compiler ## Building the Compiler
To build a compiler, run `./x.py build`. This will do the whole bootstrapping To build a compiler, run `./x.py build`. This will build up to the stage1 compiler,
process described above, producing a usable compiler toolchain from the source including `rustdoc`, producing a usable compiler toolchain from the source
code you have checked out. This takes a long time, so it is not usually what code you have checked out.
you want to actually run (more on this later).
Note that building will require a relatively large amount of storage space. Note that building will require a relatively large amount of storage space.
You may want to have upwards of 10 or 15 gigabytes available to build the compiler. You may want to have upwards of 10 or 15 gigabytes available to build the compiler.
@ -190,7 +176,7 @@ Once you've created a config.toml, you are now ready to run
probably the best "go to" command for building a local rust: probably the best "go to" command for building a local rust:
```bash ```bash
./x.py build -i --stage 1 src/libstd ./x.py build -i src/libstd
``` ```
This may *look* like it only builds `libstd`, but that is not the case. This may *look* like it only builds `libstd`, but that is not the case.
@ -220,8 +206,8 @@ there is a (hacky) workaround. See [the section on "recommended
workflows"](./suggested.md) below. workflows"](./suggested.md) below.
Note that this whole command just gives you a subset of the full `rustc` Note that this whole command just gives you a subset of the full `rustc`
build. The **full** `rustc` build (what you get if you just say `./x.py build. The **full** `rustc` build (what you get if you say `./x.py build
build`) has quite a few more steps: --stage 2 src/rustc`) has quite a few more steps:
- Build `librustc` and `rustc` with the stage1 compiler. - Build `librustc` and `rustc` with the stage1 compiler.
- The resulting compiler here is called the "stage2" compiler. - The resulting compiler here is called the "stage2" compiler.
@ -244,12 +230,6 @@ Build the libcore and libproc_macro library only
./x.py build src/libcore src/libproc_macro ./x.py build src/libcore src/libproc_macro
``` ```
Build only libcore up to Stage 1
```bash
./x.py build src/libcore --stage 1
```
Sometimes you might just want to test if the part you’re working on can Sometimes you might just want to test if the part you’re working on can
compile. Using these commands you can test that it compiles before doing compile. Using these commands you can test that it compiles before doing
a bigger build to make sure it works with the compiler. As shown before a bigger build to make sure it works with the compiler. As shown before
@ -296,16 +276,16 @@ Here are a few other useful `x.py` commands. We'll cover some of them in detail
in other sections: in other sections:
- Building things: - Building things:
- `./x.py build --stage 1` – builds everything using the stage 1 compiler, - `./x.py build` – builds everything using the stage 1 compiler,
not just up to `libstd` not just up to `libstd`
- `./x.py build` – builds the stage2 compiler - `./x.py build --stage 2` – builds the stage2 compiler
- Running tests (see the [section on running tests](../tests/running.html) for - Running tests (see the [section on running tests](../tests/running.html) for
more details): more details):
- `./x.py test --stage 1 src/libstd` – runs the `#[test]` tests from `libstd` - `./x.py test src/libstd` – runs the `#[test]` tests from `libstd`
- `./x.py test --stage 1 src/test/ui` – runs the `ui` test suite - `./x.py test src/test/ui` – runs the `ui` test suite
- `./x.py test --stage 1 src/test/ui/const-generics` - runs all the tests in - `./x.py test src/test/ui/const-generics` - runs all the tests in
the `const-generics/` subdirectory of the `ui` test suite the `const-generics/` subdirectory of the `ui` test suite
- `./x.py test --stage 1 src/test/ui/const-generics/const-types.rs` - runs - `./x.py test src/test/ui/const-generics/const-types.rs` - runs
the single test `const-types.rs` from the `ui` test suite the single test `const-types.rs` from the `ui` test suite
### Cleaning out build directories ### Cleaning out build directories

8
src/building/suggested.md
View File

@ -58,13 +58,13 @@ don't work (but that is easily detected and fixed).
The sequence of commands you want is as follows: The sequence of commands you want is as follows:
- Initial build: `./x.py build -i --stage 1 src/libstd` - Initial build: `./x.py build -i src/libstd`
- As [documented above](#command), this will build a functional - As [documented above](#command), this will build a functional
stage1 compiler as part of running all stage0 commands (which include stage1 compiler as part of running all stage0 commands (which include
building a `libstd` compatible with the stage1 compiler) as well as the building a `libstd` compatible with the stage1 compiler) as well as the
first few steps of the "stage 1 actions" up to "stage1 (sysroot stage1) first few steps of the "stage 1 actions" up to "stage1 (sysroot stage1)
builds libstd". builds libstd".
- Subsequent builds: `./x.py build -i --stage 1 src/libstd --keep-stage 1` - Subsequent builds: `./x.py build -i src/libstd --keep-stage 1`
- Note that we added the `--keep-stage 1` flag here - Note that we added the `--keep-stage 1` flag here
As mentioned, the effect of `--keep-stage 1` is that we just *assume* that the As mentioned, the effect of `--keep-stage 1` is that we just *assume* that the
@ -84,8 +84,8 @@ rebuild. That ought to fix the problem.
You can also use `--keep-stage 1` when running tests. Something like this: You can also use `--keep-stage 1` when running tests. Something like this:
- Initial test run: `./x.py test -i --stage 1 src/test/ui` - Initial test run: `./x.py test -i src/test/ui`
- Subsequent test run: `./x.py test -i --stage 1 src/test/ui --keep-stage 1` - Subsequent test run: `./x.py test -i src/test/ui --keep-stage 1`
## Fine-tuning optimizations ## Fine-tuning optimizations

10
src/contributing.md
View File

@ -361,12 +361,12 @@ You can find documentation style guidelines in [RFC 1574][rfc1574].
[rfc1574]: https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text [rfc1574]: https://github.com/rust-lang/rfcs/blob/master/text/1574-more-api-documentation-conventions.md#appendix-a-full-conventions-text
In many cases, you don't need a full `./x.py doc`, which will build the entire In many cases, you don't need a full `./x.py doc --stage 2`, which will build
stage 2 compiler and compile the various books published on the entire stage 2 compiler and compile the various books published on
[doc.rust-lang.org][docs]. When updating documentation for the standard library, [doc.rust-lang.org][docs]. When updating documentation for the standard library,
first try `./x.py doc --stage 0 src/libstd`. If that fails, or if you need to first try `./x.py doc src/libstd`. If that fails, or if you need to
see the output from the latest version of `rustdoc`, use `--stage 1` instead of see the output from the latest version of `rustdoc`, add `--stage 1`.
`--stage 0`. Results should appear in `build/$TARGET/crate-docs`. Results should appear in `build/$TARGET/crate-docs`.
[docs]: https://doc.rust-lang.org [docs]: https://doc.rust-lang.org

42
src/getting-started.md
View File

@ -175,19 +175,19 @@ should still read the rest of the section:
| Command | When to use it | | Command | When to use it |
| --- | --- | | --- | --- |
| `x.py check` | Quick check to see if things compile; rust-analyzer can run this automatically for you | | `x.py check` | Quick check to see if things compile; rust-analyzer can run this automatically for you |
| `x.py build --stage 0 src/libstd` | Build only the standard library, without building the compiler | | `x.py build --stage 0 [src/libstd]` | Build only the standard library, without building the compiler |
| `x.py build --stage 1 src/libstd` | Build just the 1st stage of the compiler, along with the standard library; this is faster than building stage 2 and usually good enough | | `x.py build src/libstd` | Build just the 1st stage of the compiler, along with the standard library; this is faster than building stage 2 and usually good enough |
| `x.py build --stage 1 --keep-stage 1 src/libstd` | Build the 1st stage of the compiler and skips rebuilding the standard library; this is useful after you've done an ordinary stage1 build to skip compilation time, but it can cause weird problems. (Just do a regular build to resolve.) | | `x.py build --keep-stage 1 src/libstd` | Build the 1st stage of the compiler and skips rebuilding the standard library; this is useful after you've done an ordinary stage1 build to skip compilation time, but it can cause weird problems. (Just do a regular build to resolve.) |
| `x.py test --stage 1 [--keep-stage 1]` | Run the test suite using the stage1 compiler | | `x.py test [--keep-stage 1]` | Run the test suite using the stage1 compiler |
| `x.py test --stage 1 --bless [--keep-stage 1]` | Run the test suite using the stage1 compiler _and_ update expected test output. | | `x.py test --bless [--keep-stage 1]` | Run the test suite using the stage1 compiler _and_ update expected test output. |
| `x.py build` | Do a full 2-stage build. You almost never want to do this. | | `x.py build --stage 2 src/rustc` | Do a full 2-stage build. You almost never want to do this. |
| `x.py test` | Do a full 2-stage build and run all tests. You almost never want to do this. | | `x.py test --stage 2` | Do a full 2-stage build and run all tests. You almost never want to do this. |
To do a full 2-stage build of the whole compiler, you should run this (after To do a full 2-stage build of the whole compiler, you should run this (after
updating `config.toml` as mentioned above): updating `config.toml` as mentioned above):
```sh ```sh
./x.py build ./x.py build --stage 2 src/rustc
``` ```
In the process, this will also necessarily build the standard libraries, and it In the process, this will also necessarily build the standard libraries, and it
@ -203,10 +203,10 @@ For most contributions, you only need to build stage 1, which saves a lot of tim
```sh ```sh
# Build the compiler (stage 1) # Build the compiler (stage 1)
./x.py build --stage 1 src/libstd ./x.py build src/libstd
# Subsequent builds # Subsequent builds
./x.py build --stage 1 --keep-stage 1 src/libstd ./x.py build --keep-stage 1 src/libstd
``` ```
This will take a while, especially the first time. Be wary of accidentally This will take a while, especially the first time. Be wary of accidentally
@ -228,17 +228,17 @@ different test suites [in this chapter][testing].
```sh ```sh
# First build # First build
./x.py test --stage 1 src/test/ui ./x.py test src/test/ui
# Subsequent builds # Subsequent builds
./x.py test --stage 1 src/test/ui --keep-stage 1 ./x.py test src/test/ui --keep-stage 1
``` ```
If your changes impact test output, you can use `--bless` to automatically If your changes impact test output, you can use `--bless` to automatically
update the `.stderr` files of the affected tests: update the `.stderr` files of the affected tests:
```sh ```sh
./x.py test --stage 1 src/test/ui --keep-stage 1 --bless ./x.py test src/test/ui --keep-stage 1 --bless
``` ```
While working on the compiler, it can be helpful to see if the code just While working on the compiler, it can be helpful to see if the code just
@ -290,7 +290,7 @@ planning to use a recently added nightly feature. Instead, you can just build
stage 0, which uses the current beta compiler. stage 0, which uses the current beta compiler.
```sh ```sh
./x.py build --stage 0 src/libstd ./x.py build --stage 0
``` ```
```sh ```sh
@ -303,17 +303,15 @@ stage 0, which uses the current beta compiler.
`rustdoc` uses `rustc` internals (and, of course, the standard library), so you `rustdoc` uses `rustc` internals (and, of course, the standard library), so you
will have to build the compiler and `std` once before you can build `rustdoc`. will have to build the compiler and `std` once before you can build `rustdoc`.
As before, you can use `./x.py build` to do this. As before, you can use `./x.py build` to do this. The first time you build,
However, in practice, stage 1 should be sufficient. The first time you build,
the stage-1 compiler will also be built. the stage-1 compiler will also be built.
```sh ```sh
# First build # First build
./x.py build --stage 1 src/tools/rustdoc ./x.py build
# Subsequent builds # Subsequent builds
./x.py build --stage 1 --keep-stage 1 src/tools/rustdoc ./x.py build --keep-stage 1
``` ```
As with the compiler, you can do a fast check build: As with the compiler, you can do a fast check build:
@ -326,13 +324,13 @@ Rustdoc has two types of tests: content tests and UI tests.
```sh ```sh
# Content tests # Content tests
./x.py test --stage 1 src/test/rustdoc ./x.py test src/test/rustdoc
# UI tests # UI tests
./x.py test --stage 1 src/test/rustdoc-ui ./x.py test src/test/rustdoc-ui
# Both at once # Both at once
./x.py test --stage 1 src/test/rustdoc src/test/rustdoc-ui ./x.py test src/test/rustdoc src/test/rustdoc-ui
``` ```
### Contributing code to other Rust projects ### Contributing code to other Rust projects

2
src/queries/profiling.md
View File

@ -20,7 +20,7 @@ address [issue 42678](https://github.com/rust-lang/rust/issues/42678).
Compile the compiler, up to at least stage 1: Compile the compiler, up to at least stage 1:
``` ```
python x.py --stage 1 x.py build src/libstd
``` ```
### 2. Run `rustc`, with flags ### 2. Run `rustc`, with flags

4
src/rustdoc.md
View File

@ -30,7 +30,7 @@ does is call the `main()` that's in this crate's `lib.rs`, though.)
## Cheat sheet ## Cheat sheet
* Use `./x.py build --stage 1 src/libstd src/tools/rustdoc` to make a usable * Use `./x.py build` to make a usable
rustdoc you can run on other projects. rustdoc you can run on other projects.
* Add `src/libtest` to be able to use `rustdoc --test`. * Add `src/libtest` to be able to use `rustdoc --test`.
* If you've used `rustup toolchain link local /path/to/build/$TARGET/stage1` * If you've used `rustup toolchain link local /path/to/build/$TARGET/stage1`
@ -41,7 +41,7 @@ does is call the `main()` that's in this crate's `lib.rs`, though.)
* The completed docs will be available in `build/$TARGET/doc/std`, though the * The completed docs will be available in `build/$TARGET/doc/std`, though the
bundle is meant to be used as though you would copy out the `doc` folder to bundle is meant to be used as though you would copy out the `doc` folder to
a web server, since that's where the CSS/JS and landing page are. a web server, since that's where the CSS/JS and landing page are.
* Use `x.py test --stage 1 src/test/rustdoc*` to run the tests using a stage1 rustdoc. * Use `x.py test src/test/rustdoc*` to run the tests using a stage1 rustdoc.
* See [rustdoc internals] for more information about tests. * See [rustdoc internals] for more information about tests.
* Most of the HTML printing code is in `html/format.rs` and `html/render.rs`. * Most of the HTML printing code is in `html/format.rs` and `html/render.rs`.
It's in a bunch of `fmt::Display` implementations and supplementary It's in a bunch of `fmt::Display` implementations and supplementary

35
src/tests/running.md
View File

@ -7,7 +7,7 @@ you will almost never want to use! – is as follows:
./x.py test ./x.py test
``` ```
This will build the full stage 2 compiler and then run the whole test This will build the stage 1 compiler and then run the whole test
suite. You probably don't want to do this very often, because it takes suite. You probably don't want to do this very often, because it takes
a very long time, and anyway bors / travis will do it for you. (Often, a very long time, and anyway bors / travis will do it for you. (Often,
I will run this command in the background after opening a PR that I I will run this command in the background after opening a PR that I
@ -29,35 +29,34 @@ If you are building gdb from source, you will need to configure with
## Running a subset of the test suites ## Running a subset of the test suites
When working on a specific PR, you will usually want to run a smaller When working on a specific PR, you will usually want to run a smaller
set of tests, and with a stage 1 build. For example, a good "smoke set of tests. For example, a good "smoke test" that can be used after
test" that can be used after modifying rustc to see if things are modifying rustc to see if things are generally working correctly would be the
generally working correctly would be the following: following:
```bash ```bash
./x.py test --stage 1 src/test/{ui,compile-fail} ./x.py test src/test/{ui,compile-fail}
``` ```
This will run the `ui` and `compile-fail` test suites, This will run the `ui` and `compile-fail` test suites. Of course, the choice
and only with the stage 1 build. Of course, the choice of test suites of test suites is somewhat arbitrary, and may not suit the task you are
is somewhat arbitrary, and may not suit the task you are doing. For doing. For example, if you are hacking on debuginfo, you may be better off
example, if you are hacking on debuginfo, you may be better off with with the debuginfo test suite:
the debuginfo test suite:
```bash ```bash
./x.py test --stage 1 src/test/debuginfo ./x.py test src/test/debuginfo
``` ```
If you only need to test a specific subdirectory of tests for any If you only need to test a specific subdirectory of tests for any
given test suite, you can pass that directory to `x.py test`: given test suite, you can pass that directory to `x.py test`:
```bash ```bash
./x.py test --stage 1 src/test/ui/const-generics ./x.py test src/test/ui/const-generics
``` ```
Likewise, you can test a single file by passing its path: Likewise, you can test a single file by passing its path:
```bash ```bash
./x.py test --stage 1 src/test/ui/const-generics/const-test.rs ./x.py test src/test/ui/const-generics/const-test.rs
``` ```
### Run only the tidy script ### Run only the tidy script
@ -81,7 +80,7 @@ Likewise, you can test a single file by passing its path:
### Run tests on the standard library using a stage 1 compiler ### Run tests on the standard library using a stage 1 compiler
```bash ```bash
> ./x.py test src/libstd --stage 1 > ./x.py test src/libstd
``` ```
By listing which test suites you want to run you avoid having to run By listing which test suites you want to run you avoid having to run
@ -99,7 +98,7 @@ you may pass the full file path to achieve this, or alternatively one
may invoke `x.py` with the `--test-args` option: may invoke `x.py` with the `--test-args` option:
```bash ```bash
./x.py test --stage 1 src/test/ui --test-args issue-1234 ./x.py test src/test/ui --test-args issue-1234
``` ```
Under the hood, the test runner invokes the standard rust test runner Under the hood, the test runner invokes the standard rust test runner
@ -114,7 +113,7 @@ making a new test, you can pass `--bless` to the test subcommand. E.g.
if some tests in `src/test/ui` are failing, you can run if some tests in `src/test/ui` are failing, you can run
```text ```text
./x.py test --stage 1 src/test/ui --bless ./x.py test src/test/ui --bless
``` ```
to automatically adjust the `.stderr`, `.stdout` or `.fixed` files of to automatically adjust the `.stderr`, `.stdout` or `.fixed` files of
@ -130,7 +129,7 @@ exists in the test file. For example, you can run all the tests in
`src/test/ui` as `check-pass`: `src/test/ui` as `check-pass`:
```bash ```bash
./x.py test --stage 1 src/test/ui --pass check ./x.py test src/test/ui --pass check
``` ```
By passing `--pass $mode`, you can reduce the testing time. For each By passing `--pass $mode`, you can reduce the testing time. For each
@ -144,7 +143,7 @@ You can further enable the `--incremental` flag to save additional
time in subsequent rebuilds: time in subsequent rebuilds:
```bash ```bash
./x.py test --stage 1 src/test/ui --incremental --test-args issue-1234 ./x.py test src/test/ui --incremental --test-args issue-1234
``` ```
If you don't want to include the flag with every command, you can If you don't want to include the flag with every command, you can