diff --git a/src/building/bootstrapping.md b/src/building/bootstrapping.md index 939c47f1b..7f2ede4f8 100644 --- a/src/building/bootstrapping.md +++ b/src/building/bootstrapping.md @@ -365,7 +365,7 @@ This flag has the following effects: Code which does not use `-Z force-unstable-if-unmarked` should include the `#![feature(rustc_private)]` crate attribute to access these force-unstable -crates. This is needed for things that link `rustc`, such as `miri`, `rls`, or +crates. This is needed for things that link `rustc`, such as `miri` or `clippy`. You can find more discussion about sysroots in: diff --git a/src/building/new-target.md b/src/building/new-target.md index 77833fad1..f999a9472 100644 --- a/src/building/new-target.md +++ b/src/building/new-target.md @@ -102,15 +102,11 @@ unreleased version of `libc`, you can add it to the top-level ```diff diff --git a/Cargo.toml b/Cargo.toml -index be15e50e2bc..4fb1248ba99 100644 +index 1e83f05e0ca..4d0172071c1 100644 --- a/Cargo.toml +++ b/Cargo.toml -@@ -66,10 +66,11 @@ cargo = { path = "src/tools/cargo" } +@@ -113,6 +113,8 @@ cargo-util = { path = "src/tools/cargo/crates/cargo-util" } [patch.crates-io] - # Similar to Cargo above we want the RLS to use a vendored version of `rustfmt` - # that we're shipping as well (to ensure that the rustfmt in RLS and the - # `rustfmt` executable are the same exact version). - rustfmt-nightly = { path = "src/tools/rustfmt" } +libc = { git = "https://github.com/rust-lang/libc", rev = "0bf7ce340699dcbacabdf5f16a242d2219a49ee0" } # See comments in `src/tools/rustc-workspace-hack/README.md` for what's going on diff --git a/src/contributing.md b/src/contributing.md index e59bb0a77..224c5eee5 100644 --- a/src/contributing.md +++ b/src/contributing.md @@ -249,37 +249,37 @@ subtrees) actually needs to use `git subtree`. ### External Dependencies (submodules) -Currently building Rust will also build the following external projects: +Building Rust will also use external git repositories tracked using [git +submodules]. The complete list may be found in the [`.gitmodules`] file. Some +of these projects are required (like `stdarch` for the standard library) and +some of them are optional (like [Miri]). -* [miri](https://github.com/rust-lang/miri) -* [rls](https://github.com/rust-lang/rls/) +Usage of submodules is discussed more in the [Using Git +chapter](git.md#git-submodules). -We allow breakage of these tools in the nightly channel. Maintainers of these -projects will be notified of the breakages and should fix them as soon as -possible. - -After the external is fixed, one could add the changes with - -```sh -git add path/to/submodule -``` - -outside the submodule. - -In order to prepare your tool-fixing PR, you can run the build locally by doing -`./x.py build src/tools/TOOL`. If you will be editing the sources -there, you may wish to set `submodules = false` in the `config.toml` -to prevent `x.py` from resetting to the original branch. +Some of the submodules are allowed to be in a "broken" state where they either +don't build or their tests don't pass. These include [Miri] and the +documentation books like [The Rust Reference]. Maintainers of these projects +will be notified when the project is in a broken state, and they should fix +them as soon as possible. The current status is tracked on the [toolstate +website]. More information may be found on the Forge [Toolstate chapter]. Breakage is not allowed in the beta and stable channels, and must be addressed -before the PR is merged. +before the PR is merged. They are also not allowed to be broken on master in +the week leading up to the beta cut. + +[git submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules +[`.gitmodules`]: https://github.com/rust-lang/rust/blob/master/.gitmodules +[Miri]: https://github.com/rust-lang/miri +[The Rust Reference]: https://github.com/rust-lang/reference/ +[toolstate website]: https://rust-lang-nursery.github.io/rust-toolstate/ +[Toolstate chapter]: https://forge.rust-lang.org/infra/toolstate.html #### Breaking Tools Built With The Compiler Rust's build system builds a number of tools that make use of the internals of the compiler and that are hosted in a separate repository, and included in Rust -via git submodules. This includes [RLS](https://github.com/rust-lang/rls) and -[Miri](https://github.com/rust-lang/Miri). If these tools break because of your +via git submodules (such as [Miri]). If these tools break because of your changes, you may run into a sort of "chicken and egg" problem. These tools rely on the latest compiler to be built so you can't update them (in their own repositories) to reflect your changes to the compiler until those changes are @@ -299,7 +299,7 @@ done and the tools are working again, you go back in the compiler and update the tools so they can be distributed again. This should avoid a bunch of synchronization dances and is also much easier on contributors as -there's no need to block on rls/miri/other tools changes going upstream. +there's no need to block on tools changes going upstream. Here are those same steps in detail: @@ -309,8 +309,8 @@ Here are those same steps in detail: from resetting to the original branch after you make your changes. If you need to [update any submodules to their latest versions](#updating-submodules), see the section of this file about that for more information. -2. (optional) Run `./x.py test src/tools/rls` (substituting the submodule - that broke for `rls`). Fix any errors in the submodule (and possibly others). +2. (optional) Run `./x.py test src/tools/miri` (substituting the submodule + that broke for `miri`). Fix any errors in the submodule (and possibly others). 3. (optional) Make commits for your changes and send them to upstream repositories as a PR. 4. (optional) Maintainers of these submodules will **not** merge the PR. The PR can't be merged because CI will be broken. You'll want to write a message on the PR referencing @@ -322,69 +322,21 @@ Here are those same steps in detail: #### Updating submodules -These instructions are specific to updating `rls`, however they may apply +These instructions are specific to updating `miri`, however they may apply to the other submodules as well. Please help by improving these instructions if you find any discrepancies or special cases that need to be addressed. -To update the `rls` submodule, start by running the appropriate +To update the `miri` submodule, start by running the appropriate [`git submodule` command](https://git-scm.com/book/en/v2/Git-Tools-Submodules). For example, to update to the latest commit on the remote master branch, you may want to run: ``` -git submodule update --remote src/tools/rls -``` -If you run `./x.py build` now, and you are lucky, it may just work. If you see -an error message about patches that did not resolve to any crates, you will need -to complete a few more steps which are outlined with their rationale below. - -*(This error may change in the future to include more information.)* -``` -error: failed to resolve patches for `https://github.com/rust-lang/rls` - -Caused by: - patch for `rls` in `https://github.com/rust-lang/rls` did not resolve to any crates -failed to run: ~/rust/build/x86_64-unknown-linux-gnu/stage0/bin/cargo build --manifest-path ~/rust/src/bootstrap/Cargo.toml -``` - -The [`[patch]`][patchsec] section of `Cargo.toml` can be very useful for -testing. In addition to that, you should read the [Overriding -dependencies][overriding] section of the documentation. - -[patchsec]: http://doc.crates.io/manifest.html#the-patch-section -[overriding]: http://doc.crates.io/specifying-dependencies.html#overriding-dependencies - -Specifically, the following [section in Overriding dependencies][testingbugfix] -reveals what the problem is: - -[testingbugfix]: http://doc.crates.io/specifying-dependencies.html#testing-a-bugfix - -> Next up we need to ensure that our lock file is updated to use this new -> version of uuid so our project uses the locally checked out copy instead of -> one from crates.io. The way `[patch]` works is that it'll load the dependency -> at ../path/to/uuid and then whenever crates.io is queried for versions of -> uuid it'll also return the local version. -> -> This means that the version number of the local checkout is significant and -> will affect whether the patch is used. Our manifest declared uuid = "1.0" -> which means we'll only resolve to >= 1.0.0, < 2.0.0, and Cargo's greedy -> resolution algorithm also means that we'll resolve to the maximum version -> within that range. Typically this doesn't matter as the version of the git -> repository will already be greater or match the maximum version published on -> crates.io, but it's important to keep this in mind! - -This says that when we updated the submodule, the version number in our -`src/tools/rls/Cargo.toml` changed. The new version is different from -the version in `Cargo.lock`, so the build can no longer continue. - -To resolve this, we need to update `Cargo.lock`. Luckily, cargo provides a -command to do this easily. - -``` -$ cargo update -p rls +git submodule update --remote src/tools/miri ``` +If you run `./x.py build` now, and you are lucky, it may just work. -This should change the version listed in `Cargo.lock` to the new version you updated -the submodule to. Running `./x.py build` should work now. +To add these changes to a commit, use `git add src/tools/miri` and commit the +change. You can the push and open a PR. ## Writing Documentation diff --git a/src/diagnostics.md b/src/diagnostics.md index 0f0bfd895..d4006c04f 100644 --- a/src/diagnostics.md +++ b/src/diagnostics.md @@ -388,10 +388,8 @@ In addition to telling the user exactly _why_ their code is wrong, it's oftentimes furthermore possible to tell them how to fix it. To this end, `DiagnosticBuilder` offers a structured suggestions API, which formats code suggestions pleasingly in the terminal, or (when the `--error-format json` flag -is passed) as JSON for consumption by tools, most notably the [Rust Language -Server][rls] and [`rustfix`][rustfix]. +is passed) as JSON for consumption by tools like [`rustfix`][rustfix]. -[rls]: https://github.com/rust-lang/rls [rustfix]: https://github.com/rust-lang/rustfix Not all suggestions should be applied mechanically, they have a degree of @@ -757,7 +755,7 @@ then dumped into the `Session::buffered_lints` used by the rest of the compiler. The compiler accepts an `--error-format json` flag to output diagnostics as JSON objects (for the benefit of tools such as `cargo -fix` or the RLS). It looks like this: +fix`). It looks like this: ```console $ rustc json_error_demo.rs --error-format json @@ -771,7 +769,7 @@ object, but the series of lines taken together is, unfortunately, not valid JSON, thwarting tools and tricks (such as [piping to `python3 -m json.tool`](https://docs.python.org/3/library/json.html#module-json.tool)) that require such. (One speculates that this was intentional for LSP -performance purposes, so that each line/object can be sent to RLS as +performance purposes, so that each line/object can be sent as it is flushed?) Also note the "rendered" field, which contains the "human" output as a diff --git a/src/git.md b/src/git.md index 5899753ba..edc5d5f63 100644 --- a/src/git.md +++ b/src/git.md @@ -149,7 +149,7 @@ Changes not staged for commit: (use "git add ..." to update what will be committed) (use "git restore ..." to discard changes in working directory) modified: src/tools/cargo (new commits) - modified: src/tools/rls (new commits) + modified: src/tools/miri (new commits) no changes added to commit (use "git add" and/or "git commit -a") ``` @@ -391,7 +391,7 @@ you might want to get used to the main concepts of Git before reading this secti The `rust-lang/rust` repository uses [Git submodules] as a way to use other Rust projects from within the `rust` repo. Examples include Rust's fork of -`llvm-project` and many devtools such as `cargo` and `rls`. +`llvm-project` and many devtools such as `cargo` and `miri`. Those projects are developed and maintained in an separate Git (and GitHub) repository, and they have their own Git history/commits, issue tracker and PRs. @@ -434,6 +434,5 @@ exist and that they correspond to some sort of embedded subrepository dependency that Git can nicely and fairly conveniently handle for us. [Git submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules -[`rust-toolstate`]: https://rust-lang-nursery.github.io/rust-toolstate/ [`rust-lang/miri`]: https://github.com/rust-lang/miri [miri-update]: https://github.com/rust-lang/rust/pull/77500/files diff --git a/src/name-resolution.md b/src/name-resolution.md index c4f44909b..1dbc95ead 100644 --- a/src/name-resolution.md +++ b/src/name-resolution.md @@ -174,7 +174,7 @@ Still, it probably provides useful first guidepost to what happens in there. following stages of compilation? * Who calls it and how it is actually used. * Is it a pass and then the result is only used, or can it be computed - incrementally (e.g. for RLS)? + incrementally? * The overall strategy description is a bit vague. * Where does the name `Rib` come from? * Does this thing have its own tests, or is it tested only as part of some e2e diff --git a/src/overview.md b/src/overview.md index c7da92542..3725e1f8e 100644 --- a/src/overview.md +++ b/src/overview.md @@ -190,7 +190,7 @@ satisfy/optimize for. For example, the input programs says they do, and should continue to do so despite the tremendous amount of change constantly going on. - Integration: a number of other tools need to use the compiler in - various ways (e.g. cargo, clippy, miri, RLS) that must be supported. + various ways (e.g. cargo, clippy, miri) that must be supported. - Compiler stability: the compiler should not crash or fail ungracefully on the stable channel. - Rust stability: the compiler must respect Rust's stability guarantees by not diff --git a/src/rustc-driver.md b/src/rustc-driver.md index 7250c852c..cef50111d 100644 --- a/src/rustc-driver.md +++ b/src/rustc-driver.md @@ -7,7 +7,7 @@ using the interface defined in the [`rustc_interface`] crate. The `rustc_interface` crate provides external users with an (unstable) API for running code at particular times during the compilation process, allowing third parties to effectively use `rustc`'s internals as a library for -analyzing a crate or emulating the compiler in-process (e.g. the RLS or rustdoc). +analyzing a crate or emulating the compiler in-process (e.g. rustdoc). For those using `rustc` as a library, the [`rustc_interface::run_compiler()`][i_rc] function is the main entrypoint to the compiler. It takes a configuration for the compiler diff --git a/src/tests/intro.md b/src/tests/intro.md index 8b65e4df5..66e0a9eef 100644 --- a/src/tests/intro.md +++ b/src/tests/intro.md @@ -115,7 +115,7 @@ will unpack, build, and run all tests. ### Tool tests Packages that are included with Rust have all of their tests run as well. -This includes things such as cargo, clippy, rustfmt, rls, miri, bootstrap +This includes things such as cargo, clippy, rustfmt, miri, bootstrap (testing the Rust build system itself), etc. Most of the tools are located in the [`src/tools`] directory.