Update docs to match the new x.py defaults (#813)
This commit is contained in:
Joshua Nelson
GitHub
parent
593facff2a
commit
879ca582de
|
|
@ -132,7 +132,7 @@ git submodule update --remote src/doc/rustc-dev-guide
|
|||
git add -u
|
||||
git commit -m "Update rustc-dev-guide"
|
||||
# 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
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -9,11 +9,14 @@ since documentation is more about the content.
|
|||
|
||||
## Document everything
|
||||
|
||||
This uses the beta rustdoc, which usually but not always has the same output
|
||||
as stage 1 rustdoc.
|
||||
|
||||
```bash
|
||||
./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
|
||||
./x.py doc --stage 1
|
||||
|
|
|
|||
|
|
@ -62,19 +62,6 @@ debug = true
|
|||
# compiler.
|
||||
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
|
||||
incremental = true
|
||||
|
||||
|
|
@ -147,10 +134,9 @@ To read more about the bootstrap process, [read this chapter][bootstrap].
|
|||
|
||||
## Building the Compiler
|
||||
|
||||
To build a compiler, run `./x.py build`. This will do the whole bootstrapping
|
||||
process described above, producing a usable compiler toolchain from the source
|
||||
code you have checked out. This takes a long time, so it is not usually what
|
||||
you want to actually run (more on this later).
|
||||
To build a compiler, run `./x.py build`. This will build up to the stage1 compiler,
|
||||
including `rustdoc`, producing a usable compiler toolchain from the source
|
||||
code you have checked out.
|
||||
|
||||
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.
|
||||
|
|
@ -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:
|
||||
|
||||
```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.
|
||||
|
|
@ -220,8 +206,8 @@ there is a (hacky) workaround. See [the section on "recommended
|
|||
workflows"](./suggested.md) below.
|
||||
|
||||
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`) has quite a few more steps:
|
||||
build. The **full** `rustc` build (what you get if you say `./x.py build
|
||||
--stage 2 src/rustc`) has quite a few more steps:
|
||||
|
||||
- Build `librustc` and `rustc` with the stage1 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
|
||||
```
|
||||
|
||||
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
|
||||
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
|
||||
|
|
@ -296,16 +276,16 @@ Here are a few other useful `x.py` commands. We'll cover some of them in detail
|
|||
in other sections:
|
||||
|
||||
- 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`
|
||||
- `./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
|
||||
more details):
|
||||
- `./x.py test --stage 1 src/libstd` – runs the `#[test]` tests from `libstd`
|
||||
- `./x.py test --stage 1 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/libstd` – runs the `#[test]` tests from `libstd`
|
||||
- `./x.py test src/test/ui` – runs the `ui` test suite
|
||||
- `./x.py test src/test/ui/const-generics` - runs all the tests in
|
||||
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
|
||||
|
||||
### Cleaning out build directories
|
||||
|
|
|
|||
|
|
@ -58,13 +58,13 @@ don't work (but that is easily detected and fixed).
|
|||
|
||||
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
|
||||
stage1 compiler as part of running all stage0 commands (which include
|
||||
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)
|
||||
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
|
||||
|
||||
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:
|
||||
|
||||
- Initial test run: `./x.py test -i --stage 1 src/test/ui`
|
||||
- Subsequent test run: `./x.py test -i --stage 1 src/test/ui --keep-stage 1`
|
||||
- Initial test run: `./x.py test -i src/test/ui`
|
||||
- Subsequent test run: `./x.py test -i src/test/ui --keep-stage 1`
|
||||
|
||||
## Fine-tuning optimizations
|
||||
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
In many cases, you don't need a full `./x.py doc`, which will build the entire
|
||||
stage 2 compiler and compile the various books published on
|
||||
In many cases, you don't need a full `./x.py doc --stage 2`, which will build
|
||||
the entire stage 2 compiler and compile the various books published on
|
||||
[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
|
||||
see the output from the latest version of `rustdoc`, use `--stage 1` instead of
|
||||
`--stage 0`. Results should appear in `build/$TARGET/crate-docs`.
|
||||
first try `./x.py doc src/libstd`. If that fails, or if you need to
|
||||
see the output from the latest version of `rustdoc`, add `--stage 1`.
|
||||
Results should appear in `build/$TARGET/crate-docs`.
|
||||
|
||||
[docs]: https://doc.rust-lang.org
|
||||
|
||||
|
|
|
|||
|
|
@ -175,19 +175,19 @@ should still read the rest of the section:
|
|||
| 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 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 --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 test --stage 1 [--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 build` | 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 build --stage 0 [src/libstd]` | Build only the standard library, without building the compiler |
|
||||
| `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 --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 [--keep-stage 1]` | Run the test suite using the stage1 compiler |
|
||||
| `x.py test --bless [--keep-stage 1]` | Run the test suite using the stage1 compiler _and_ update expected test output. |
|
||||
| `x.py build --stage 2 src/rustc` | Do a full 2-stage build. 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
|
||||
updating `config.toml` as mentioned above):
|
||||
|
||||
```sh
|
||||
./x.py build
|
||||
./x.py build --stage 2 src/rustc
|
||||
```
|
||||
|
||||
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
|
||||
# Build the compiler (stage 1)
|
||||
./x.py build --stage 1 src/libstd
|
||||
./x.py build src/libstd
|
||||
|
||||
# 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
|
||||
|
|
@ -228,17 +228,17 @@ different test suites [in this chapter][testing].
|
|||
|
||||
```sh
|
||||
# First build
|
||||
./x.py test --stage 1 src/test/ui
|
||||
./x.py test src/test/ui
|
||||
|
||||
# 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
|
||||
update the `.stderr` files of the affected tests:
|
||||
|
||||
```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
|
||||
|
|
@ -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.
|
||||
|
||||
```sh
|
||||
./x.py build --stage 0 src/libstd
|
||||
./x.py build --stage 0
|
||||
```
|
||||
|
||||
```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
|
||||
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.
|
||||
|
||||
However, in practice, stage 1 should be sufficient. The first time you build,
|
||||
As before, you can use `./x.py build` to do this. The first time you build,
|
||||
the stage-1 compiler will also be built.
|
||||
|
||||
```sh
|
||||
# First build
|
||||
./x.py build --stage 1 src/tools/rustdoc
|
||||
./x.py build
|
||||
|
||||
# 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:
|
||||
|
|
@ -326,13 +324,13 @@ Rustdoc has two types of tests: content tests and UI tests.
|
|||
|
||||
```sh
|
||||
# Content tests
|
||||
./x.py test --stage 1 src/test/rustdoc
|
||||
./x.py test src/test/rustdoc
|
||||
|
||||
# UI tests
|
||||
./x.py test --stage 1 src/test/rustdoc-ui
|
||||
./x.py test src/test/rustdoc-ui
|
||||
|
||||
# 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
|
||||
|
|
|
|||
|
|
@ -20,7 +20,7 @@ address [issue 42678](https://github.com/rust-lang/rust/issues/42678).
|
|||
Compile the compiler, up to at least stage 1:
|
||||
|
||||
```
|
||||
python x.py --stage 1
|
||||
x.py build src/libstd
|
||||
```
|
||||
|
||||
### 2. Run `rustc`, with flags
|
||||
|
|
|
|||
|
|
@ -30,7 +30,7 @@ does is call the `main()` that's in this crate's `lib.rs`, though.)
|
|||
|
||||
## 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.
|
||||
* Add `src/libtest` to be able to use `rustdoc --test`.
|
||||
* 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
|
||||
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.
|
||||
* 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.
|
||||
* 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
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ you will almost never want to use! – is as follows:
|
|||
./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
|
||||
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
|
||||
|
|
@ -29,35 +29,34 @@ If you are building gdb from source, you will need to configure with
|
|||
## Running a subset of the test suites
|
||||
|
||||
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
|
||||
test" that can be used after modifying rustc to see if things are
|
||||
generally working correctly would be the following:
|
||||
set of tests. For example, a good "smoke test" that can be used after
|
||||
modifying rustc to see if things are generally working correctly would be the
|
||||
following:
|
||||
|
||||
```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,
|
||||
and only with the stage 1 build. Of course, the choice of test suites
|
||||
is somewhat arbitrary, and may not suit the task you are doing. For
|
||||
example, if you are hacking on debuginfo, you may be better off with
|
||||
the debuginfo test suite:
|
||||
This will run the `ui` and `compile-fail` test suites. Of course, the choice
|
||||
of test suites is somewhat arbitrary, and may not suit the task you are
|
||||
doing. For example, if you are hacking on debuginfo, you may be better off
|
||||
with the debuginfo test suite:
|
||||
|
||||
```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
|
||||
given test suite, you can pass that directory to `x.py test`:
|
||||
|
||||
```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:
|
||||
|
||||
```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
|
||||
|
|
@ -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
|
||||
|
||||
```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
|
||||
|
|
@ -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:
|
||||
|
||||
```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
|
||||
|
|
@ -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
|
||||
|
||||
```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
|
||||
|
|
@ -130,7 +129,7 @@ exists in the test file. For example, you can run all the tests in
|
|||
`src/test/ui` as `check-pass`:
|
||||
|
||||
```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
|
||||
|
|
@ -144,7 +143,7 @@ You can further enable the `--incremental` flag to save additional
|
|||
time in subsequent rebuilds:
|
||||
|
||||
```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
|
||||
|
|
|
|||
Loading…
Reference in New Issue