diff --git a/src/how-to-build-and-run.md b/src/how-to-build-and-run.md index aef5b66b..2285b268 100644 --- a/src/how-to-build-and-run.md +++ b/src/how-to-build-and-run.md @@ -49,11 +49,12 @@ use-jemalloc = false ### Running x.py and building a stage1 compiler -One thing to keep in mind is that `rustc` is a _bootstrapping_ compiler. That -is, since `rustc` is written in Rust, we need to use an older version of the -compiler to compile the newer version. In particular, the newer version of the -compiler, `libstd`, and other tooling may use some unstable features -internally. The result is the compiling `rustc` is done in stages: +One thing to keep in mind is that `rustc` is a _bootstrapping_ +compiler. That is, since `rustc` is written in Rust, we need to use an +older version of the compiler to compile the newer version. In +particular, the newer version of the compiler, `libstd`, and other +tooling may use some unstable features internally. The result is that +compiling `rustc` is done in stages: - **Stage 0:** the stage0 compiler is usually the current _beta_ compiler (`x.py` will download it for you); you can configure `x.py` to use something @@ -73,10 +74,11 @@ internally. The result is the compiling `rustc` is done in stages: with stage1.) - **Stage 2:** we rebuild our stage1 compiler with itself to produce the stage2 compiler (i.e. it builds itself) to have all the _latest - optimizations_. + optimizations_. (By default, we copy the stage1 libraries for use by + the stage2 compiler, since they ought to be identical.) - _(Optional)_ **Stage 3**: to sanity check of our new compiler, we - can build it again with stage2 compiler which must be identical to - itself, unless something has broken. + can build the libraries with the stage2 compiler. The result ought + to be identical to before, unless something has broken. For hacking, often building the stage 1 compiler is enough, but for final testing and release, the stage 2 compiler is used. @@ -86,7 +88,7 @@ It is, in particular, very useful when you're doing some kind of "type-based refactoring", like renaming a method, or changing the signature of some function. - + Once you've created a config.toml, you are now ready to run `x.py`. There are a lot of options here, but let's start with what is @@ -104,8 +106,8 @@ What this command does is the following: - This produces the stage1 compiler - Build libstd using the stage1 compiler (cannot use incremental) -This final product (stage1 compiler + libs build using that compiler) -is what you need to build other rust programs. +This final product (stage1 compiler + libs built using that compiler) +is what you need to build other rust programs. Note that the command includes the `-i` switch. This enables incremental compilation. This will be used to speed up the first two steps of the process: @@ -125,7 +127,7 @@ 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 librustc rustc with the stage1 compiler. +- Build librustc and rustc with the stage1 compiler. - The resulting compiler here is called the "stage2" compiler. - Build libstd with stage2 compiler. - Build librustdoc and a bunch of other things with the stage2 compiler. @@ -168,7 +170,7 @@ release: 1.25.0-dev LLVM version: 4.0 ``` - + ### Suggested workflows for faster builds of the compiler @@ -188,7 +190,7 @@ refactoring commits and only run the tests at some later time. You can then use `git bisect` to track down **precisely** which commit caused the problem. A nice side-effect of this style is that you are left with a fairly fine-grained set of commits at the end, all of which -build and pass testes. This often helps reviewing. +build and pass tests. This often helps reviewing. **Incremental builds with `--keep-stage`.** Sometimes just checking whether the compiler builds is not enough. A common example is that @@ -216,7 +218,7 @@ encodes types and other states into the `rlib` files, or if you are editing things that wind up in the metadata (such as the definition of the MIR). **The TL;DR is that you might get weird behavior from a compile when -using `--keep-stage 1`** -- for example, strange ICEs or other +using `--keep-stage 1`** -- for example, strange [ICEs](appendix/glossary.html) or other panics. In that case, you should simply remove the `--keep-stage 1` from the command and rebuild. That ought to fix the problem.