]>
Commit | Line | Data |
---|---|---|
60c5eb7d XL |
1 | # How to Build and Run the Compiler |
2 | ||
3 | The compiler is built using a tool called `x.py`. You will need to | |
4 | have Python installed to run it. But before we get to that, if you're going to | |
5 | be hacking on `rustc`, you'll want to tweak the configuration of the compiler. | |
6 | The default configuration is oriented towards running the compiler as a user, | |
7 | not a developer. | |
8 | ||
6a06907d XL |
9 | For instructions on how to install Python and other prerequisites, |
10 | see [the next page](./prerequisites.md). | |
11 | ||
12 | ## Get the source code | |
13 | ||
14 | The very first step to work on `rustc` is to clone the repository: | |
15 | ||
16 | ```bash | |
17 | git clone https://github.com/rust-lang/rust.git | |
18 | cd rust | |
19 | ``` | |
20 | ||
21 | ## Create a `config.toml` | |
60c5eb7d XL |
22 | |
23 | To start, copy [`config.toml.example`] to `config.toml`: | |
24 | ||
25 | [`config.toml.example`]: https://github.com/rust-lang/rust/blob/master/config.toml.example | |
26 | ||
27 | ```bash | |
6a06907d | 28 | cp config.toml.example config.toml |
60c5eb7d XL |
29 | ``` |
30 | ||
31 | Then you will want to open up the file and change the following | |
32 | settings (and possibly others, such as `llvm.ccache`): | |
33 | ||
34 | ```toml | |
35 | [llvm] | |
6a06907d | 36 | # Indicates whether the LLVM assertions are enabled or not |
60c5eb7d XL |
37 | assertions = true |
38 | ||
39 | [rust] | |
6a06907d XL |
40 | # Whether or not to leave debug! and trace! calls in the rust binary. |
41 | # Overrides the `debug-assertions` option, if defined. | |
42 | # | |
43 | # Defaults to rust.debug-assertions value | |
44 | # | |
45 | # If you see a message from `tracing` saying | |
46 | # `max_level_info` is enabled and means logging won't be shown, | |
47 | # set this value to `true`. | |
48 | debug-logging = true | |
49 | ||
50 | # Whether to always use incremental compilation when building rustc | |
51 | incremental = true | |
60c5eb7d XL |
52 | ``` |
53 | ||
54 | If you have already built `rustc`, then you may have to execute `rm -rf build` for subsequent | |
55 | configuration changes to take effect. Note that `./x.py clean` will not cause a | |
56 | rebuild of LLVM, so if your configuration change affects LLVM, you will need to | |
57 | manually `rm -rf build/` before rebuilding. | |
58 | ||
59 | ## What is `x.py`? | |
60 | ||
61 | `x.py` is the script used to orchestrate the tooling in the `rustc` repository. | |
62 | It is the script that can build docs, run tests, and compile `rustc`. | |
63 | It is the now preferred way to build `rustc` and it replaces the old makefiles | |
64 | from before. Below are the different ways to utilize `x.py` in order to | |
65 | effectively deal with the repo for various common tasks. | |
66 | ||
67 | This chapter focuses on the basics to be productive, but | |
68 | if you want to learn more about `x.py`, read its README.md | |
69 | [here](https://github.com/rust-lang/rust/blob/master/src/bootstrap/README.md). | |
6a06907d XL |
70 | To read more about the bootstrap process and why `x.py` is necessary, |
71 | [read this chapter][bootstrap]. | |
72 | ||
73 | ### Running `x.py` slightly more conveniently | |
74 | ||
75 | There is a binary that wraps `x.py` called `x` in `src/tools/x`. All it does is | |
76 | run `x.py`, but it can be installed system-wide and run from any subdirectory | |
77 | of a checkout. It also looks up the appropriate version of `python` to use. | |
60c5eb7d | 78 | |
6a06907d | 79 | You can install it with `cargo install --path src/tools/x`. |
60c5eb7d XL |
80 | |
81 | [bootstrap]: ./bootstrapping.md | |
82 | ||
83 | ## Building the Compiler | |
84 | ||
6a06907d XL |
85 | To build a compiler, run `./x.py build`. This will build up to the stage1 compiler, |
86 | including `rustdoc`, producing a usable compiler toolchain from the source | |
87 | code you have checked out. | |
88 | ||
89 | Note that building will require a relatively large amount of storage space. | |
90 | You may want to have upwards of 10 or 15 gigabytes available to build the compiler. | |
60c5eb7d XL |
91 | |
92 | There are many flags you can pass to the build command of `x.py` that can be | |
93 | beneficial to cutting down compile times or fitting other things you might | |
94 | need to change. They are: | |
95 | ||
96 | ```txt | |
97 | Options: | |
98 | -v, --verbose use verbose output (-vv for very verbose) | |
99 | -i, --incremental use incremental compilation | |
100 | --config FILE TOML configuration file for build | |
101 | --build BUILD build target of the stage0 compiler | |
102 | --host HOST host targets to build | |
103 | --target TARGET target targets to build | |
104 | --on-fail CMD command to run on failure | |
105 | --stage N stage to build | |
106 | --keep-stage N stage to keep without recompiling | |
107 | --src DIR path to the root of the rust checkout | |
108 | -j, --jobs JOBS number of jobs to run in parallel | |
109 | -h, --help print this help message | |
110 | ``` | |
111 | ||
112 | For hacking, often building the stage 1 compiler is enough, but for | |
113 | final testing and release, the stage 2 compiler is used. | |
114 | ||
115 | `./x.py check` is really fast to build the rust compiler. | |
116 | It is, in particular, very useful when you're doing some kind of | |
117 | "type-based refactoring", like renaming a method, or changing the | |
118 | signature of some function. | |
119 | ||
6a06907d | 120 | Once you've created a `config.toml`, you are now ready to run |
60c5eb7d XL |
121 | `x.py`. There are a lot of options here, but let's start with what is |
122 | probably the best "go to" command for building a local rust: | |
123 | ||
124 | ```bash | |
6a06907d | 125 | ./x.py build -i library/std |
60c5eb7d XL |
126 | ``` |
127 | ||
6a06907d | 128 | This may *look* like it only builds `std`, but that is not the case. |
60c5eb7d XL |
129 | What this command does is the following: |
130 | ||
6a06907d XL |
131 | - Build `std` using the stage0 compiler (using incremental) |
132 | - Build `rustc` using the stage0 compiler (using incremental) | |
60c5eb7d | 133 | - This produces the stage1 compiler |
6a06907d | 134 | - Build `std` using the stage1 compiler (cannot use incremental) |
60c5eb7d XL |
135 | |
136 | This final product (stage1 compiler + libs built using that compiler) | |
137 | is what you need to build other rust programs (unless you use `#![no_std]` or | |
138 | `#![no_core]`). | |
139 | ||
140 | The command includes the `-i` switch which enables incremental compilation. | |
141 | This will be used to speed up the first two steps of the process: | |
142 | in particular, if you make a small change, we ought to be able to use your old | |
143 | results to make producing the stage1 **compiler** faster. | |
144 | ||
145 | Unfortunately, incremental cannot be used to speed up making the | |
146 | stage1 libraries. This is because incremental only works when you run | |
147 | the *same compiler* twice in a row. In this case, we are building a | |
148 | *new stage1 compiler* every time. Therefore, the old incremental | |
149 | results may not apply. **As a result, you will probably find that | |
6a06907d | 150 | building the stage1 `std` is a bottleneck for you** -- but fear not, |
60c5eb7d XL |
151 | there is a (hacky) workaround. See [the section on "recommended |
152 | workflows"](./suggested.md) below. | |
153 | ||
154 | Note that this whole command just gives you a subset of the full `rustc` | |
6a06907d XL |
155 | build. The **full** `rustc` build (what you get if you say `./x.py build |
156 | --stage 2 compiler/rustc`) has quite a few more steps: | |
60c5eb7d | 157 | |
6a06907d | 158 | - Build `rustc` with the stage1 compiler. |
60c5eb7d | 159 | - The resulting compiler here is called the "stage2" compiler. |
6a06907d | 160 | - Build `std` with stage2 compiler. |
ba9703b0 | 161 | - Build `librustdoc` and a bunch of other things with the stage2 compiler. |
60c5eb7d XL |
162 | |
163 | <a name=toolchain></a> | |
164 | ||
165 | ## Build specific components | |
166 | ||
6a06907d | 167 | - Build only the core library |
60c5eb7d XL |
168 | |
169 | ```bash | |
6a06907d | 170 | ./x.py build --stage 0 library/core |
60c5eb7d XL |
171 | ``` |
172 | ||
6a06907d | 173 | - Build only the core and `proc_macro` libraries |
60c5eb7d XL |
174 | |
175 | ```bash | |
6a06907d | 176 | ./x.py build --stage 0 library/core library/proc_macro |
60c5eb7d XL |
177 | ``` |
178 | ||
179 | Sometimes you might just want to test if the part you’re working on can | |
180 | compile. Using these commands you can test that it compiles before doing | |
181 | a bigger build to make sure it works with the compiler. As shown before | |
6a06907d | 182 | you can also pass flags at the end such as `--stage`. |
60c5eb7d XL |
183 | |
184 | ## Creating a rustup toolchain | |
185 | ||
186 | Once you have successfully built `rustc`, you will have created a bunch | |
187 | of files in your `build` directory. In order to actually run the | |
188 | resulting `rustc`, we recommend creating rustup toolchains. The first | |
189 | one will run the stage1 compiler (which we built above). The second | |
190 | will execute the stage2 compiler (which we did not build, but which | |
191 | you will likely need to build at some point; for example, if you want | |
192 | to run the entire test suite). | |
193 | ||
194 | ```bash | |
195 | rustup toolchain link stage1 build/<host-triple>/stage1 | |
196 | rustup toolchain link stage2 build/<host-triple>/stage2 | |
197 | ``` | |
198 | ||
199 | The `<host-triple>` would typically be one of the following: | |
200 | ||
201 | - Linux: `x86_64-unknown-linux-gnu` | |
202 | - Mac: `x86_64-apple-darwin` | |
203 | - Windows: `x86_64-pc-windows-msvc` | |
204 | ||
205 | Now you can run the `rustc` you built with. If you run with `-vV`, you | |
206 | should see a version number ending in `-dev`, indicating a build from | |
207 | your local environment: | |
208 | ||
209 | ```bash | |
210 | $ rustc +stage1 -vV | |
6a06907d | 211 | rustc 1.48.0-dev |
60c5eb7d XL |
212 | binary: rustc |
213 | commit-hash: unknown | |
214 | commit-date: unknown | |
215 | host: x86_64-unknown-linux-gnu | |
6a06907d XL |
216 | release: 1.48.0-dev |
217 | LLVM version: 11.0 | |
60c5eb7d XL |
218 | ``` |
219 | ## Other `x.py` commands | |
220 | ||
221 | Here are a few other useful `x.py` commands. We'll cover some of them in detail | |
222 | in other sections: | |
223 | ||
224 | - Building things: | |
6a06907d XL |
225 | - `./x.py build` – builds everything using the stage 1 compiler, |
226 | not just up to `std` | |
227 | - `./x.py build --stage 2` – builds the stage2 compiler | |
60c5eb7d XL |
228 | - Running tests (see the [section on running tests](../tests/running.html) for |
229 | more details): | |
6a06907d XL |
230 | - `./x.py test library/std` – runs the `#[test]` tests from `std` |
231 | - `./x.py test src/test/ui` – runs the `ui` test suite | |
232 | - `./x.py test src/test/ui/const-generics` - runs all the tests in | |
60c5eb7d | 233 | the `const-generics/` subdirectory of the `ui` test suite |
6a06907d | 234 | - `./x.py test src/test/ui/const-generics/const-types.rs` - runs |
60c5eb7d XL |
235 | the single test `const-types.rs` from the `ui` test suite |
236 | ||
237 | ### Cleaning out build directories | |
238 | ||
239 | Sometimes you need to start fresh, but this is normally not the case. | |
ba9703b0 | 240 | If you need to run this then `rustbuild` is most likely not acting right and |
60c5eb7d XL |
241 | you should file a bug as to what is going wrong. If you do need to clean |
242 | everything up then you only need to run one command! | |
243 | ||
244 | ```bash | |
245 | ./x.py clean | |
246 | ``` | |
6a06907d XL |
247 | |
248 | `rm -rf build` works too, but then you have to rebuild LLVM, which can take | |
249 | a long time even on fast computers. |