Change:
//!   crates.io and Cargo. //! * A standard interface to build across all platforms, including MSVC //! <del> //! ## Architecture //! //! 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. //! //! Most of the "meaty" steps that matter are backed by Cargo, which does indeed //! have its own parallelism and incremental management. Later steps, like //! tests, aren't incremental and simply run the entire suite currently. //! However, compiletest itself tries to avoid running tests when the artifacts //! that are involved (mainly the compiler) haven't changed. //! //! When you execute `x.py build`, the steps executed are: //! //! * First, the python script is run. This will automatically download the //!   stage0 rustc and cargo according to `src/stage0.json`, or use the cached //!   versions if they're available. These are then used to compile rustbuild //!   itself (using Cargo). Finally, control is then transferred to rustbuild. //! //! * Rustbuild takes over, performs sanity checks, probes the environment, //!   reads configuration, and starts executing steps as it reads the command //!   line arguments (paths) or going through the default rules. //! //!   The build output will be something like the following: //! //!   Building stage0 std artifacts //!   Copying stage0 std //!   Building stage0 test artifacts //!   Copying stage0 test //!   Building stage0 compiler artifacts //!   Copying stage0 rustc //!   Assembling stage1 compiler //!   Building stage1 std artifacts //!   Copying stage1 std //!   Building stage1 test artifacts //!   Copying stage1 test //!   Building stage1 compiler artifacts //!   Copying stage1 rustc //!   Assembling stage2 compiler //!   Uplifting stage1 std //!   Uplifting stage1 test //!   Uplifting stage1 rustc //! //! Let's disect that a little: //! //! ## Building stage0 {std,test,compiler} artifacts //! //! These steps use the provided (downloaded, usually) compiler to compile the //! local Rust source into libraries we can use. //! //! ## Copying stage0 {std,test,rustc} //! //! This copies the build output from Cargo into //! `build/$HOST/stage0-sysroot/lib/rustlib/$ARCH/lib`. FIXME: this step's //! documentation should be expanded -- the information already here may be //! incorrect. //! //! ## Assembling stage1 compiler //! //! This copies the libraries we built in "building stage0 ... artifacts" into //! the stage1 compiler's lib directory. These are the host libraries that the //! compiler itself uses to run. These aren't actually used by artifacts the new //! compiler generates. This step also copies the rustc and rustdoc binaries we //! generated into build/$HOST/stage/bin. //! //! The stage1/bin/rustc is a fully functional compiler, but it doesn't yet have //! any libraries to link built binaries or libraries to. The next 3 steps will //! provide those libraries for it; they are mostly equivalent to constructing //! the stage1/bin compiler so we don't go through them individually. //! //! ## Uplifting stage1 {std,test,rustc} //! //! This step copies the libraries from the stage1 compiler sysroot into the //! stage2 compiler. This is done to avoid rebuilding the compiler; libraries //! we'd build in this step should be identical (in function, if not necessarily //! identical on disk) so there's no need to recompile the compiler again. Note //! that if you want to, you can enable the full-bootstrap option to change this //! behavior. //! //! Each step is driven by a separate Cargo project and rustbuild orchestrates //! copying files between steps and otherwise preparing for Cargo to run. //! </del> //! ## Further information //! //! More documentation can be found in each respective module below, and you can

Discussion:
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.