Building Specific Components, Creating a Rustup Toolchain, and Building Targets for Cross-Compilation

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 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 build --stage 2 compiler/rustc`) has quite a few more steps: - Build `rustc` with the stage1 compiler. - The resulting compiler here is called the "stage2" compiler, which uses stage1 std from the previous command. - Build `librustdoc` and a bunch of other things with the stage2 compiler. You almost never need to do this. ### Build specific components If you are working on the standard library, you probably don't need to build every other default component. Instead, you can build a specific component by providing its name, like this: ```bash ./x build --stage 1 library ``` If you choose the `library` profile when running `x setup`, you can omit `--stage 1` (it's the default). ## Creating a rustup toolchain Once you have successfully built `rustc`, you will have created a bunch of files in your `build` directory. In order to actually run the resulting `rustc`, we recommend creating rustup toolchains. The first one will run the stage1 compiler (which we built above). The second will execute the stage2 compiler (which we did not build, but which you will likely need to build at some point; for example, if you want to run the entire test suite). ```bash rustup toolchain link stage1 build/host/stage1 rustup toolchain link stage2 build/host/stage2 ``` Now you can run the `rustc` you built with. If you run with `-vV`, you should see a version number ending in `-dev`, indicating a build from your local environment: ```bash $ rustc +stage1 -vV rustc 1.48.0-dev binary: rustc commit-hash: unknown commit-date: unknown host: x86_64-unknown-linux-gnu release: 1.48.0-dev LLVM version: 11.0 ``` The rustup toolchain points to the specified toolchain compiled in your `build` directory, so the rustup toolchain will be updated whenever `x build` or `x test` are run for that toolchain/stage. **Note:** the toolchain we've built does not include `cargo`. In this case, `rustup` will fall back to using `cargo` from the installed `nightly`, `beta`, or `stable` toolchain (in that order). If you need to use unstable `cargo` flags, be sure to run `rustup install nightly` if you haven't already. See the [rustup documentation on custom toolchains](https://rust-lang.github.io/rustup/concepts/toolchains.html#custom-toolchains). **Note:** rust-analyzer and IntelliJ Rust plugin use a component called `rust-analyzer-proc-macro-srv` to work with proc macros. If you intend to use a custom toolchain for a project (e.g. via `rustup override set stage1`) you may want to build this component: ```bash ./x build proc-macro-srv-cli ``` ## Building targets for cross-compilation To produce a compiler that can cross-compile for other targets, pass any number of `target` flags to `x build`. For example, if your host platform is `x86_64-unknown-linux-gnu` and your cross-compilation target is `wasm32-wasip1`, you can build with: ```bash ./x build --target x86_64-unknown-linux-gnu,wasm32-wasip1 ``` Note that if you want the resulting compiler to be able to build crates that involve proc macros or build scripts, you must be sure to explicitly build target support for the host platform (in this case, `x86_64-unknown-linux-gnu`).

This section explains how to build specific components of the standard library and provides instructions for creating rustup toolchains to run the compiled `rustc`. It details how to link the stage1 and stage2 compilers to rustup and verify the version. It also touches upon the need for `cargo` and mentions `rust-analyzer` integration. The final part of the section covers building targets for cross-compilation by using the `--target` flag with `x build`.