diff --git a/src/building/how-to-build-and-run.md b/src/building/how-to-build-and-run.md index 2fac55ed..f10619ab 100644 --- a/src/building/how-to-build-and-run.md +++ b/src/building/how-to-build-and-run.md @@ -24,34 +24,10 @@ cd rust ## Create a `config.toml` To start, run `./x.py setup`. This will do some initialization and create a -`config.toml` for you with reasonable defaults. These defaults are specified -indirectly via the `profile` setting, which points to one of the TOML files in -`src/bootstrap/defaults.` +`config.toml` for you with reasonable defaults. Alternatively, you can write `config.toml` by hand. See `config.toml.example` -for all the available settings and explanations of them. The following settings -are of particular interest, and `config.toml.example` has full explanations. - -You may want to change some of the following settings (and possibly others, such as -`llvm.ccache`): - -```toml -[llvm] -# Whether to use Rust CI built LLVM instead of locally building it. -download-ci-llvm = true # Download a pre-built LLVM? -assertions = true # LLVM assertions on? -ccache = "/path/to/ccache" # Use ccache when building LLVM? - -[rust] -debug-logging = true # Leave debug! and trace! calls in rustc? -incremental = true # Build rustc with incremental compilation? -``` - -If you set `download-ci-llvm = true`, in some circumstances, such as when -updating the version of LLVM used by `rustc`, you may want to temporarily -disable this feature. See the ["Updating LLVM" section] for more. - -["Updating LLVM" section]: ../backend/updating-llvm.md#feature-updates +for all the available settings and explanations of them. See `src/bootstrap/defaults` for common settings to change. If you have already built `rustc` and you change settings related to LLVM, then you may have to execute `rm -rf build` for subsequent configuration changes to take effect. Note that `./x.py @@ -59,17 +35,13 @@ clean` will not cause a rebuild of LLVM. ## What is `x.py`? -`x.py` is the script used to orchestrate the tooling in the `rustc` repository. -It is the script that can build docs, run tests, and compile `rustc`. -It is the now preferred way to build `rustc` and it replaces the old makefiles -from before. Below are the different ways to utilize `x.py` in order to -effectively deal with the repo for various common tasks. +`x.py` is the build tool for the `rust` repository. It can build docs, run tests, and compile the +compiler and standard library. This chapter focuses on the basics to be productive, but -if you want to learn more about `x.py`, read its README.md -[here](https://github.com/rust-lang/rust/blob/master/src/bootstrap/README.md). -To read more about the bootstrap process and why `x.py` is necessary, -[read this chapter][bootstrap]. +if you want to learn more about `x.py`, [read this chapter][bootstrap]. + +[bootstrap]: ./bootstrapping.md ### Running `x.py` slightly more conveniently @@ -79,48 +51,14 @@ of a checkout. It also looks up the appropriate version of `python` to use. You can install it with `cargo install --path src/tools/x`. -[bootstrap]: ./bootstrapping.md - ## Building the Compiler -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. -There are many flags you can pass to the build command of `x.py` that can be -beneficial to cutting down compile times or fitting other things you might -need to change. They are: - -```txt -Options: - -v, --verbose use verbose output (-vv for very verbose) - -i, --incremental use incremental compilation - --config FILE TOML configuration file for build - --build BUILD build target of the stage0 compiler - --host HOST host targets to build - --target TARGET target targets to build - --on-fail CMD command to run on failure - --stage N stage to build - --keep-stage N stage to keep without recompiling - --src DIR path to the root of the Rust checkout - -j, --jobs JOBS number of jobs to run in parallel - -h, --help print this help message -``` - -For hacking, often building the stage 1 compiler is enough, which saves a lot -of time. But for final testing and release, the stage 2 compiler is used. - -`./x.py check` is really fast to build the Rust compiler. -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 -probably the best "go to" command for building a local rust: +probably the best "go to" command for building a local compiler: ```bash ./x.py build library @@ -144,6 +82,10 @@ see [the section on avoiding rebuilds for std][keep-stage]. [keep-stage]: ./suggested.md#faster-builds-with---keep-stage +Sometimes you don't need a full build. When doing some kind of +"type-based refactoring", like renaming a method, or changing the +signature of some function, you can use `./x.py check` instead for a much faster build. + Note that this whole command just gives you a subset of the full `rustc` build. The **full** `rustc` build (what you get with `./x.py build --stage 2 compiler/rustc`) has quite a few more steps: @@ -165,6 +107,9 @@ Instead, you can just build using the bootstrap compiler. ./x.py build --stage 0 library ``` +If you choose the `library` profile when running `x.py setup`, you can omit `--stage 0` (it's the +default). + ## Creating a rustup toolchain Once you have successfully built `rustc`, you will have created a bunch @@ -273,7 +218,7 @@ in other sections: - `./x.py build` – builds everything using the stage 1 compiler, not just up to `std` - `./x.py build --stage 2` – builds everything with the stage 2 compiler including - `rustdoc` (which doesn't take too long) + `rustdoc` - Running tests (see the [section on running tests](../tests/running.html) for more details): - `./x.py test library/std` – runs the unit tests and integration tests from `std`