is bootstrapped and in general, some of the technical details of the build system. <del> ## Using rustbuild </del> <ins> Note that this README only covers internal information, not how to use the tool. Please check [bootstrapping dev guide][bootstrapping-dev-guide] for further information. </ins> <del> The rustbuild build system has a primary entry point, a top level `x.py` script: </del> <ins> [bootstrapping-dev-guide]: https://rustc-dev-guide.rust-lang.org/building/bootstrapping.html </ins> <del> ```sh $ python ./x.py build ``` Note that if you're on Unix, you should be able to execute the script directly: ```sh $ ./x.py build ``` 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 build. For example: ``` # build the whole compiler ./x.py build --stage 2 # build the stage1 compiler ./x.py build # build stage0 libstd ./x.py build --stage 0 library/std # build a particular crate in stage0 ./x.py build --stage 0 library/test ``` If files that would normally be rebuilt from stage 0 are dirty, the rebuild can be overridden using `--keep-stage 0`. Using `--keep-stage n` will skip all steps that belong to stage n or earlier: ``` # build stage 1, keeping old build products for stage 0 ./x.py build --keep-stage 0 ``` * `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: ``` # run all unit tests ./x.py test # execute tool tests ./x.py test tidy # execute the UI test suite ./x.py test tests/ui # execute only some tests in the UI test suite ./x.py test tests/ui --test-args substring-of-test-name # execute tests in the standard library in stage0 ./x.py test --stage 0 library/std # execute tests in the core and standard library in stage0, # without running doc tests (thus avoid depending on building the compiler) ./x.py test --stage 0 --no-doc library/core library/std </del> <ins> ## Introduction </ins> <del> # execute all doc tests ./x.py test src/doc ``` </del> <ins> The build system defers most of the complicated logic managing invocations of rustc and rustdoc to Cargo itself. However, moving through various stages and copying artifacts is still necessary for it to do. Each time rustbuild is invoked, it will iterate through the list of predefined steps and execute each serially in turn if it matches the paths passed or is a default rule. For each step rustbuild relies on the step internally being incremental and parallel. Note, though, that the `-j` parameter to rustbuild gets forwarded to appropriate test harnesses and such. </ins> <del> * `doc` - a command for building documentation. Like above, can take arguments for what to document. ## Configuring rustbuild rustbuild offers a TOML-based configuration system with a `config.toml` file. An example of this configuration can be found at `config.toml.example`, and the configuration file can also be passed as `--config path/to/config.toml` if the build system is being invoked manually (via the python script). You can generate a config.toml using `./configure` options if you want to automate creating the file without having to edit it. Finally, rustbuild makes use of the [cc-rs crate] which has [its own method][env-vars] of configuring C compilers and C flags via environment variables. [cc-rs crate]: https://github.com/alexcrichton/cc-rs [env-vars]: https://github.com/alexcrichton/cc-rs#external-configuration-via-environment-variables ## Build stages </del> <ins> ## Build phases </ins> The rustbuild build system goes through a few phases to actually build the compiler. What actually happens when you invoke rustbuild is: <del> 1. The entry point script, `x.py` is run. This script is responsible for downloading the stage0 compiler/Cargo binaries, and it then compiles the build system itself (this folder). Finally, it then invokes the actual `bootstrap` binary build system. </del> <ins> 1. The entry point script(`x` for unix like systems, `x.ps1` for windows systems, `x.py` cross-platform) is run. This script is responsible for downloading the stage0 compiler/Cargo binaries, and it then compiles the build system itself (this folder). Finally, it then invokes the actual `bootstrap` binary build system. </ins> 2. In Rust, `bootstrap` will slurp up all configuration, perform a number of sanity checks (whether compilers exist, for example), and then start building the stage0 artifacts.