1 # rustbuild - Bootstrapping Rust
3 This is an in-progress README which is targeted at helping to explain how Rust
4 is bootstrapped and in general, some of the technical details of the build
7 Note that this README only covers internal information, not how to use the tool.
8 Please check [bootstrapping dev guide][bootstrapping-dev-guide] for further information.
10 [bootstrapping-dev-guide]: https://rustc-dev-guide.rust-lang.org/building/bootstrapping.html
14 The build system defers most of the complicated logic managing invocations
15 of rustc and rustdoc to Cargo itself. However, moving through various stages
16 and copying artifacts is still necessary for it to do. Each time rustbuild
17 is invoked, it will iterate through the list of predefined steps and execute
18 each serially in turn if it matches the paths passed or is a default rule.
19 For each step rustbuild relies on the step internally being incremental and
20 parallel. Note, though, that the `-j` parameter to rustbuild gets forwarded
21 to appropriate test harnesses and such.
25 The rustbuild build system goes through a few phases to actually build the
26 compiler. What actually happens when you invoke rustbuild is:
28 1. The entry point script(`x` for unix like systems, `x.ps1` for windows systems,
29 `x.py` cross-platform) is run. This script is responsible for downloading the stage0
30 compiler/Cargo binaries, and it then compiles the build system itself (this folder).
31 Finally, it then invokes the actual `bootstrap` binary build system.
32 2. In Rust, `bootstrap` will slurp up all configuration, perform a number of
33 sanity checks (whether compilers exist, for example), and then start building the
35 3. The stage0 `cargo`, downloaded earlier, is used to build the standard library
36 and the compiler, and then these binaries are then copied to the `stage1`
37 directory. That compiler is then used to generate the stage1 artifacts which
38 are then copied to the stage2 directory, and then finally, the stage2
39 artifacts are generated using that compiler.
41 The goal of each stage is to (a) leverage Cargo as much as possible and failing
42 that (b) leverage Rust as much as possible!
46 This build system houses all output under the `build` directory, which looks
50 # Root folder of all output. Everything is scoped underneath here
53 # Location where the stage0 compiler downloads are all cached. This directory
54 # only contains the tarballs themselves, as they're extracted elsewhere.
61 # Output directory for building this build system itself. The stage0
62 # cargo/rustc are used to build the build system into this location.
67 # Output of the dist-related steps like dist-std, dist-rustc, and dist-docs
70 # Temporary directory used for various input/output as part of various stages
73 # Each remaining directory is scoped by the "host" triple of compilation at
75 x86_64-unknown-linux-gnu/
77 # The build artifacts for the `compiler-rt` library for the target that
78 # this folder is under. The exact layout here will likely depend on the
79 # platform, and this is also built with CMake, so the build system is
80 # also likely different.
84 # Output folder for LLVM if it is compiled for this target
87 # build folder (e.g. the platform-specific build system). Like with
88 # compiler-rt, this is compiled with CMake
91 # Installation of LLVM. Note that we run the equivalent of 'make install'
92 # for LLVM, to setup these folders.
99 # Output folder for all documentation of this target. This is what's filled
100 # in whenever the `doc` step is run.
103 # Output for all compiletest-based test suites
109 # Location where the stage0 Cargo and Rust compiler are unpacked. This
110 # directory is purely an extracted and overlaid tarball of these two (done
111 # by the bootstrap python script). In theory, the build system does not
112 # modify anything under this directory afterwards.
115 # These to-build directories are the cargo output directories for builds of
116 # the standard library and compiler, respectively. Internally, these may also
117 # have other target directories, which represent artifacts being compiled
118 # from the host to the specified target.
120 # Essentially, each of these directories is filled in by one `cargo`
121 # invocation. The build system instruments calling Cargo in the right order
122 # with the right variables to ensure that these are filled in correctly.
128 # This is a special case of the above directories, **not** filled in via
129 # Cargo but rather the build system itself. The stage0 compiler already has
130 # a set of target libraries for its own host triple (in its own sysroot)
131 # inside of stage0/. When we run the stage0 compiler to bootstrap more
132 # things, however, we don't want to use any of these libraries (as those are
133 # the ones that we're building). So essentially, when the stage1 compiler is
134 # being compiled (e.g. after libstd has been built), *this* is used as the
135 # sysroot for the stage0 compiler being run.
137 # Basically, this directory is just a temporary artifact used to configure the
138 # stage0 compiler to ensure that the libstd that we just built is used to
139 # compile the stage1 compiler.
142 # These output directories are intended to be standalone working
143 # implementations of the compiler (corresponding to each stage). The build
144 # system will link (using hard links) output from stageN-{std,rustc} into
145 # each of these directories.
147 # In theory these are working rustc sysroot directories, meaning there is
148 # no extra build output in these directories.
154 ## Extending rustbuild
156 When you use the bootstrap system, you'll call it through the entry point script
157 (`x`, `x.ps1`, or `x.py`). However, most of the code lives in `src/bootstrap`.
158 `bootstrap` has a difficult problem: it is written in Rust, but yet it is run
159 before the Rust compiler is built! To work around this, there are two components
160 of bootstrap: the main one written in rust, and `bootstrap.py`. `bootstrap.py`
161 is what gets run by entry point script. It takes care of downloading the `stage0`
162 compiler, which will then build the bootstrap binary written in Rust.
164 Because there are two separate codebases behind `x.py`, they need to
165 be kept in sync. In particular, both `bootstrap.py` and the bootstrap binary
166 parse `config.toml` and read the same command line arguments. `bootstrap.py`
167 keeps these in sync by setting various environment variables, and the
168 programs sometimes have to add arguments that are explicitly ignored, to be
171 Some general areas that you may be interested in modifying are:
173 * Adding a new build tool? Take a look at `bootstrap/tool.rs` for examples of
175 * Adding a new compiler crate? Look no further! Adding crates can be done by
176 adding a new directory with `Cargo.toml` followed by configuring all
177 `Cargo.toml` files accordingly.
178 * Adding a new dependency from crates.io? This should just work inside the
179 compiler artifacts stage (everything other than libtest and libstd).
180 * Adding a new configuration option? You'll want to modify `bootstrap/flags.rs`
181 for command line flags and then `bootstrap/config.rs` to copy the flags to the
183 * Adding a sanity check? Take a look at `bootstrap/sanity.rs`.
185 If you make a major change, please remember to:
187 + Update `VERSION` in `src/bootstrap/main.rs`.
188 * Update `changelog-seen = N` in `config.toml.example`.
189 * Add an entry in `src/bootstrap/CHANGELOG.md`.
191 A 'major change' includes
194 * A change in the default options.
196 Changes that do not affect contributors to the compiler or users
197 building rustc from source don't need an update to `VERSION`.
199 If you have any questions, feel free to reach out on the `#t-infra/bootstrap` channel
200 at [Rust Bootstrap Zulip server][rust-bootstrap-zulip]. When you encounter bugs,
201 please file issues on the [Rust issue tracker][rust-issue-tracker].
203 [rust-bootstrap-zulip]: https://rust-lang.zulipchat.com/#narrow/stream/t-infra.2Fbootstrap
204 [rust-issue-tracker]: https://github.com/rust-lang/rust/issues