bootstrap readme: fix, improve, update · rust-lang/rust@816dc96 (original) (raw)
1
1
`# rustbuild - Bootstrapping Rust
`
2
2
``
3
``
`-
This README is aimed at helping to explain how Rust is bootstrapped and in general,
`
4
``
`-
some of the technical details of the build system.
`
``
3
`+
This README is aimed at helping to explain how Rust is bootstrapped,
`
``
4
`+
and some of the technical details of the build system.
`
5
5
``
6
6
`Note that this README only covers internal information, not how to use the tool.
`
7
7
`Please check [bootstrapping dev guide][bootstrapping-dev-guide] for further information.
`
`@@ -10,12 +10,12 @@ Please check [bootstrapping dev guide][bootstrapping-dev-guide] for further info
`
10
10
``
11
11
`## Introduction
`
12
12
``
13
``
`-
The build system defers most of the complicated logic managing invocations
`
``
13
`+
The build system defers most of the complicated logic of managing invocations
`
14
14
`of rustc and rustdoc to Cargo itself. However, moving through various stages
`
15
15
`and copying artifacts is still necessary for it to do. Each time rustbuild
`
16
16
`is invoked, it will iterate through the list of predefined steps and execute
`
17
17
`each serially in turn if it matches the paths passed or is a default rule.
`
18
``
`-
For each step rustbuild relies on the step internally being incremental and
`
``
18
`+
For each step, rustbuild relies on the step internally being incremental and
`
19
19
`` parallel. Note, though, that the -j parameter to rustbuild gets forwarded
``
20
20
`to appropriate test harnesses and such.
`
21
21
``
`@@ -24,7 +24,7 @@ to appropriate test harnesses and such.
`
24
24
`The rustbuild build system goes through a few phases to actually build the
`
25
25
`compiler. What actually happens when you invoke rustbuild is:
`
26
26
``
27
``
`` -
- The entry point script(
xfor unix like systems,x.ps1for windows systems,
``
``
27
`` +
- The entry point script (
xfor unix like systems,x.ps1for windows systems,
``
28
28
`` x.py cross-platform) is run. This script is responsible for downloading the stage0
``
29
29
` compiler/Cargo binaries, and it then compiles the build system itself (this folder).
`
30
30
`` Finally, it then invokes the actual bootstrap binary build system.
``
`@@ -107,12 +107,13 @@ build/
`
107
107
``
108
108
`# Location where the stage0 Cargo and Rust compiler are unpacked. This
`
109
109
`# directory is purely an extracted and overlaid tarball of these two (done
`
110
``
`-
by the bootstrap python script). In theory, the build system does not
`
``
110
`+
by the bootstrap Python script). In theory, the build system does not
`
111
111
`# modify anything under this directory afterwards.
`
112
112
` stage0/
`
113
113
``
114
114
`# These to-build directories are the cargo output directories for builds of
`
115
``
`-
the standard library and compiler, respectively. Internally, these may also
`
``
115
`+
the standard library, the test system, the compiler, and various tools,
`
``
116
`+
respectively. Internally, these may also
`
116
117
`# have other target directories, which represent artifacts being compiled
`
117
118
`# from the host to the specified target.
`
118
119
`#
`
`@@ -169,17 +170,17 @@ read by the other.
`
169
170
``
170
171
`Some general areas that you may be interested in modifying are:
`
171
172
``
172
``
`` -
- Adding a new build tool? Take a look at
bootstrap/tool.rsfor examples of
``
173
``
`-
other tools.
`
``
173
`` +
- Adding a new build tool? Take a look at
bootstrap/src/core/build_steps/tool.rs
``
``
174
`+
for examples of other tools.
`
174
175
`* Adding a new compiler crate? Look no further! Adding crates can be done by
`
175
``
`` -
adding a new directory with Cargo.toml followed by configuring all
``
``
176
`` +
adding a new directory with Cargo.toml, followed by configuring all
``
176
177
`` Cargo.toml files accordingly.
``
177
178
`* Adding a new dependency from crates.io? This should just work inside the
`
178
179
` compiler artifacts stage (everything other than libtest and libstd).
`
179
``
`` -
- Adding a new configuration option? You'll want to modify
bootstrap/flags.rs
``
180
``
`` -
for command line flags and then bootstrap/config.rs to copy the flags to the
``
``
180
`` +
- Adding a new configuration option? You'll want to modify
bootstrap/src/core/config/flags.rs
``
``
181
`` +
for command line flags and then bootstrap/src/core/config/config.rs to copy the flags to the
``
181
182
`` Config struct.
``
182
``
`` -
- Adding a sanity check? Take a look at
bootstrap/sanity.rs.
``
``
183
`` +
- Adding a sanity check? Take a look at
bootstrap/src/core/sanity.rs.
``
183
184
``
184
185
`If you make a major change on bootstrap configuration, please remember to:
`
185
186
``