bootstrap: Describe build_steps modules #124242
Conversation
The description was most accurate when it was still called rustbuild, and I presume indeed did mostly run in CI. It has become something more so try to describe it better for current-day usage.
|
rustbot has assigned @Mark-Simulacrum. Use |
rustbot
added
S-waiting-on-review
| //! | ||
| //! These are build-and-run steps for `./x.py setup`, which allows quickly setting up the directory | ||
| //! for modifying, building, and running the compiler and library. The main convenience is to allow | ||
| //! not having to painstakingly set every single option in config.toml. |
There was a problem hiding this comment.
this is not actually the main convenience, profile = foo is enough for 99% of things. the reason this exists is:
- it gives us a single command to put in documentation
- it lets us suggest a build command based on the profile.
x.py test uimakes sense if you're working on the compiler but not if you're working on the standard library. (note that this is so important because putting commands in the readme means people will just copy paste the first one without reading it, i've seen it happen so many times) - it reduces the number of commands to get a useful environment from ~6 to 1 (it creates .vscode, it runs rustup toolchain link, etc)
- it makes profiles more discoverable; most people's instinct is to configure options one by one and that's a waste of their time.
There was a problem hiding this comment.
oh, and originally one of the goals was to avoid the trap where someone runs x.py build before configuring a profile and now they have the LLVM submodule checked out indefinitely and their life is pain. for a while now LLVM is downloaded by default if you don't have a config.toml, though, so that doesn't really apply anymore.
There was a problem hiding this comment.
it makes profiles more discoverable; most people's instinct is to configure options one by one and that's a waste of their time.
okay but isn't that just saying what I said with different words tho' <_<;
| //! | ||
| //! This file implements the various regression test suites that we execute on | ||
| //! our CI. | ||
| //! `./x.py test` (aka [`Kind::Test`]) is currently allowed to reach build steps in other modules. |
There was a problem hiding this comment.
this is true of all Steps, not just test steps - i'm curious why you've singled it out here?
There was a problem hiding this comment.
i wonder if it makes sense to link to src/bootstrap/README and/or https://rustc-dev-guide.rust-lang.org/building/bootstrapping/how-bootstrap-does-it.html in lib.rs and builder.rs respectively.
There was a problem hiding this comment.
Because most of the things run when you execute ./x.py {command} are in fact in the given {command}.rs, so the fact that this one has an exception stood out to me:
rust/src/bootstrap/src/core/builder.rs
Lines 768 to 770 in f22a0c2
|
@bors r+ rollup |
bors
added
S-waiting-on-bors
…files-better, r=Mark-Simulacrum bootstrap: Describe build_steps modules One of my preferred ways to understand source code is to start with its API. This implies the code is documented reasonably accurately, even if it is a private API. The description of one of these modules had not been updated since 2015 and so was both terse and confusing, so I rewrote it. Then I noticed many others went unremarked, so I offered some remarks.
…iaskrgr Rollup of 7 pull requests Successful merges: - rust-lang#123942 (`x vendor`) - rust-lang#124165 (add test for incremental ICE: slice-pattern-const.rs rust-lang#83085) - rust-lang#124210 (Abort a process when FD ownership is violated) - rust-lang#124242 (bootstrap: Describe build_steps modules) - rust-lang#124406 (Remove unused `[patch]` for clippy_lints) - rust-lang#124429 (bootstrap: Document `struct Builder` and its fields) - rust-lang#124447 (Unconditionally call `really_init` on GNU/Linux) r? `@ghost` `@rustbot` modify labels: rollup
…iaskrgr Rollup of 7 pull requests Successful merges: - rust-lang#123248 (1.78 release notes) - rust-lang#123942 (`x vendor`) - rust-lang#124165 (add test for incremental ICE: slice-pattern-const.rs rust-lang#83085) - rust-lang#124242 (bootstrap: Describe build_steps modules) - rust-lang#124406 (Remove unused `[patch]` for clippy_lints) - rust-lang#124429 (bootstrap: Document `struct Builder` and its fields) - rust-lang#124447 (Unconditionally call `really_init` on GNU/Linux) r? `@ghost` `@rustbot` modify labels: rollup
Rollup merge of rust-lang#124242 - workingjubilee:describe-bootstrap-files-better, r=Mark-Simulacrum bootstrap: Describe build_steps modules One of my preferred ways to understand source code is to start with its API. This implies the code is documented reasonably accurately, even if it is a private API. The description of one of these modules had not been updated since 2015 and so was both terse and confusing, so I rewrote it. Then I noticed many others went unremarked, so I offered some remarks.
One of my preferred ways to understand source code is to start with its API. This implies the code is documented reasonably accurately, even if it is a private API. The description of one of these modules had not been updated since 2015 and so was both terse and confusing, so I rewrote it. Then I noticed many others went unremarked, so I offered some remarks.