@@ -21,7 +21,6 @@ differently from other crates that are directly in this repo:
2121* [ rust-analyzer] ( https://github.com/rust-lang/rust-analyzer )
2222
2323[ Miri ] : https://github.com/rust-lang/miri
24- [ Cargo ] : https://github.com/rust-lang/cargo
2524
2625In contrast to ` submodule ` dependencies
2726(see below for those), the ` subtree ` dependencies are just regular files and directories which can
@@ -93,8 +92,7 @@ submodules]. The complete list may be found in the [`.gitmodules`] file. Some
9392of these projects are required (like ` stdarch ` for the standard library) and
9493some of them are optional (like ` src/doc/book ` ).
9594
96- Usage of submodules is discussed more in the [ Using Git
97- chapter] ( git.md#git-submodules ) .
95+ Usage of submodules is discussed more in the [ Using Git chapter] ( git.md#git-submodules ) .
9896
9997Some of the submodules are allowed to be in a "broken" state where they
10098either don't build or their tests don't pass, e.g. the documentation books
@@ -112,49 +110,3 @@ the week leading up to the beta cut.
112110[ The Rust Reference ] : https://github.com/rust-lang/reference/
113111[ toolstate website ] : https://rust-lang-nursery.github.io/rust-toolstate/
114112[ Toolstate chapter ] : https://forge.rust-lang.org/infra/toolstate.html
115- 116- ### Breaking Tools Built With The Compiler
117- 118- Rust's build system builds a number of tools that make use of the internals of
119- the compiler and that are hosted in a separate repository, and included in Rust
120- via git submodules (such as [ Cargo] ). If these tools break because of your
121- changes, you may run into a sort of "chicken and egg" problem. These tools rely
122- on the latest compiler to be built so you can't update them (in their own
123- repositories) to reflect your changes to the compiler until those changes are
124- merged into the compiler. At the same time, you can't get your changes merged
125- into the compiler because the rust-lang/rust build won't pass until those tools
126- build and pass their tests.
127- 128- Luckily, a feature was
129- [ added to Rust's build] ( https://github.com/rust-lang/rust/issues/45861 ) to make
130- all of this easy to handle. The idea is that we allow these tools to be
131- "broken", so that the rust-lang/rust build passes without trying to build them,
132- then land the change in the compiler, and go update the tools that you
133- broke. Some tools will require waiting for a nightly release before this can
134- happen, while others use the builds uploaded after each bors merge and thus can
135- be updated immediately (check the tool's documentation for details). Once you're
136- done and the tools are working again, you go back in the compiler and update the
137- tools so they can be distributed again.
138- 139- This should avoid a bunch of synchronization dances and is also much easier on contributors as
140- there's no need to block on tools changes going upstream.
141- 142- Here are those same steps in detail:
143- 144- 1 . (optional) First, if it doesn't exist already, create a ` config.toml ` by copying
145- ` config.example.toml ` in the root directory of the Rust repository.
146- Set ` submodules = false ` in the ` [build] ` section. This will prevent ` x.py `
147- from resetting to the original branch after you make your changes. If you
148- need to [ update any submodules to their latest versions] ( #updating-submodules ) ,
149- see the section of this file about that for more information.
150- 2 . (optional) Run ` ./x.py test src/tools/cargo ` (substituting the submodule
151- that broke for ` cargo ` ). Fix any errors in the submodule (and possibly others).
152- 3 . (optional) Make commits for your changes and send them to upstream repositories as a PR.
153- 4 . (optional) Maintainers of these submodules will ** not** merge the PR. The PR can't be
154- merged because CI will be broken. You'll want to write a message on the PR referencing
155- your change, and how the PR should be merged once your change makes it into a nightly.
156- 5 . Wait for your PR to merge.
157- 6 . Wait for a nightly.
158- 7 . (optional) Help land your PR on the upstream repository now that your changes are in nightly.
159- 8 . (optional) Send a PR to rust-lang/rust updating the submodule.
160-
0 commit comments