1 # How to build and run the compiler
5 The compiler is built using a tool called `x.py`. You will need to
6 have Python installed to run it.
8 For instructions on how to install Python and other prerequisites,
9 see [the `rust-lang/rust` README][readme].
11 ## Get the source code
13 The main repository is [`rust-lang/rust`][repo]. This contains the compiler,
14 the standard library (including `core`, `alloc`, `test`, `proc_macro`, etc),
15 and a bunch of tools (e.g. `rustdoc`, the bootstrapping infrastructure, etc).
17 [repo]: https://github.com/rust-lang/rust
18 [readme]: https://github.com/rust-lang/rust#building-on-a-unix-like-system
20 The very first step to work on `rustc` is to clone the repository:
23 git clone https://github.com/rust-lang/rust.git
27 ### Shallow clone the repository
29 Due to the size of the repository, cloning on a slower internet connection can take a long time.
30 To sidestep this, you can use the `--depth N` option with the `git clone` command.
31 This instructs `git` to perform a "shallow clone", cloning the repository but truncating it to
34 Passing `--depth 1` tells `git` to clone the repository but truncate the history to the latest
35 commit that is on the `master` branch, which is usually fine for browsing the source code or
36 building the compiler.
39 git clone --depth 1 https://github.com/rust-lang/rust.git
43 > **NOTE**: A shallow clone limits which `git` commands can be run.
44 > If you intend to work on and contribute to the compiler, it is
45 > generally recommended to fully clone the repository [as shown above](#get-the-source-code).
47 > For example, `git bisect` and `git blame` require access to the commit history,
48 > so they don't work if the repository was cloned with `--depth 1`.
52 `x.py` is the build tool for the `rust` repository. It can build docs, run tests, and compile the
53 compiler and standard library.
55 This chapter focuses on the basics to be productive, but
56 if you want to learn more about `x.py`, [read this chapter][bootstrap].
58 [bootstrap]: ./bootstrapping.md
60 ### Running `x.py` slightly more conveniently
62 There is a binary that wraps `x.py` called `x` in `src/tools/x`. All it does is
63 run `x.py`, but it can be installed system-wide and run from any subdirectory
64 of a checkout. It also looks up the appropriate version of `python` to use.
66 You can install it with `cargo install --path src/tools/x`.
68 ## Create a `config.toml`
70 To start, run `./x.py setup`. This will do some initialization and create a
71 `config.toml` for you with reasonable defaults.
73 Alternatively, you can write `config.toml` by hand. See `config.example.toml` for all the available
74 settings and explanations of them. See `src/bootstrap/defaults` for common settings to change.
76 If you have already built `rustc` and you change settings related to LLVM, then you may have to
77 execute `rm -rf build` for subsequent configuration changes to take effect. Note that `./x.py
78 clean` will not cause a rebuild of LLVM.
80 ## Common `x.py` commands
82 Here are the basic invocations of the `x.py` commands most commonly used when
83 working on `rustc`, `std`, `rustdoc`, and other tools.
85 | Command | When to use it |
87 | `./x.py check` | Quick check to see if most things compile; [rust-analyzer can run this automatically for you][rust-analyzer] |
88 | `./x.py build` | Builds `rustc`, `std`, and `rustdoc` |
89 | `./x.py test` | Runs all tests |
90 | `./x.py fmt` | Formats all code |
92 As written, these commands are reasonable starting points. However, there are
93 additional options and arguments for each of them that are worth learning for
94 serious development work. In particular, `./x.py build` and `./x.py test`
95 provide many ways to compile or test a subset of the code, which can save a lot
98 Also, note that `x.py` supports all kinds of path suffixes for `compiler`, `library`,
99 and `src/tools` directories. So, you can simply run `x.py test tidy` instead of
100 `x.py test src/tools/tidy`. Or, `x.py build std` instead of `x.py build library/std`.
102 [rust-analyzer]: ./building/suggested.html#configuring-rust-analyzer-for-rustc
104 See the chapters on [building](./building/how-to-build-and-run.md),
105 [testing](./tests/intro.md), and [rustdoc](./rustdoc.md) for more details.
107 ### Building the compiler
109 Note that building will require a relatively large amount of storage space.
110 You may want to have upwards of 10 or 15 gigabytes available to build the compiler.
112 Once you've created a `config.toml`, you are now ready to run
113 `x.py`. There are a lot of options here, but let's start with what is
114 probably the best "go to" command for building a local compiler:
120 This may *look* like it only builds the standard library, but that is not the case.
121 What this command does is the following:
123 - Build `std` using the stage0 compiler
124 - Build `rustc` using the stage0 compiler
125 - This produces the stage1 compiler
126 - Build `std` using the stage1 compiler
128 This final product (stage1 compiler + libs built using that compiler)
129 is what you need to build other Rust programs (unless you use `#![no_std]` or
132 You will probably find that building the stage1 `std` is a bottleneck for you,
133 but fear not, there is a (hacky) workaround...
134 see [the section on avoiding rebuilds for std][keep-stage].
136 [keep-stage]: ./suggested.md#faster-builds-with---keep-stage
138 Sometimes you don't need a full build. When doing some kind of
139 "type-based refactoring", like renaming a method, or changing the
140 signature of some function, you can use `./x.py check` instead for a much faster build.
142 Note that this whole command just gives you a subset of the full `rustc`
143 build. The **full** `rustc` build (what you get with `./x.py build
144 --stage 2 compiler/rustc`) has quite a few more steps:
146 - Build `rustc` with the stage1 compiler.
147 - The resulting compiler here is called the "stage2" compiler.
148 - Build `std` with stage2 compiler.
149 - Build `librustdoc` and a bunch of other things with the stage2 compiler.
151 You almost never need to do this.
153 ### Build specific components
155 If you are working on the standard library, you probably don't need to build
156 the compiler unless you are planning to use a recently added nightly feature.
157 Instead, you can just build using the bootstrap compiler.
160 ./x.py build --stage 0 library
163 If you choose the `library` profile when running `x.py setup`, you can omit `--stage 0` (it's the
166 ## Creating a rustup toolchain
168 Once you have successfully built `rustc`, you will have created a bunch
169 of files in your `build` directory. In order to actually run the
170 resulting `rustc`, we recommend creating rustup toolchains. The first
171 one will run the stage1 compiler (which we built above). The second
172 will execute the stage2 compiler (which we did not build, but which
173 you will likely need to build at some point; for example, if you want
174 to run the entire test suite).
177 rustup toolchain link stage0 build/host/stage0-sysroot # beta compiler + stage0 std
178 rustup toolchain link stage1 build/host/stage1
179 rustup toolchain link stage2 build/host/stage2
182 Now you can run the `rustc` you built with. If you run with `-vV`, you
183 should see a version number ending in `-dev`, indicating a build from
184 your local environment:
192 host: x86_64-unknown-linux-gnu
197 The rustup toolchain points to the specified toolchain compiled in your `build` directory,
198 so the rustup toolchain will be updated whenever `x.py build` or `x.py test` are run for
199 that toolchain/stage.
201 **Note:** the toolchain we've built does not include `cargo`. In this case, `rustup` will
202 fall back to using `cargo` from the installed `nightly`, `beta`, or `stable` toolchain
203 (in that order). If you need to use unstable `cargo` flags, be sure to run
204 `rustup install nightly` if you haven't already. See the
205 [rustup documentation on custom toolchains](https://rust-lang.github.io/rustup/concepts/toolchains.html#custom-toolchains).
207 **Note:** rust-analyzer and IntelliJ Rust plugin use a component called
208 `rust-analyzer-proc-macro-srv` to work with proc macros. If you intend to use a
209 custom toolchain for a project (e.g. via `rustup override set stage1`) you may
210 want to build this component:
213 ./x.py build proc-macro-srv-cli
216 ## Building targets for cross-compilation
218 To produce a compiler that can cross-compile for other targets,
219 pass any number of `target` flags to `x.py build`.
220 For example, if your host platform is `x86_64-unknown-linux-gnu`
221 and your cross-compilation target is `wasm32-wasi`, you can build with:
224 ./x.py build --target x86_64-unknown-linux-gnu --target wasm32-wasi
227 Note that if you want the resulting compiler to be able to build crates that
228 involve proc macros or build scripts, you must be sure to explicitly build target support for the
229 host platform (in this case, `x86_64-unknown-linux-gnu`).
231 If you want to always build for other targets without needing to pass flags to `x.py build`,
232 you can configure this in the `[build]` section of your `config.toml` like so:
236 target = ["x86_64-unknown-linux-gnu", "wasm32-wasi"]
239 Note that building for some targets requires having external dependencies installed
240 (e.g. building musl targets requires a local copy of musl).
241 Any target-specific configuration (e.g. the path to a local copy of musl)
242 will need to be provided by your `config.toml`.
243 Please see `config.example.toml` for information on target-specific configuration keys.
245 For examples of the complete configuration necessary to build a target, please visit
246 [the rustc book](https://doc.rust-lang.org/rustc/platform-support.html),
247 select any target under the "Platform Support" heading on the left,
248 and see the section related to building a compiler for that target.
249 For targets without a corresponding page in the rustc book,
250 it may be useful to [inspect the Dockerfiles](../tests/docker.md)
251 that the Rust infrastructure itself uses to set up and configure cross-compilation.
253 If you have followed the directions from the prior section on creating a rustup toolchain,
254 then once you have built your compiler you will be able to use it to cross-compile like so:
257 cargo +stage1 build --target wasm32-wasi
260 ## Other `x.py` commands
262 Here are a few other useful `x.py` commands. We'll cover some of them in detail
266 - `./x.py build` – builds everything using the stage 1 compiler,
268 - `./x.py build --stage 2` – builds everything with the stage 2 compiler including
270 - Running tests (see the [section on running tests](../tests/running.html) for
272 - `./x.py test library/std` – runs the unit tests and integration tests from `std`
273 - `./x.py test tests/ui` – runs the `ui` test suite
274 - `./x.py test tests/ui/const-generics` - runs all the tests in
275 the `const-generics/` subdirectory of the `ui` test suite
276 - `./x.py test tests/ui/const-generics/const-types.rs` - runs
277 the single test `const-types.rs` from the `ui` test suite
279 ### Cleaning out build directories
281 Sometimes you need to start fresh, but this is normally not the case.
282 If you need to run this then `rustbuild` is most likely not acting right and
283 you should file a bug as to what is going wrong. If you do need to clean
284 everything up then you only need to run one command!
290 `rm -rf build` works too, but then you have to rebuild LLVM, which can take
291 a long time even on fast computers.