diff options
Diffstat (limited to 'src/bootstrap/README.md')
| -rw-r--r-- | src/bootstrap/README.md | 49 |
1 files changed, 47 insertions, 2 deletions
diff --git a/src/bootstrap/README.md b/src/bootstrap/README.md index d0b501e4d89..ac84edb4038 100644 --- a/src/bootstrap/README.md +++ b/src/bootstrap/README.md @@ -22,7 +22,7 @@ Note that if you're on Unix you should be able to execute the script directly: ./x.py build ``` -The script accepts commands, flags, and filters to determine what to do: +The script accepts commands, flags, and arguments to determine what to do: * `build` - a general purpose command for compiling code. Alone `build` will bootstrap the entire compiler, and otherwise arguments passed indicate what to @@ -42,6 +42,15 @@ The script accepts commands, flags, and filters to determine what to do: ./x.py build --stage 0 src/libtest ``` + If files are dirty that would normally be rebuilt from stage 0, that can be + overidden using `--keep-stage 0`. Using `--keep-stage n` will skip all steps + that belong to stage n or earlier: + + ``` + # keep old build products for stage 0 and build stage 1 + ./x.py build --keep-stage 0 --stage 1 + ``` + * `test` - a command for executing unit tests. Like the `build` command this will execute the entire test suite by default, and otherwise it can be used to select which test suite is run: @@ -54,7 +63,7 @@ The script accepts commands, flags, and filters to determine what to do: ./x.py test src/test/run-pass # execute only some tests in the run-pass test suite - ./x.py test src/test/run-pass --filter my-filter + ./x.py test src/test/run-pass --test-args substring-of-test-name # execute tests in the standard library in stage0 ./x.py test --stage 0 src/libstd @@ -107,6 +116,42 @@ compiler. What actually happens when you invoke rustbuild is: The goal of each stage is to (a) leverage Cargo as much as possible and failing that (b) leverage Rust as much as possible! +## Incremental builds + +You can configure rustbuild to use incremental compilation. Because +incremental is new and evolving rapidly, if you want to use it, it is +recommended that you replace the snapshot with a locally installed +nightly build of rustc. You will want to keep this up to date. + +To follow this course of action, first thing you will want to do is to +install a nightly, presumably using `rustup`. You will then want to +configure your directory to use this build, like so: + +``` +# configure to use local rust instead of downloding a beta. +# `--local-rust-root` is optional here. If elided, we will +# use whatever rustc we find on your PATH. +> configure --enable-rustbuild --local-rust-root=~/.cargo/ --enable-local-rebuild +``` + +After that, you can use the `--incremental` flag to actually do +incremental builds: + +``` +> ../x.py build --incremental +``` + +The `--incremental` flag will store incremental compilation artifacts +in `build/<host>/stage0-incremental`. Note that we only use incremental +compilation for the stage0 -> stage1 compilation -- this is because +the stage1 compiler is changing, and we don't try to cache and reuse +incremental artifacts across different versions of the compiler. For +this reason, `--incremental` defaults to `--stage 1` (though you can +manually select a higher stage, if you prefer). + +You can always drop the `--incremental` to build as normal (but you +will still be using the local nightly as your bootstrap). + ## Directory Layout This build system houses all output under the `build` directory, which looks |