@@ -21,7 +21,6 @@ differently from other crates that are directly in this repo:
21
21
* [ rust-analyzer] ( https://github.com/rust-lang/rust-analyzer )
22
22
23
23
[ Miri ] : https://github.com/rust-lang/miri
24
- [ Cargo ] : https://github.com/rust-lang/cargo
25
24
26
25
In contrast to ` submodule ` dependencies
27
26
(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
93
92
of these projects are required (like ` stdarch ` for the standard library) and
94
93
some of them are optional (like ` src/doc/book ` ).
95
94
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 ) .
98
96
99
97
Some of the submodules are allowed to be in a "broken" state where they
100
98
either 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.
112
110
[ The Rust Reference ] : https://github.com/rust-lang/reference/
113
111
[ toolstate website ] : https://rust-lang-nursery.github.io/rust-toolstate/
114
112
[ 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