Code change:
Right now, there are docs for x.py in a bunch of different places: https://rustc-dev- https://rustc-dev- It would be nice to consolidate these some; e.g. can probably just point to the README, and lots of the information in the readme is duplicated in the dev-guide and can be deleted and replaced with a link. cc - do you have strong opinions on this? <!-- TRIAGEBOTSTART --<!-- TRIAGEBOTASSIGNSTART --<!-- TRIAGEBOTASSIGNDATASTARTTRIAGEBOTASSIGNDATAEND --<!-- TRIAGEBOTASSIGNEND --<!-- TRIAGEBOTEND --
No, seems good to consolidate. I personally think we might get something out of ending up with two guides, one of which discusses the content from an internal perspective (e.g., Step, how to add new targets) and another from an external perspective, focusing on what users need to know. I think most of the existing documentation is sort of in the second of those, but also (potentially correctly, hard for me to say) treats things as a very leaky abstraction and documents a lot of the internals too. I think some of this is our audience, but I do wonder if a much simpler message is possible with just a few standard commands depending on what they want to build, and documenting specific outputs rather than the whole layout. I think right now we're trying to explain things by teaching everything, but perhaps we can get away with not teaching the internals of the abstraction. Anyway, mostly musing, no strong opinions here.
We should also document that we support suffixes instead of full paths (e.g. instead of ):
Hello, Should I start working on adding doc-comments in bootstrap ?
more doc-comments are always welcome :) but when I wrote the issue I was imagining coming up for a plan for how to organize the standalone documentation. maybe we can put the internal documentation in src/bootstrap/README and the user facing documentation in the guide?
claim
I like the idea and I think this standard should be applied in general since this seperation reduces cost of the maintaince and makes dev-guide more understandable and simple for users. I will follow that idea in the refactoring.

Related discussion:
text: 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.