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: # system will link (using hard links) output from stageN-{std,rustc} into # each of these directories. # <del> # In theory, there is no extra build output in these directories. </del> <ins> # In theory these are working rustc sysroot directories, meaning there is # no extra build output in these directories. </ins> stage1/ stage2/ stage3/ ``` <del> ## Cargo projects The current build is unfortunately not quite as simple as `cargo build` in a directory, but rather the compiler is split into three different Cargo projects: * `library/std` - the standard library * `library/test` - testing support, depends on libstd * `compiler/rustc` - the actual compiler itself Each "project" has a corresponding Cargo.lock file with all dependencies, and this means that building the compiler involves running Cargo three times. The structure here serves two goals: 1. Facilitating dependencies coming from crates.io. These dependencies don't depend on `std`, so libstd is a separate project compiled ahead of time before the actual compiler builds. 2. Splitting "host artifacts" from "target artifacts". That is, when building code for an arbitrary target, you don't need the entire compiler, but you'll end up needing libraries like libtest that depend on std but also want to use crates.io dependencies. Hence, libtest is split out as its own project that is sequenced after `std` but before `rustc`. This project is built for all targets. There is some loss in build parallelism here because libtest can be compiled in parallel with a number of rustc artifacts, but in theory, the loss isn't too bad! ## Build tools We've actually got quite a few tools that we use in the compiler's build system and for testing. To organize these, each tool is a project in `src/tools` with a corresponding `Cargo.toml`. All tools are compiled with Cargo (currently having independent `Cargo.lock` files) and do not currently explicitly depend on the compiler or standard library. Compiling each tool is sequenced after the appropriate libstd/libtest/librustc compile above. </del> ## Extending rustbuild <del> So, you'd like to add a feature to the rustbuild build system or just fix a bug. Great! One of the major motivational factors for moving away from `make` is that Rust is in theory much easier to read, modify, and write. If you find anything excessively confusing, please open an issue on this, and we'll try to get it documented or simplified, pronto. </del> <ins> When you use the bootstrap system, you'll call it through the entry point script (`x`, `x.ps1`, or `x.py`). However, most of the code lives in `src/bootstrap`. `bootstrap` has a difficult problem: it is written in Rust, but yet it is run before the Rust compiler is built! To work around this, there are two components of bootstrap: the main one written in rust, and `bootstrap.py`. `bootstrap.py` is what gets run by entry point script. It takes care of downloading the `stage0` compiler, which will then build the bootstrap binary written in Rust. </ins> <del> First up, you'll probably want to read over the documentation above, as that'll give you a high level overview of what rustbuild is doing. You also probably want to play around a bit yourself by just getting it up and running before you dive too much into the actual build system itself. </del> <ins> Because there are two separate codebases behind `x.py`, they need to be kept in sync. In particular, both `bootstrap.py` and the bootstrap binary parse `config.toml` and read the same command line arguments. `bootstrap.py` keeps these in sync by setting various environment variables, and the programs sometimes have to add arguments that are explicitly ignored, to be read by the other. </ins> <del> After that, each module in rustbuild should have enough documentation to keep you up and running. Some general areas that you may be interested in modifying are: </del> <ins> Some general areas that you may be interested in modifying are: </ins> * Adding a new build tool? Take a look at `bootstrap/tool.rs` for examples of other tools.