@@ -10,24 +10,72 @@ system.
1010
1111## Using rustbuild
1212
13- When configuring Rust via ` ./configure ` , pass the following to enable building
14- via this build system:
13+ The rustbuild build system has a primary entry point, a top level ` x.py ` script:
1514
1615```
17- ./configure --enable-rustbuild
18- make
16+ python ./x.py build
1917```
2018
21- Afterwards the ` Makefile ` which is generated will have a few commands like
22- ` make check ` , ` make tidy ` , etc. For finer-grained control, the
23- ` bootstrap.py ` entry point can be used:
19+ Note that if you're on Unix you should be able to execute the script directly:
2420
2521```
26- python src/bootstrap/bootstrap .py
22+ ./x .py build
2723```
2824
29- This accepts a number of options like ` --stage ` and ` --step ` which can configure
30- what's actually being done.
25+ The script accepts commands, flags, and filters to determine what to do:
26+
27+ * ` build ` - a general purpose command for compiling code. Alone ` build ` will
28+ bootstrap the entire compiler, and otherwise arguments passed indicate what to
29+ build. For example:
30+
31+ ```
32+ # build the whole compiler
33+ ./x.py build
34+
35+ # build the stage1 compier
36+ ./x.py build --stage 1
37+
38+ # build stage0 libstd
39+ ./x.py build --stage 0 src/libstd
40+
41+ # build a particular crate in stage0
42+ ./x.py build --stage 0 src/libtest
43+ ```
44+
45+ * ` test ` - a command for executing unit tests. Like the ` build ` command this
46+ will execute the entire test suite by default, and otherwise it can be used to
47+ select which test suite is run:
48+
49+ ```
50+ # run all unit tests
51+ ./x.py test
52+
53+ # execute the run-pass test suite
54+ ./x.py test src/test/run-pass
55+
56+ # execute only some tests in the run-pass test suite
57+ ./x.py test src/test/run-pass --filter my-filter
58+
59+ # execute tests in the standard library in stage0
60+ ./x.py test --stage 0 src/libstd
61+
62+ # execute all doc tests
63+ ./x.py test src/doc
64+ ```
65+
66+ * ` doc ` - a command for building documentation. Like above can take arguments
67+ for what to document.
68+
69+ If you're more used to ` ./configure ` and ` make ` , however, then you can also
70+ configure the build system to use rustbuild instead of the old makefiles:
71+
72+ ```
73+ ./configure --enable-rustbuild
74+ make
75+ ```
76+
77+ Afterwards the ` Makefile ` which is generated will have a few commands like
78+ ` make check ` , ` make tidy ` , etc.
3179
3280## Configuring rustbuild
3381
@@ -47,7 +95,7 @@ being invoked manually (via the python script).
4795The rustbuild build system goes through a few phases to actually build the
4896compiler. What actually happens when you invoke rustbuild is:
4997
50- 1 . The entry point script, ` src/bootstrap/bootstrap .py` is run. This script is
98+ 1 . The entry point script, ` x .py` is run. This script is
5199 responsible for downloading the stage0 compiler/Cargo binaries, and it then
52100 compiles the build system itself (this folder). Finally, it then invokes the
53101 actual ` bootstrap ` binary build system.
0 commit comments