diff --git a/src/doc/rustc-dev-guide/README.md b/src/doc/rustc-dev-guide/README.md index 2a686b5471c68..7ce7d4ddf3e7d 100644 --- a/src/doc/rustc-dev-guide/README.md +++ b/src/doc/rustc-dev-guide/README.md @@ -70,46 +70,21 @@ $ ENABLE_LINKCHECK=1 mdbook serve We use `mdbook-toc` to auto-generate TOCs for long sections. You can invoke the preprocessor by including the `` marker at the place where you want the TOC. -## How to fix toolstate failures - -> [!NOTE] -> Currently, we do not track the rustc-dev-guide toolstate due to -> [spurious failures](https://github.com/rust-lang/rust/pull/71731), -> but we leave these instructions for when we do it again in the future. - -1. You will get a ping from the toolstate commit. e.g. https://github.com/rust-lang-nursery/rust-toolstate/commit/8ffa0e4c30ac9ba8546b7046e5c4ccc2b96ebdd4 - -2. The commit contains a link to the PR that caused the breakage. e.g. https://github.com/rust-lang/rust/pull/64321 - -3. If you go to that PR's thread, there is a post from bors with a link to the CI status: https://github.com/rust-lang/rust/pull/64321#issuecomment-529763807 - -4. Follow the check-actions link to get to the Actions page for that build - -5. There will be approximately 1 billion different jobs for the build. They are for different configurations and platforms. The rustc-dev-guide build only runs on the Linux x86_64-gnu-tools job. So click on that job in the list, which is about 60% down in the list. - -6. Click the Run build step in the job to get the console log for the step. - -7. Click on the log and Ctrl-f to get a search box in the log - -8. Search for rustc-dev-guide. This gets you to the place where the links are checked. It is usually ~11K lines into the log. - -9. Look at the links in the log near that point in the log - -10. Fix those links in the rustc-dev-guide (by making a PR in the rustc-dev-guide repo) - -11. Make a PR on the rust-lang/rust repo to update the rustc-dev-guide git submodule in src/docs/rustc-dev-guide. -To make a PR, the following steps are useful. - -```bash -# Assuming you already cloned the rust-lang/rust repo and you're in the correct directory -git submodule update --remote src/doc/rustc-dev-guide -git add -u -git commit -m "Update rustc-dev-guide" -# Note that you can use -i, which is short for --incremental, in the following command -./x test --incremental src/doc/rustc-dev-guide # This is optional and should succeed anyway -# Open a PR in rust-lang/rust -``` - -12. Wait for PR to merge - -Voilà! +## Synchronizing josh subtree with rustc + +This repository is linked to `rust-lang/rust` as a [josh](https://josh-project.github.io/josh/intro.html) subtree. You can use the following commands to synchronize the subtree in both directions. + +### Pull changes from `rust-lang/rust` into this repository +1) Checkout a new branch that will be used to create a PR into `rust-lang/rustc-dev-guide` +2) Run the pull command + ``` + $ cargo run --manifest-path josh-sync/Cargo.toml rustc-pull + ``` +3) Push the branch to your fork and create a PR into `rustc-dev-guide` + +### Push changes from this repository into `rust-lang/rust` +1) Run the push command to create a branch named `` in a `rustc` fork under the `` account + ``` + $ cargo run --manifest-path josh-sync/Cargo.toml rustc-push + ``` +2) Create a PR from `` into `rust-lang/rust` diff --git a/src/doc/rustc-dev-guide/josh-sync/Cargo.lock b/src/doc/rustc-dev-guide/josh-sync/Cargo.lock new file mode 100644 index 0000000000000..844518628c437 --- /dev/null +++ b/src/doc/rustc-dev-guide/josh-sync/Cargo.lock @@ -0,0 +1,430 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +version = 4 + +[[package]] +name = "anstream" +version = "0.6.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8acc5369981196006228e28809f761875c0327210a891e941f4c683b3a99529b" +dependencies = [ + "anstyle", + "anstyle-parse", + "anstyle-query", + "anstyle-wincon", + "colorchoice", + "is_terminal_polyfill", + "utf8parse", +] + +[[package]] +name = "anstyle" +version = "1.0.10" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "55cc3b69f167a1ef2e161439aa98aed94e6028e5f9a59be9a6ffb47aef1651f9" + +[[package]] +name = "anstyle-parse" +version = "0.2.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3b2d16507662817a6a20a9ea92df6652ee4f94f914589377d69f3b21bc5798a9" +dependencies = [ + "utf8parse", +] + +[[package]] +name = "anstyle-query" +version = "1.1.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "79947af37f4177cfead1110013d678905c37501914fba0efea834c3fe9a8d60c" +dependencies = [ + "windows-sys 0.59.0", +] + +[[package]] +name = "anstyle-wincon" +version = "3.0.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2109dbce0e72be3ec00bed26e6a7479ca384ad226efdd66db8fa2e3a38c83125" +dependencies = [ + "anstyle", + "windows-sys 0.59.0", +] + +[[package]] +name = "anyhow" +version = "1.0.95" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "34ac096ce696dc2fcabef30516bb13c0a68a11d30131d3df6f04711467681b04" + +[[package]] +name = "bitflags" +version = "2.6.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b048fb63fd8b5923fc5aa7b340d8e156aec7ec02f0c78fa8a6ddc2613f6f71de" + +[[package]] +name = "cfg-if" +version = "1.0.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd" + +[[package]] +name = "clap" +version = "4.5.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3135e7ec2ef7b10c6ed8950f0f792ed96ee093fa088608f1c76e569722700c84" +dependencies = [ + "clap_builder", + "clap_derive", +] + +[[package]] +name = "clap_builder" +version = "4.5.23" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "30582fc632330df2bd26877bde0c1f4470d57c582bbc070376afcd04d8cb4838" +dependencies = [ + "anstream", + "anstyle", + "clap_lex", + "strsim", +] + +[[package]] +name = "clap_derive" +version = "4.5.18" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4ac6a0c7b1a9e9a5186361f67dfa1b88213572f427fb9ab038efb2bd8c582dab" +dependencies = [ + "heck", + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "clap_lex" +version = "0.7.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "f46ad14479a25103f283c0f10005961cf086d8dc42205bb44c46ac563475dca6" + +[[package]] +name = "colorchoice" +version = "1.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5b63caa9aa9397e2d9480a9b13673856c78d8ac123288526c37d7839f2a86990" + +[[package]] +name = "directories" +version = "5.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9a49173b84e034382284f27f1af4dcbbd231ffa358c0fe316541a7337f376a35" +dependencies = [ + "dirs-sys", +] + +[[package]] +name = "dirs-sys" +version = "0.4.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "520f05a5cbd335fae5a99ff7a6ab8627577660ee5cfd6a94a6a929b52ff0321c" +dependencies = [ + "libc", + "option-ext", + "redox_users", + "windows-sys 0.48.0", +] + +[[package]] +name = "getrandom" +version = "0.2.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c4567c8db10ae91089c99af84c68c38da3ec2f087c3f82960bcdbf3656b6f4d7" +dependencies = [ + "cfg-if", + "libc", + "wasi", +] + +[[package]] +name = "heck" +version = "0.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" + +[[package]] +name = "is_terminal_polyfill" +version = "1.70.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7943c866cc5cd64cbc25b2e01621d07fa8eb2a1a23160ee81ce38704e97b8ecf" + +[[package]] +name = "josh-sync" +version = "0.1.0" +dependencies = [ + "anyhow", + "clap", + "directories", + "xshell", +] + +[[package]] +name = "libc" +version = "0.2.169" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b5aba8db14291edd000dfcc4d620c7ebfb122c613afb886ca8803fa4e128a20a" + +[[package]] +name = "libredox" +version = "0.1.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c0ff37bd590ca25063e35af745c343cb7a0271906fb7b37e4813e8f79f00268d" +dependencies = [ + "bitflags", + "libc", +] + +[[package]] +name = "option-ext" +version = "0.2.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "04744f49eae99ab78e0d5c0b603ab218f515ea8cfe5a456d7629ad883a3b6e7d" + +[[package]] +name = "proc-macro2" +version = "1.0.92" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "37d3544b3f2748c54e147655edb5025752e2303145b5aefb3c3ea2c78b973bb0" +dependencies = [ + "unicode-ident", +] + +[[package]] +name = "quote" +version = "1.0.38" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0e4dccaaaf89514f546c693ddc140f729f958c247918a13380cccc6078391acc" +dependencies = [ + "proc-macro2", +] + +[[package]] +name = "redox_users" +version = "0.4.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ba009ff324d1fc1b900bd1fdb31564febe58a8ccc8a6fdbb93b543d33b13ca43" +dependencies = [ + "getrandom", + "libredox", + "thiserror", +] + +[[package]] +name = "strsim" +version = "0.11.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f" + +[[package]] +name = "syn" +version = "2.0.93" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9c786062daee0d6db1132800e623df74274a0a87322d8e183338e01b3d98d058" +dependencies = [ + "proc-macro2", + "quote", + "unicode-ident", +] + +[[package]] +name = "thiserror" +version = "1.0.69" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52" +dependencies = [ + "thiserror-impl", +] + +[[package]] +name = "thiserror-impl" +version = "1.0.69" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1" +dependencies = [ + "proc-macro2", + "quote", + "syn", +] + +[[package]] +name = "unicode-ident" +version = "1.0.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "adb9e6ca4f869e1180728b7950e35922a7fc6397f7b641499e8f3ef06e50dc83" + +[[package]] +name = "utf8parse" +version = "0.2.2" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821" + +[[package]] +name = "wasi" +version = "0.11.0+wasi-snapshot-preview1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9c8d87e72b64a3b4db28d11ce29237c246188f4f51057d65a7eab63b7987e423" + +[[package]] +name = "windows-sys" +version = "0.48.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "677d2418bec65e3338edb076e806bc1ec15693c5d0104683f2efe857f61056a9" +dependencies = [ + "windows-targets 0.48.5", +] + +[[package]] +name = "windows-sys" +version = "0.59.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b" +dependencies = [ + "windows-targets 0.52.6", +] + +[[package]] +name = "windows-targets" +version = "0.48.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9a2fa6e2155d7247be68c096456083145c183cbbbc2764150dda45a87197940c" +dependencies = [ + "windows_aarch64_gnullvm 0.48.5", + "windows_aarch64_msvc 0.48.5", + "windows_i686_gnu 0.48.5", + "windows_i686_msvc 0.48.5", + "windows_x86_64_gnu 0.48.5", + "windows_x86_64_gnullvm 0.48.5", + "windows_x86_64_msvc 0.48.5", +] + +[[package]] +name = "windows-targets" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973" +dependencies = [ + "windows_aarch64_gnullvm 0.52.6", + "windows_aarch64_msvc 0.52.6", + "windows_i686_gnu 0.52.6", + "windows_i686_gnullvm", + "windows_i686_msvc 0.52.6", + "windows_x86_64_gnu 0.52.6", + "windows_x86_64_gnullvm 0.52.6", + "windows_x86_64_msvc 0.52.6", +] + +[[package]] +name = "windows_aarch64_gnullvm" +version = "0.48.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2b38e32f0abccf9987a4e3079dfb67dcd799fb61361e53e2882c3cbaf0d905d8" + +[[package]] +name = "windows_aarch64_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3" + +[[package]] +name = "windows_aarch64_msvc" +version = "0.48.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "dc35310971f3b2dbbf3f0690a219f40e2d9afcf64f9ab7cc1be722937c26b4bc" + +[[package]] +name = "windows_aarch64_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469" + +[[package]] +name = "windows_i686_gnu" +version = "0.48.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "a75915e7def60c94dcef72200b9a8e58e5091744960da64ec734a6c6e9b3743e" + +[[package]] +name = "windows_i686_gnu" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b" + +[[package]] +name = "windows_i686_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66" + +[[package]] +name = "windows_i686_msvc" +version = "0.48.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f55c233f70c4b27f66c523580f78f1004e8b5a8b659e05a4eb49d4166cca406" + +[[package]] +name = "windows_i686_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66" + +[[package]] +name = "windows_x86_64_gnu" +version = "0.48.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "53d40abd2583d23e4718fddf1ebec84dbff8381c07cae67ff7768bbf19c6718e" + +[[package]] +name = "windows_x86_64_gnu" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78" + +[[package]] +name = "windows_x86_64_gnullvm" +version = "0.48.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0b7b52767868a23d5bab768e390dc5f5c55825b6d30b86c844ff2dc7414044cc" + +[[package]] +name = "windows_x86_64_gnullvm" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d" + +[[package]] +name = "windows_x86_64_msvc" +version = "0.48.5" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ed94fce61571a4006852b7389a063ab983c02eb1bb37b47f8272ce92d06d9538" + +[[package]] +name = "windows_x86_64_msvc" +version = "0.52.6" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec" + +[[package]] +name = "xshell" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9e7290c623014758632efe00737145b6867b66292c42167f2ec381eb566a373d" +dependencies = [ + "xshell-macros", +] + +[[package]] +name = "xshell-macros" +version = "0.2.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "32ac00cd3f8ec9c1d33fb3e7958a82df6989c42d747bd326c822b1d625283547" diff --git a/src/doc/rustc-dev-guide/josh-sync/Cargo.toml b/src/doc/rustc-dev-guide/josh-sync/Cargo.toml new file mode 100644 index 0000000000000..81d0d1ebd22d8 --- /dev/null +++ b/src/doc/rustc-dev-guide/josh-sync/Cargo.toml @@ -0,0 +1,10 @@ +[package] +name = "josh-sync" +version = "0.1.0" +edition = "2021" + +[dependencies] +anyhow = "1.0.95" +clap = { version = "4.5.21", features = ["derive"] } +directories = "5" +xshell = "0.2.6" diff --git a/src/doc/rustc-dev-guide/josh-sync/README.md b/src/doc/rustc-dev-guide/josh-sync/README.md new file mode 100644 index 0000000000000..a3dd876e8b87b --- /dev/null +++ b/src/doc/rustc-dev-guide/josh-sync/README.md @@ -0,0 +1,4 @@ +# Git josh sync +This utility serves for syncing the josh git subtree to and from the rust-lang/rust repository. + +See CLI help for usage. diff --git a/src/doc/rustc-dev-guide/josh-sync/src/main.rs b/src/doc/rustc-dev-guide/josh-sync/src/main.rs new file mode 100644 index 0000000000000..84613ad86890e --- /dev/null +++ b/src/doc/rustc-dev-guide/josh-sync/src/main.rs @@ -0,0 +1,32 @@ +use clap::Parser; +use crate::sync::GitSync; + +mod sync; + +#[derive(clap::Parser)] +enum Args { + /// Pull changes from the main `rustc` repository. + /// This creates new commits that should be then merged into `rustc-dev-guide`. + RustcPull, + /// Push changes from `rustc-dev-guide` to the given `branch` of a `rustc` fork under the given + /// GitHub `username`. + /// The pushed branch should then be merged into the `rustc` repository. + RustcPush { + branch: String, + github_username: String + } +} + +fn main() -> anyhow::Result<()> { + let args = Args::parse(); + let sync = GitSync::from_current_dir()?; + match args { + Args::RustcPull => { + sync.rustc_pull(None)?; + } + Args::RustcPush { github_username, branch } => { + sync.rustc_push(github_username, branch)?; + } + } + Ok(()) +} diff --git a/src/doc/rustc-dev-guide/josh-sync/src/sync.rs b/src/doc/rustc-dev-guide/josh-sync/src/sync.rs new file mode 100644 index 0000000000000..da21a4c9a27cb --- /dev/null +++ b/src/doc/rustc-dev-guide/josh-sync/src/sync.rs @@ -0,0 +1,234 @@ +use std::ops::Not; +use std::path::PathBuf; +use std::{env, net, process}; +use std::io::Write; +use std::time::Duration; +use anyhow::{anyhow, bail, Context}; +use xshell::{cmd, Shell}; + +/// Used for rustc syncs. +const JOSH_FILTER: &str = ":/src/doc/rustc-dev-guide"; +const JOSH_PORT: u16 = 42042; +const UPSTREAM_REPO: &str = "rust-lang/rust"; + +pub struct GitSync { + dir: PathBuf, +} + +/// This code was adapted from the miri repository +/// (https://github.com/rust-lang/miri/blob/6a68a79f38064c3bc30617cca4bdbfb2c336b140/miri-script/src/commands.rs#L236). +impl GitSync { + pub fn from_current_dir() -> anyhow::Result { + Ok(Self { + dir: std::env::current_dir()? + }) + } + + pub fn rustc_pull(&self, commit: Option) -> anyhow::Result<()> { + let sh = Shell::new()?; + sh.change_dir(&self.dir); + let commit = commit.map(Ok).unwrap_or_else(|| { + let rust_repo_head = + cmd!(sh, "git ls-remote https://github.com/{UPSTREAM_REPO}/ HEAD").read()?; + rust_repo_head + .split_whitespace() + .next() + .map(|front| front.trim().to_owned()) + .ok_or_else(|| anyhow!("Could not obtain Rust repo HEAD from remote.")) + })?; + // Make sure the repo is clean. + if cmd!(sh, "git status --untracked-files=no --porcelain").read()?.is_empty().not() { + bail!("working directory must be clean before performing rustc pull"); + } + // Make sure josh is running. + let josh = Self::start_josh()?; + let josh_url = + format!("http://localhost:{JOSH_PORT}/{UPSTREAM_REPO}.git@{commit}{JOSH_FILTER}.git"); + + // Update rust-version file. As a separate commit, since making it part of + // the merge has confused the heck out of josh in the past. + // We pass `--no-verify` to avoid running git hooks. + // We do this before the merge so that if there are merge conflicts, we have + // the right rust-version file while resolving them. + sh.write_file("rust-version", format!("{commit}\n"))?; + const PREPARING_COMMIT_MESSAGE: &str = "Preparing for merge from rustc"; + cmd!(sh, "git commit rust-version --no-verify -m {PREPARING_COMMIT_MESSAGE}") + .run() + .context("FAILED to commit rust-version file, something went wrong")?; + + // Fetch given rustc commit. + cmd!(sh, "git fetch {josh_url}") + .run() + .inspect_err(|_| { + // Try to un-do the previous `git commit`, to leave the repo in the state we found it. + cmd!(sh, "git reset --hard HEAD^") + .run() + .expect("FAILED to clean up again after failed `git fetch`, sorry for that"); + }) + .context("FAILED to fetch new commits, something went wrong (committing the rust-version file has been undone)")?; + + // This should not add any new root commits. So count those before and after merging. + let num_roots = || -> anyhow::Result { + Ok(cmd!(sh, "git rev-list HEAD --max-parents=0 --count") + .read() + .context("failed to determine the number of root commits")? + .parse::()?) + }; + let num_roots_before = num_roots()?; + + // Merge the fetched commit. + const MERGE_COMMIT_MESSAGE: &str = "Merge from rustc"; + cmd!(sh, "git merge FETCH_HEAD --no-verify --no-ff -m {MERGE_COMMIT_MESSAGE}") + .run() + .context("FAILED to merge new commits, something went wrong")?; + + // Check that the number of roots did not increase. + if num_roots()? != num_roots_before { + bail!("Josh created a new root commit. This is probably not the history you want."); + } + + drop(josh); + Ok(()) + } + + pub fn rustc_push(&self, github_user: String, branch: String) -> anyhow::Result<()> { + let sh = Shell::new()?; + sh.change_dir(&self.dir); + let base = sh.read_file("rust-version")?.trim().to_owned(); + // Make sure the repo is clean. + if cmd!(sh, "git status --untracked-files=no --porcelain").read()?.is_empty().not() { + bail!("working directory must be clean before running `rustc-push`"); + } + // Make sure josh is running. + let josh = Self::start_josh()?; + let josh_url = + format!("http://localhost:{JOSH_PORT}/{github_user}/rust.git{JOSH_FILTER}.git"); + + // Find a repo we can do our preparation in. + if let Ok(rustc_git) = env::var("RUSTC_GIT") { + // If rustc_git is `Some`, we'll use an existing fork for the branch updates. + sh.change_dir(rustc_git); + } else { + // Otherwise, do this in the local repo. + println!( + "This will pull a copy of the rust-lang/rust history into this checkout, growing it by about 1GB." + ); + print!( + "To avoid that, abort now and set the `RUSTC_GIT` environment variable to an existing rustc checkout. Proceed? [y/N] " + ); + std::io::stdout().flush()?; + let mut answer = String::new(); + std::io::stdin().read_line(&mut answer)?; + if answer.trim().to_lowercase() != "y" { + std::process::exit(1); + } + }; + // Prepare the branch. Pushing works much better if we use as base exactly + // the commit that we pulled from last time, so we use the `rust-version` + // file to find out which commit that would be. + println!("Preparing {github_user}/rust (base: {base})..."); + if cmd!(sh, "git fetch https://github.com/{github_user}/rust {branch}") + .ignore_stderr() + .read() + .is_ok() + { + println!( + "The branch '{branch}' seems to already exist in 'https://github.com/{github_user}/rust'. Please delete it and try again." + ); + std::process::exit(1); + } + cmd!(sh, "git fetch https://github.com/{UPSTREAM_REPO} {base}").run()?; + cmd!(sh, "git push https://github.com/{github_user}/rust {base}:refs/heads/{branch}") + .ignore_stdout() + .ignore_stderr() // silence the "create GitHub PR" message + .run()?; + println!(); + + // Do the actual push. + sh.change_dir(&self.dir); + println!("Pushing changes..."); + cmd!(sh, "git push {josh_url} HEAD:{branch}").run()?; + println!(); + + // Do a round-trip check to make sure the push worked as expected. + cmd!(sh, "git fetch {josh_url} {branch}").ignore_stderr().read()?; + let head = cmd!(sh, "git rev-parse HEAD").read()?; + let fetch_head = cmd!(sh, "git rev-parse FETCH_HEAD").read()?; + if head != fetch_head { + bail!( + "Josh created a non-roundtrip push! Do NOT merge this into rustc!\n\ + Expected {head}, got {fetch_head}." + ); + } + println!( + "Confirmed that the push round-trips back to rustc-dev-guide properly. Please create a rustc PR:" + ); + println!( + // Open PR with `subtree update` title to silence the `no-merges` triagebot check + " https://github.com/{UPSTREAM_REPO}/compare/{github_user}:{branch}?quick_pull=1&title=Rustc+dev+guide+subtree+update&body=r?+@ghost" + ); + + drop(josh); + Ok(()) + } + + fn start_josh() -> anyhow::Result { + // Determine cache directory. + let local_dir = { + let user_dirs = + directories::ProjectDirs::from("org", "rust-lang", "rustc-dev-guide-josh").unwrap(); + user_dirs.cache_dir().to_owned() + }; + + // Start josh, silencing its output. + let mut cmd = process::Command::new("josh-proxy"); + cmd.arg("--local").arg(local_dir); + cmd.arg("--remote").arg("https://github.com"); + cmd.arg("--port").arg(JOSH_PORT.to_string()); + cmd.arg("--no-background"); + cmd.stdout(process::Stdio::null()); + cmd.stderr(process::Stdio::null()); + let josh = cmd.spawn().context("failed to start josh-proxy, make sure it is installed")?; + + // Create a wrapper that stops it on drop. + struct Josh(process::Child); + impl Drop for Josh { + fn drop(&mut self) { + #[cfg(unix)] + { + // Try to gracefully shut it down. + process::Command::new("kill") + .args(["-s", "INT", &self.0.id().to_string()]) + .output() + .expect("failed to SIGINT josh-proxy"); + // Sadly there is no "wait with timeout"... so we just give it some time to finish. + std::thread::sleep(Duration::from_millis(100)); + // Now hopefully it is gone. + if self.0.try_wait().expect("failed to wait for josh-proxy").is_some() { + return; + } + } + // If that didn't work (or we're not on Unix), kill it hard. + eprintln!( + "I have to kill josh-proxy the hard way, let's hope this does not break anything." + ); + self.0.kill().expect("failed to SIGKILL josh-proxy"); + } + } + + // Wait until the port is open. We try every 10ms until 1s passed. + for _ in 0..100 { + // This will generally fail immediately when the port is still closed. + let josh_ready = net::TcpStream::connect_timeout( + &net::SocketAddr::from(([127, 0, 0, 1], JOSH_PORT)), + Duration::from_millis(1), + ); + if josh_ready.is_ok() { + return Ok(Josh(josh)); + } + // Not ready yet. + std::thread::sleep(Duration::from_millis(10)); + } + bail!("Even after waiting for 1s, josh-proxy is still not available.") + } +} diff --git a/src/doc/rustc-dev-guide/rust-version b/src/doc/rustc-dev-guide/rust-version new file mode 100644 index 0000000000000..876c32dcf434d --- /dev/null +++ b/src/doc/rustc-dev-guide/rust-version @@ -0,0 +1 @@ +dcfa38fe234de9304169afc6638e81d0dd222c06 diff --git a/src/doc/rustc-dev-guide/src/SUMMARY.md b/src/doc/rustc-dev-guide/src/SUMMARY.md index 2fbbb187d6b3f..a8fddbc7562d5 100644 --- a/src/doc/rustc-dev-guide/src/SUMMARY.md +++ b/src/doc/rustc-dev-guide/src/SUMMARY.md @@ -134,14 +134,13 @@ - [Prologue](./part-4-intro.md) - [Generic parameter definitions](./generic_parameters_summary.md) - - [Implementation nuances of early/late bound parameters](./early-late-bound-params/early-late-bound-implementation-nuances.md) - - [Interactions with turbofishing](./early-late-bound-params/turbofishing-and-early-late-bound.md) + - [`EarlyBinder` and instantiating parameters](./ty_module/early_binder.md) +- [Binders and Higher ranked regions](./ty_module/binders.md) + - [Instantiating binders](./ty_module/instantiating_binders.md) +- [Early vs Late bound parameters](./early_late_parameters.md) - [The `ty` module: representing types](./ty.md) - [ADTs and Generic Arguments](./ty_module/generic_arguments.md) - [Parameter types/consts/regions](./ty_module/param_ty_const_regions.md) - - [`EarlyBinder` and instantiating parameters](./ty_module/early_binder.md) - - [`Binder` and Higher ranked regions](./ty_module/binders.md) - - [Instantiating binders](./ty_module/instantiating_binders.md) - [`TypeFolder` and `TypeFoldable`](./ty-fold.md) - [Parameter Environments](./param_env/param_env_summary.md) - [What is it?](./param_env/param_env_what_is_it.md) diff --git a/src/doc/rustc-dev-guide/src/early-late-bound-params/early-late-bound-implementation-nuances.md b/src/doc/rustc-dev-guide/src/early-late-bound-params/early-late-bound-implementation-nuances.md deleted file mode 100644 index 01569e8dc6a01..0000000000000 --- a/src/doc/rustc-dev-guide/src/early-late-bound-params/early-late-bound-implementation-nuances.md +++ /dev/null @@ -1,197 +0,0 @@ -# Early and Late Bound Parameter Implementation Nuances - -> Note: this chapter makes reference to information discussed later on in the [representing types][ch_representing_types] chapter. Specifically, it uses concise notation to represent some more complex kinds of types that have not yet been discussed, such as inference variables. - -[ch_representing_types]: ../ty.md - -Understanding this page likely requires a rudimentary understanding of higher ranked -trait bounds/`for<'a>`and also what types such as `dyn for<'a> Trait<'a>` and - `for<'a> fn(&'a u32)` mean. Reading [the nomincon chapter](https://doc.rust-lang.org/nomicon/hrtb.html) -on HRTB may be useful for understanding this syntax. The meaning of `for<'a> fn(&'a u32)` -is incredibly similar to the meaning of `T: for<'a> Trait<'a>`. - -## What does it mean for parameters to be early or late bound - -All function definitions conceptually have a ZST (this is represented by `TyKind::FnDef` in rustc). -The only generics on this ZST are the early bound parameters of the function definition. e.g. -```rust -fn foo<'a>(_: &'a u32) {} - -fn main() { - let b = foo; - // ^ `b` has type `FnDef(foo, [])` (no args because `'a` is late bound) - assert!(std::mem::size_of_val(&b) == 0); -} -``` - -In order to call `b` the late bound parameters do need to be provided, these are inferred at the -call site instead of when we refer to `foo`. -```rust -fn main() { - let b = foo; - let a: &'static u32 = &10; - foo(a); - // the lifetime argument for `'a` on `foo` is inferred at the callsite - // the generic parameter `'a` on `foo` is inferred to `'static` here -} -``` - -Because late bound parameters are not part of the `FnDef`'s args this allows us to prove trait -bounds such as `F: for<'a> Fn(&'a u32)` where `F` is `foo`'s `FnDef`. e.g. -```rust -fn foo_early<'a, T: Trait<'a>>(_: &'a u32, _: T) {} -fn foo_late<'a, T>(_: &'a u32, _: T) {} - -fn accepts_hr_func Fn(&'a u32, u32)>(_: F) {} - -fn main() { - // doesn't work, the instantiated bound is `for<'a> FnDef<'?0>: Fn(&'a u32, u32)` - // `foo_early` only implements `for<'a> FnDef<'a>: Fn(&'a u32, u32)`- the lifetime - // of the borrow in the function argument must be the same as the lifetime - // on the `FnDef`. - accepts_hr_func(foo_early); - - // works, the instantiated bound is `for<'a> FnDef: Fn(&'a u32, u32)` - accepts_hr_func(foo_late); -} - -// the builtin `Fn` impls for `foo_early` and `foo_late` look something like: -// `foo_early` -impl<'a, T: Trait<'a>> Fn(&'a u32, T) for FooEarlyFnDef<'a, T> { ... } -// `foo_late` -impl<'a, T> Fn(&'a u32, T) for FooLateFnDef { ... } - -``` - -Early bound parameters are present on the `FnDef`. Late bound generic parameters are not present -on the `FnDef` but are instead constrained by the builtin `Fn*` impl. - -The same distinction applies to closures. Instead of `FnDef` we are talking about the anonymous -closure type. Closures are [currently unsound](https://github.com/rust-lang/rust/issues/84366) in -ways that are closely related to the distinction between early/late bound -parameters (more on this later) - -The early/late boundness of generic parameters is only relevant for the desugaring of -functions/closures into types with builtin `Fn*` impls. It does not make sense to talk about -in other contexts. - -The `generics_of` query in rustc only contains early bound parameters. In this way it acts more -like `generics_of(my_func)` is the generics for the FnDef than the generics provided to the function -body although it's not clear to the author of this section if this was the actual justification for -making `generics_of` behave this way. - -## What parameters are currently late bound - -Below are the current requirements for determining if a generic parameter is late bound. It is worth -keeping in mind that these are not necessarily set in stone and it is almost certainly possible to -be more flexible. - -### Must be a lifetime parameter - -Rust can't support types such as `for dyn Trait` or `for fn(T)`, this is a -fundamental limitation of the language as we are required to monomorphize type/const -parameters and cannot do so behind dynamic dispatch. (technically we could probably -support `for dyn MarkerTrait` as there is nothing to monomorphize) - -Not being able to support `for dyn Trait` resulted in making all type and const -parameters early bound. Only lifetime parameters can be late bound. - -### Must not appear in the where clauses - -In order for a generic parameter to be late bound it must not appear in any where clauses. -This is currently an incredibly simplistic check that causes lifetimes to be early bound even -if the where clause they appear in are always true, or implied by well formedness of function -arguments. e.g. -```rust -fn foo1<'a: 'a>(_: &'a u32) {} -// ^^ early bound parameter because it's in a `'a: 'a` clause -// even though the bound obviously holds all the time -fn foo2<'a, T: Trait<'a>(a: T, b: &'a u32) {} -// ^^ early bound parameter because it's used in the `T: Trait<'a>` clause -fn foo3<'a, T: 'a>(_: &'a T) {} -// ^^ early bound parameter because it's used in the `T: 'a` clause -// even though that bound is implied by wellformedness of `&'a T` -fn foo4<'a, 'b: 'a>(_: Inv<&'a ()>, _: Inv<&'b ()>) {} -// ^^ ^^ ^^^ note: -// ^^ ^^ `Inv` stands for `Invariant` and is used to -// ^^ ^^ make the type parameter invariant. This -// ^^ ^^ is necessary for demonstration purposes as -// ^^ ^^ `for<'a, 'b> fn(&'a (), &'b ())` and -// ^^ ^^ `for<'a> fn(&'a u32, &'a u32)` are subtypes- -// ^^ ^^ of each other which makes the bound trivially -// ^^ ^^ satisfiable when making the fnptr. `Inv` -// ^^ ^^ disables this subtyping. -// ^^ ^^ -// ^^^^^^ both early bound parameters because they are present in the -// `'b: 'a` clause -``` - -The reason for this requirement is that we cannot represent the `T: Trait<'a>` or `'a: 'b` clauses -on a function pointer. `for<'a, 'b> fn(Inv<&'a ()>, Inv<&'b ()>)` is not a valid function pointer to -represent`foo4` as it would allow calling the function without `'b: 'a` holding. - -### Must be constrained by where clauses or function argument types - -The builtin impls of the `Fn*` traits for closures and `FnDef`s cannot not have any unconstrained -parameters. For example the following impl is illegal: -```rust -impl<'a> Trait for u32 { type Assoc = &'a u32; } -``` -We must not end up with a similar impl for the `Fn*` traits e.g. -```rust -impl<'a> Fn<()> for FnDef { type Assoc = &'a u32 } -``` - -Violating this rule can trivially lead to unsoundness as seen in [#84366](https://github.com/rust-lang/rust/issues/84366). -Additionally if we ever support late bound type params then an impl like: -```rust -impl Fn<()> for FnDef { type Assoc = T; } -``` -would break the compiler in various ways. - -In order to ensure that everything functions correctly, we do not allow generic parameters to -be late bound if it would result in a builtin impl that does not constrain all of the generic -parameters on the builtin impl. Making a generic parameter be early bound trivially makes it be -constrained by the builtin impl as it ends up on the self type. - -Because of the requirement that late bound parameters must not appear in where clauses, checking -this is simpler than the rules for checking impl headers constrain all the parameters on the impl. -We only have to ensure that all late bound parameters appear at least once in the function argument -types outside of an alias (e.g. an associated type). - -The requirement that they not indirectly be in the args of an alias for it to count is the -same as why the follow code is forbidden: -```rust -impl OtherTrait for ::Assoc { type Assoc = T } -``` -There is no guarantee that `::Assoc` will normalize to different types for every -instantiation of `T`. If we were to allow this impl we could get overlapping impls and the -same is true of the builtin `Fn*` impls. - -## Making more generic parameters late bound - -It is generally considered desirable for more parameters to be late bound as it makes -the builtin `Fn*` impls more flexible. Right now many of the requirements for making -a parameter late bound are overly restrictive as they are tied to what we can currently -(or can ever) do with fn ptrs. - -It would be theoretically possible to support late bound params in `where`-clauses in the -language by introducing implication types which would allow us to express types such as: -`for<'a, 'b: 'a> fn(Inv<&'a u32>, Inv<&'b u32>)` which would ensure `'b: 'a` is upheld when -calling the function pointer. - -It would also be theoretically possible to support it by making the coercion to a fn ptr -instantiate the parameter with an infer var while still allowing the FnDef to not have the -generic parameter present as trait impls are perfectly capable of representing the where clauses -on the function on the impl itself. This would also allow us to support late bound type/const -vars allowing bounds like `F: for Fn(T)` to hold. - -It is almost somewhat unclear if we can change the `Fn` traits to be structured differently -so that we never have to make a parameter early bound just to make the builtin impl have all -generics be constrained. Of all the possible causes of a generic parameter being early bound -this seems the most difficult to remove. - -Whether these would be good ideas to implement is a separate question- they are only brought -up to illustrate that the current rules are not necessarily set in stone and a result of -"its the only way of doing this". - diff --git a/src/doc/rustc-dev-guide/src/early-late-bound-params/turbofishing-and-early-late-bound.md b/src/doc/rustc-dev-guide/src/early-late-bound-params/turbofishing-and-early-late-bound.md deleted file mode 100644 index 6fc30c6767d24..0000000000000 --- a/src/doc/rustc-dev-guide/src/early-late-bound-params/turbofishing-and-early-late-bound.md +++ /dev/null @@ -1,125 +0,0 @@ -# Turbofishing's interactions with early/late bound parameters - -> Note: this chapter makes reference to information discussed later on in the [representing types][ch_representing_types] chapter. Specifically, it uses concise notation to represent some more complex kinds of types that have not yet been discussed, such as inference variables. - -[ch_representing_types]: ../ty.md - -The early/late bound parameter distinction on functions introduces some complications -when providing generic arguments to functions. This document discusses what those are -and how they might interact with future changes to make more things late bound. - -## Can't turbofish generic arguments on functions sometimes - -When a function has any late bound lifetime parameters (be they explicitly defined or -implicitly introduced via lifetime elision) we disallow specifying any lifetime arguments -on the function. Sometimes this is a hard error other times it is a future compat lint -([`late_bound_lifetime_arguments`](https://github.com/rust-lang/rust/issues/42868)). - -```rust -fn early<'a: 'a>(a: &'a ()) -> &'a () { a } -fn late<'a>(a: &'a ()) -> &'a () { a } - -fn mixed<'a, 'b: 'b>(a: &'a (), b: &'b ()) -> &'a () { a } - -struct Foo; -impl Foo { - fn late<'a>(self, a: &'a ()) -> &'a () { a } -} - -fn main() { - // fine - let f = early::<'static>; - - // some variation of hard errors and future compat lints - Foo.late::<'static>(&()); - let f = late::<'static>; - let f = mixed::<'static, 'static>; - let f = mixed::<'static>; - late::<'static>(&()); -} -``` - -The justification for this is that late bound parameters are not present on the -`FnDef` so the arguments to late bound parameters can't be present in the generic arguments -for the type. i.e. the `late` function in the above code snippet would not have -any generic parameters on the `FnDef` zst: -```rust -// example desugaring of the `late` function and its zst + builtin Fn impl -struct LateFnDef; -impl<'a> Fn<(&'a ())> for LateFnDef { - type Output = &'a (); - ... -} -``` - -The cause for some situations giving future compat lints and others giving hard errors -is a little arbitrary but explainable: -- It's always a hard error for method calls -- It's only a hard error on paths to free functions if there is no unambiguous way to -create the generic arguments for the fndef from the lifetime arguments. (i.e. the amount of -lifetimes provided must be exactly equal to the amount of early bound lifetimes or -else it's a hard error) - -## Back compat issues from turning early bound to late bound - -Because of the previously mentioned restriction on turbofishing generic arguments, it -is a breaking change to upgrade a lifetime from early bound to late bound as it can cause -existing turbofishies to become hard errors/future compat lints. - -Many t-types members have expressed interest in wanting more parameters to be late bound. -We cannot do so if making something late bound is going to break code that many would -expect to work (judging by the future compat lint issue many people do expect to be able -to turbofish late bound parameters). - -## Interactions with late bound type/const parameters - -If we were to make some type/const parameters late bound we would definitely not want -to disallow turbofishing them as it presumably(?) would break a Tonne of code. - -While lifetimes do differ from type/consts in some ways I(BoxyUwU) do not believe there -is any justification for why it would make sense to allow turbofishing late bound -type/const parameters but not late bound lifetimes. - -## Removing the hard error/fcw - -From reasons above it seems reasonable that we may want to remove the hard error and fcw -(removing the errors/fcw is definitely a blocker for making more things late bound). - -example behaviour: -```rust -fn late<'a>(a: &'a ()) -> &'a () { a } - -fn accepts_fn(_: impl for<'a> Fn(&'a ()) -> &'a ()) {} -fn accepts_fn_2(_: impl Fn(&'static ()) -> &'static ()) {} - -fn main() { - let f = late::<'static>; - - accepts_fn(f); //~ error: `f` doesn't implement `for<'a> Fn(&'a ()) -> &'a ()` - accepts_fn_2(f) // works - - accepts_fn(late) // works -} -```` - -one potential complication is that we would want a way to specify a generic argument -to a function without having to specify arguments for all previous parameters. i.e. -ideally you could write the following code somehow. -```rust -fn late<'a, 'b>(_: &'a (), _: &'b ()) {} - -fn accepts_fn(_: impl for<'a> Fn(&'a (), &'static ())) {} - -fn main() { - // a naive implementation would have an inference variable as - // the argument to the `'a` parameter no longer allowing the `FnDef` - // to satisfy the bound `for<'a> Fn(&'a ())` - let f = late::<'_, 'static>; - accepts_fn(f); -} -``` -Maybe we can just special case HIR ty lowering for `_`/`'_` arguments for late bound -parameters somehow and have it not mean the same thing as `_` for early bound parameters. -Regardless I think we would need a solution that would allow writing the above code even -if it was done by some new syntax such as having to write `late::` -(naturally `k#no_argument` would only make sense as an argument to late bound parameters). diff --git a/src/doc/rustc-dev-guide/src/early_late_parameters.md b/src/doc/rustc-dev-guide/src/early_late_parameters.md new file mode 100644 index 0000000000000..6d13655294d3e --- /dev/null +++ b/src/doc/rustc-dev-guide/src/early_late_parameters.md @@ -0,0 +1,424 @@ + +# Early vs Late bound parameters + + + +> **NOTE**: This chapter largely talks about early/late bound as being solely relevant when discussing function item types/function definitions. This is potentially not completely true, async blocks and closures should likely be discussed somewhat in this chapter. + +## What does it mean to be "early" bound or "late" bound + +Every function definition has a corresponding ZST that implements the `Fn*` traits known as a [function item type][function_item_type]. This part of the chapter will talk a little bit about the "desugaring" of function item types as it is useful context for explaining the difference between early bound and late bound generic parameters. + +Let's start with a very trivial example involving no generic parameters: + +```rust +fn foo(a: String) -> u8 { + # 1 + /* snip */ +} +``` + +If we explicitly wrote out the definitions for the function item type corresponding to `foo` and its associated `Fn` impl it would look something like this: +```rust,ignore +struct FooFnItem; + +impl Fn<(String,)> for FooFnItem { + type Output = u8; + /* fn call(&self, ...) -> ... { ... } */ +} +``` + +The builtin impls for the `FnMut`/`FnOnce` traits as well as the impls for `Copy` and `Clone` were omitted for brevity reasons (although these traits *are* implemented for function item types). + +A slightly more complicated example would involve introducing generic parameters to the function: +```rust +fn foo(a: T) -> T { + # a + /* snip */ +} +``` +Writing out the definitions would look something like this: +```rust,ignore +struct FooFnItem(PhantomData T>); + +impl Fn<(T,)> for FooFnItem { + type Output = T; + /* fn call(&self, ...) -> ... { ... } */ +} +``` + +Note that the function item type `FooFnItem` is generic over some type parameter `T` as defined on the function `foo`. However, not all generic parameters defined on functions are also defined on the function item type as demonstrated here: +```rust +fn foo<'a, T: Sized>(a: &'a T) -> &'a T { + # a + /* snip */ +} +``` +With its "desugared" form looking like so: +```rust,ignore +struct FooFnItem(PhantomData fn(&'a T) -> &'a T>); + +impl<'a, T: Sized> Fn<(&'a T,)> for FooFnItem { + type Output = &'a T; + /* fn call(&self, ...) -> ... { ... } */ +} +``` + +The lifetime parameter `'a` from the function `foo` is not present on the function item type `FooFnItem` and is instead introduced on the builtin impl solely for use in representing the argument types. + +Generic parameters not all being defined on the function item type means that there are two steps where generic arguments are provided when calling a function. +1. Naming the function (e.g. `let a = foo;`) the arguments for `FooFnItem` are provided. +2. Calling the function (e.g. `a(&10);`) any parameters defined on the builtin impl are provided. + +This two-step system is where the early vs late naming scheme comes from, early bound parameters are provided in the *earliest* step (naming the function), whereas late bound parameters are provided in the *latest* step (calling the function). + +Looking at the desugaring from the previous example we can tell that `T` is an early bound type parameter and `'a` is a late bound lifetime parameter as `T` is present on the function item type but `'a` is not. See this example of calling `foo` annotated with where each generic parameter has an argument provided: +```rust +fn foo<'a, T: Sized>(a: &'a T) -> &'a T { + # a + /* snip */ +} + +// Here we provide a type argument `String` to the +// type parameter `T` on the function item type +let my_func = foo::; + +// Here (implicitly) a lifetime argument is provided +// to the lifetime parameter `'a` on the builtin impl. +my_func(&String::new()); +``` + +[function_item_type]: https://doc.rust-lang.org/reference/types/function-item.html + +## Differences between early and late bound parameters + +### Higher ranked function pointers and trait bounds + +A generic parameter being late bound allows for more flexible usage of the function item. For example if we have some function `foo` with an early bound lifetime parameter and some function `bar` with a late bound lifetime parameter `'a` we would have the following builtin `Fn` impls: +```rust,ignore +impl<'a> Fn<(&'a String,)> for FooFnItem<'a> { /* ... */ } +impl<'a> Fn<(&'a String,)> for BarFnItem { /* ... */ } +``` + +The `bar` function has a strictly more flexible signature as the function item type can be called with a borrow with *any* lifetime, whereas the `foo` function item type would only be callable with a borrow with the same lifetime on the function item type. We can show this by simply trying to call `foo`'s function item type multiple times with different lifetimes: + +```rust +// The `'a: 'a` bound forces this lifetime to be early bound. +fn foo<'a: 'a>(b: &'a String) -> &'a String { b } +fn bar<'a>(b: &'a String) -> &'a String { b } + +// Early bound generic parameters are instantiated here when naming +// the function `foo`. As `'a` is early bound an argument is provided. +let f = foo::<'_>; + +// Both function arguments are required to have the same lifetime as +// the lifetime parameter being early bound means that `f` is only +// callable for one specific lifetime. +// +// As we call this with borrows of different lifetimes, the borrow checker +// will error here. +f(&String::new()); +f(&String::new()); +``` + +In this example we call `foo`'s function item type twice, each time with a borrow of a temporary. These two borrows could not possible have lifetimes that overlap as the temporaries are only alive during the function call, not after. The lifetime parameter on `foo` being early bound requires all callers of `f` to provide a borrow with the same lifetime, as this is not possible the borrow checker errors. + +If the lifetime parameter on `foo` was late bound this would be able to compile as each caller could provide a different lifetime argument for its borrow. See the following example which demonstrates this using the `bar` function defined above: + +```rust +#fn foo<'a: 'a>(b: &'a String) -> &'a String { b } +#fn bar<'a>(b: &'a String) -> &'a String { b } + +// Early bound parameters are instantiated here, however as `'a` is +// late bound it is not provided here. +let b = bar; + +// Late bound parameters are instantiated separately at each call site +// allowing different lifetimes to be used by each caller. +b(&String::new()); +b(&String::new()); +``` + +This is reflected in the ability to coerce function item types to higher ranked function pointers and prove higher ranked `Fn` trait bounds. We can demonstrate this with the following example: +```rust +// The `'a: 'a` bound forces this lifetime to be early bound. +fn foo<'a: 'a>(b: &'a String) -> &'a String { b } +fn bar<'a>(b: &'a String) -> &'a String { b } + +fn accepts_hr_fn(_: impl for<'a> Fn(&'a String) -> &'a String) {} + +fn higher_ranked_trait_bound() { + let bar_fn_item = bar; + accepts_hr_fn(bar_fn_item); + + let foo_fn_item = foo::<'_>; + // errors + accepts_hr_fn(foo_fn_item); +} + +fn higher_ranked_fn_ptr() { + let bar_fn_item = bar; + let fn_ptr: for<'a> fn(&'a String) -> &'a String = bar_fn_item; + + let foo_fn_item = foo::<'_>; + // errors + let fn_ptr: for<'a> fn(&'a String) -> &'a String = foo_fn_item; +} +``` + +In both of these cases the borrow checker errors as it does not consider `foo_fn_item` to be callable with a borrow of any lifetime. This is due to the fact that the lifetime parameter on `foo` is early bound, causing `foo_fn_item` to have a type of `FooFnItem<'_>` which (as demonstrated by the desugared `Fn` impl) is only callable with a borrow of the same lifetime `'_`. + +### Turbofishing in the presence of late bound parameters + +As mentioned previously, the distinction between early and late bound parameters means that there are two places where generic parameters are instantiated: +- When naming a function (early) +- When calling a function (late) + +There currently is no syntax for explicitly specifying generic arguments for late bound parameters as part of the call step, only specifying generic arguments when naming a function. The syntax `foo::<'static>();`, despite being part of a function call, behaves as `(foo::<'static>)();` and instantiates the early bound generic parameters on the function item type. + +See the following example: +```rust +fn foo<'a>(b: &'a u32) -> &'a u32 { b } + +let f /* : FooFnItem */ = foo::<'static>; +``` + +The above example errors as the lifetime parameter `'a` is late bound and so cannot be instantiated as part of the "naming a function" step. If we make the lifetime parameter early bound we will see this code start to compile: +```rust +fn foo<'a: 'a>(b: &'a u32) -> &'a u32 { b } + +let f /* : FooFnItem<'static> */ = foo::<'static>; +``` + +What the current implementation of the compiler aims to do is error when specifying lifetime arguments to a function that has both early *and* late bound lifetime parameters. In practice, due to excessive breakage, some cases are actually only future compatibility warnings ([#42868](https://github.com/rust-lang/rust/issues/42868)): +- When the amount of lifetime arguments is the same as the number of early bound lifetime parameters a FCW is emitted instead of an error +- An error is always downgraded to a FCW when using method call syntax + +To demonstrate this we can write out the different kinds of functions and give them both a late and early bound lifetime: +```rust,ignore +fn free_function<'a: 'a, 'b>(_: &'a (), _: &'b ()) {} + +struct Foo; + +trait Trait: Sized { + fn trait_method<'a: 'a, 'b>(self, _: &'a (), _: &'b ()); + fn trait_function<'a: 'a, 'b>(_: &'a (), _: &'b ()); +} + +impl Trait for Foo { + fn trait_method<'a: 'a, 'b>(self, _: &'a (), _: &'b ()) {} + fn trait_function<'a: 'a, 'b>(_: &'a (), _: &'b ()) {} +} + +impl Foo { + fn inherent_method<'a: 'a, 'b>(self, _: &'a (), _: &'b ()) {} + fn inherent_function<'a: 'a, 'b>(_: &'a (), _: &'b ()) {} +} +``` + +Then, for the first case, we can call each function with a single lifetime argument (corresponding to the one early bound lifetime parameter) and note that it only results in a FCW rather than a hard error. +```rust +#![deny(late_bound_lifetime_arguments)] + +#fn free_function<'a: 'a, 'b>(_: &'a (), _: &'b ()) {} +# +#struct Foo; +# +#trait Trait: Sized { +# fn trait_method<'a: 'a, 'b>(self, _: &'a (), _: &'b ()); +# fn trait_function<'a: 'a, 'b>(_: &'a (), _: &'b ()); +#} +# +#impl Trait for Foo { +# fn trait_method<'a: 'a, 'b>(self, _: &'a (), _: &'b ()) {} +# fn trait_function<'a: 'a, 'b>(_: &'a (), _: &'b ()) {} +#} +# +#impl Foo { +# fn inherent_method<'a: 'a, 'b>(self, _: &'a (), _: &'b ()) {} +# fn inherent_function<'a: 'a, 'b>(_: &'a (), _: &'b ()) {} +#} +# +// Specifying as many arguments as there are early +// bound parameters is always a future compat warning +Foo.trait_method::<'static>(&(), &()); +Foo::trait_method::<'static>(Foo, &(), &()); +Foo::trait_function::<'static>(&(), &()); +Foo.inherent_method::<'static>(&(), &()); +Foo::inherent_function::<'static>(&(), &()); +free_function::<'static>(&(), &()); +``` + +For the second case we call each function with more lifetime arguments than there are lifetime parameters (be it early or late bound) and note that method calls result in a FCW as opposed to the free/associated functions which result in a hard error: +```rust +#fn free_function<'a: 'a, 'b>(_: &'a (), _: &'b ()) {} +# +#struct Foo; +# +#trait Trait: Sized { +# fn trait_method<'a: 'a, 'b>(self, _: &'a (), _: &'b ()); +# fn trait_function<'a: 'a, 'b>(_: &'a (), _: &'b ()); +#} +# +#impl Trait for Foo { +# fn trait_method<'a: 'a, 'b>(self, _: &'a (), _: &'b ()) {} +# fn trait_function<'a: 'a, 'b>(_: &'a (), _: &'b ()) {} +#} +# +#impl Foo { +# fn inherent_method<'a: 'a, 'b>(self, _: &'a (), _: &'b ()) {} +# fn inherent_function<'a: 'a, 'b>(_: &'a (), _: &'b ()) {} +#} +# +// Specifying more arguments than there are early +// bound parameters is a future compat warning when +// using method call syntax. +Foo.trait_method::<'static, 'static, 'static>(&(), &()); +Foo.inherent_method::<'static, 'static, 'static>(&(), &()); +// However, it is a hard error when not using method call syntax. +Foo::trait_method::<'static, 'static, 'static>(Foo, &(), &()); +Foo::trait_function::<'static, 'static, 'static>(&(), &()); +Foo::inherent_function::<'static, 'static, 'static>(&(), &()); +free_function::<'static, 'static, 'static>(&(), &()); +``` + +Even when specifying enough lifetime arguments for both the late and early bound lifetime parameter, these arguments are not actually used to annotate the lifetime provided to late bound parameters. We can demonstrate this by turbofishing `'static` to a function while providing a non-static borrow: +```rust +struct Foo; + +impl Foo { + fn inherent_method<'a: 'a, 'b>(self, _: &'a (), _: &'b String ) {} +} + +Foo.inherent_method::<'static, 'static>(&(), &String::new()); +``` + +This compiles even though the `&String::new()` function argument does not have a `'static` lifetime, this is because "extra" lifetime arguments are discarded rather than taken into account for late bound parameters when actually calling the function. + +### Liveness of types with late bound parameters + +When checking type outlives bounds involving function item types we take into account early bound parameters. For example: + +```rust +fn foo(_: T) {} + +fn requires_static(_: T) {} + +fn bar() { + let f /* : FooFnItem */ = foo::; + requires_static(f); +} +``` + +As the type parameter `T` is early bound, the desugaring of the function item type for `foo` would look something like `struct FooFnItem`. Then in order for `FooFnItem: 'static` to hold we must also require `T: 'static` to hold as otherwise we would wind up with soundness bugs. + +Unfortunately, due to bugs in the compiler, we do not take into account early bound *lifetimes*, which is the cause of the open soundness bug [#84366](https://github.com/rust-lang/rust/issues/84366). This means that it's impossible to demonstrate a "difference" between early/late bound parameters for liveness/type outlives bounds as the only kind of generic parameters that are able to be late bound are lifetimes which are handled incorrectly. + +Regardless, in theory the code example below *should* demonstrate such a difference once [#84366](https://github.com/rust-lang/rust/issues/84366) is fixed: +```rust +fn early_bound<'a: 'a>(_: &'a String) {} +fn late_bound<'a>(_: &'a String) {} + +fn requires_static(_: T) {} + +fn bar<'b>() { + let e = early_bound::<'b>; + // this *should* error but does not + requires_static(e); + + let l = late_bound; + // this correctly does not error + requires_static(l); +} +``` + +## Requirements for a parameter to be late bound + +### Must be a lifetime parameter + +Type and Const parameters are not able to be late bound as we do not have a way to support types such as `dyn for Fn(Box)` or `for fn(Box)`. Calling such types requires being able to monomorphize the underlying function which is not possible with indirection through dynamic dispatch. + +### Must not be used in a where clause + +Currently when a generic parameter is used in a where clause it must be early bound. For example: +```rust +# trait Trait<'a> {} +fn foo<'a, T: Trait<'a>>(_: &'a String, _: T) {} +``` + +In this example the lifetime parameter `'a` is considered to be early bound as it appears in the where clause `T: Trait<'a>`. This is true even for "trivial" where clauses such as `'a: 'a` or those implied by wellformedness of function arguments, for example: +```rust +fn foo<'a: 'a>(_: &'a String) {} +fn bar<'a, T: 'a>(_: &'a T) {} +``` + +In both of these functions the lifetime parameter `'a` would be considered to be early bound even though the where clauses they are used in arguably do not actually impose any constraints on the caller. + +The reason for this restriction is a combination of two things: +- We cannot prove bounds on late bound parameters until they have been instantiated +- Function pointers and trait objects do not have a way to represent yet to be proven where clauses from the underlying function + +Take the following example: +```rust +trait Trait<'a> {} +fn foo<'a, T: Trait<'a>>(_: &'a T) {} + +let f = foo::; +let f = f as for<'a> fn(&'a String); +f(&String::new()); +``` + +At *some point* during type checking an error should be emitted for this code as `String` does not implement `Trait` for any lifetime. + +If the lifetime `'a` were late bound then this becomes difficult to check. When naming `foo` we do not know what lifetime should be used as part of the `T: Trait<'a>` trait bound as it has not yet been instantiated. When coercing the function item type to a function pointer we have no way of tracking the `String: Trait<'a>` trait bound that must be proven when calling the function. + +If the lifetime `'a` is early bound (which it is in the current implementation in rustc), then the trait bound can be checked when naming the function `foo`. Requiring parameters used in where clauses to be early bound gives a natural place to check where clauses defined on the function. + +Finally, we do not require lifetimes to be early bound if they are used in *implied bounds*, for example: +```rust +fn foo<'a, T>(_: &'a T) {} + +let f = foo; +f(&String::new()); +f(&String::new()); +``` + +This code compiles, demonstrating that the lifetime parameter is late bound, even though `'a` is used in the type `&'a T` which implicitly requires `T: 'a` to hold. Implied bounds can be treated specially as any types introducing implied bounds are in the signature of the function pointer type, which means that when calling the function we know to prove `T: 'a`. + +### Must be constrained by argument types + +It is important that builtin impls on function item types do not wind up with unconstrained generic parameters as this can lead to unsoundness. This is the same kind of restriction as applies to user written impls, for example the following code results in an error: +```rust +trait Trait { + type Assoc; +} + +impl<'a> Trait for u8 { + type Assoc = &'a String; +} +``` + +The analogous example for builtin impls on function items would be the following: +```rust,ignore +fn foo<'a>() -> &'a String { /* ... */ } +``` +If the lifetime parameter `'a` were to be late bound we would wind up with a builtin impl with an unconstrained lifetime, we can manually write out the desugaring for the function item type and its impls with `'a` being late bound to demonstrate this: +```rust,ignore +// NOTE: this is just for demonstration, in practice `'a` is early bound +struct FooFnItem; + +impl<'a> Fn<()> for FooFnItem { + type Output = &'a String; + /* fn call(...) -> ... { ... } */ +} +``` + +In order to avoid such a situation we consider `'a` to be early bound which causes the lifetime on the impl to be constrained by the self type: +```rust,ignore +struct FooFnItem<'a>(PhantomData &'a String>); + +impl<'a> Fn<()> for FooFnItem<'a> { + type Output = &'a String; + /* fn call(...) -> ... { ... } */ +} +``` \ No newline at end of file diff --git a/src/doc/rustc-dev-guide/src/external-repos.md b/src/doc/rustc-dev-guide/src/external-repos.md index 533f7eb5e7344..a7ab3d773acb5 100644 --- a/src/doc/rustc-dev-guide/src/external-repos.md +++ b/src/doc/rustc-dev-guide/src/external-repos.md @@ -3,24 +3,24 @@ The `rust-lang/rust` git repository depends on several other repos in the `rust-lang` organization. There are three main ways we use dependencies: 1. As a Cargo dependency through crates.io (e.g. `rustc-rayon`) -2. As a git subtree (e.g. `clippy`) +2. As a git (e.g. `clippy`) or a [josh] (e.g. `miri`) subtree 3. As a git submodule (e.g. `cargo`) -As a general rule, use crates.io for libraries that could be useful for others in the ecosystem; use -subtrees for tools that depend on compiler internals and need to be updated if there are breaking -changes; and use submodules for tools that are independent of the compiler. +As a general rule: +- Use crates.io for libraries that could be useful for others in the ecosystem +- Use subtrees for tools that depend on compiler internals and need to be updated if there are breaking +changes +- Use submodules for tools that are independent of the compiler -## External Dependencies (subtree) +## External Dependencies (subtrees) -As a developer to this repository, you don't have to treat the following external projects -differently from other crates that are directly in this repo: +The following external projects are managed using some form of a `subtree`: -* [Clippy](https://github.com/rust-lang/rust-clippy) -* [Miri] +* [clippy](https://github.com/rust-lang/rust-clippy) +* [miri](https://github.com/rust-lang/miri) * [rustfmt](https://github.com/rust-lang/rustfmt) * [rust-analyzer](https://github.com/rust-lang/rust-analyzer) - -[Miri]: https://github.com/rust-lang/miri +* [rustc_codegen_cranelift](https://github.com/rust-lang/rustc_codegen_cranelift) In contrast to `submodule` dependencies (see below for those), the `subtree` dependencies are just regular files and directories which can @@ -29,6 +29,20 @@ to these tools should be filed against the tools directly in their respective upstream repositories. The exception is that when rustc changes are required to implement a new tool feature or test, that should happen in one collective rustc PR. +`subtree` dependencies are currently managed by two distinct approaches: + +* Using `git subtree` + * `clippy` ([sync guide](https://doc.rust-lang.org/nightly/clippy/development/infrastructure/sync.html#performing-the-sync-from-rust-langrust-to-clippy)) + * `rustfmt` + * `rustc_codegen_cranelift` ([sync script](https://github.com/rust-lang/rustc_codegen_cranelift/blob/113af154d459e41b3dc2c5d7d878e3d3a8f33c69/scripts/rustup.sh#L7)) +* Using the [josh] tool + * `miri` ([sync guide](https://github.com/rust-lang/miri/blob/master/CONTRIBUTING.md#advanced-topic-syncing-with-the-rustc-repo)) + * `rust-analyzer` ([sync script](https://github.com/rust-lang/rust-analyzer/blob/2e13684be123eca7181aa48e043e185d8044a84a/xtask/src/release.rs#L147)) + +The [josh] tool is an alternative to git subtrees, which manages git history in a different way and scales better to larger repositories. Specific tooling is required to work with josh, you can check out the `miri` or `rust-analyzer` scripts linked above for inspiration. If you want to migrate a subtree from `git subtree` to josh, you can check out [this guide](https://hackmd.io/7pOuxnkdQDaL1Y1FQr65xg). + +Below you can find a guide on how to perform push and pull synchronization with the main rustc repo using `git subtree`, although these instructions might differ repo from repo. + ### Synchronizing a subtree Periodically the changes made to subtree based dependencies need to be synchronized between this @@ -84,7 +98,6 @@ Now you're done, the `src/tools/clippy` directory behaves as if Clippy were part of the rustc monorepo, so no one but you (or others that synchronize subtrees) actually needs to use `git subtree`. - ## External Dependencies (submodules) Building Rust will also use external git repositories tracked using [git @@ -111,3 +124,4 @@ the week leading up to the beta cut. [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 +[josh]: https://josh-project.github.io/josh/intro.html diff --git a/src/doc/rustc-dev-guide/src/generic_parameters_summary.md b/src/doc/rustc-dev-guide/src/generic_parameters_summary.md index 3403c9f2991a1..da38ba0455c2c 100644 --- a/src/doc/rustc-dev-guide/src/generic_parameters_summary.md +++ b/src/doc/rustc-dev-guide/src/generic_parameters_summary.md @@ -25,42 +25,4 @@ Interestingly, `ty::Generics` does not currently contain _every_ generic paramet [ch_representing_types]: ./ty.md [`ty::Generics`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.Generics.html [`GenericParamDef`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/generics/struct.GenericParamDef.html - -# Early vs Late bound parameters - - -```rust -fn foo<'a, T>(b: &'a T) -> &'a T { b } -// ^^ ^early bound -// ^^ -// ^^late bound -``` - -Generally when referring to an item with generic parameters you must specify a list of generic arguments corresponding to the item's generic parameters. In some cases it is permitted to elide these arguments but still, implicitly, a set of arguments are provided (e.g. `Vec::default()` desugars to `Vec::<_>::default()`). - -For functions this is not necessarily the case, for example if we take the function `foo` from the example above and write the following code: -```rust -fn main() { - let f = foo::<_>; - - let b = String::new(); - let c = String::new(); - - f(&b); - drop(b); - f(&c); -} -``` - -This code compiles perfectly fine even though there is no single lifetime that could possibly be specified in `foo::<_>` that would allow for both -the `&b` and `&c` borrows to be used as arguments (note: the `drop(b)` line forces the `&b` borrow to be shorter than the `&c` borrow). This works because the `'a` lifetime is _late bound_. - -A generic parameter being late bound means that when we write `foo::<_>` we do not actually provide an argument for that parameter, instead we wait until _calling_ the function to provide the generic argument. In the above example this means that we are doing something like `f::<'_>(&b);` and `f::<'_>(&c);` (although in practice we do not actually support turbofishing late bound parameters in this manner) - -It may be helpful to think of "early bound parameter" or "late bound parameter" as meaning "early provided parameter" and "late provided parameter", i.e. we provide the argument to the parameter either early (when naming the function) or late (when calling it). - -Late bound parameters on functions are tracked with a [`Binder`] when accessing the signature of the function, this can be done with the [`fn_sig`] query. For more information of binders see the [chapter on `Binder`s ][ch_binders]. - -[`Binder`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_type_ir/binder/struct.Binder.html -[`fn_sig`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.fn_sig -[ch_binders]: ./ty_module/binders.md \ No newline at end of file +[ch_binders]: ./ty_module/binders.md diff --git a/src/doc/rustc-dev-guide/src/method-lookup.md b/src/doc/rustc-dev-guide/src/method-lookup.md index 8b49e8d004b17..c8d529a32b532 100644 --- a/src/doc/rustc-dev-guide/src/method-lookup.md +++ b/src/doc/rustc-dev-guide/src/method-lookup.md @@ -67,6 +67,7 @@ imported to use an inherent method, they are associated with the type itself (note that inherent impls can only be defined in the same crate as the type itself). + **Extension candidates** are derived from imported traits. If I have the trait `ToString` imported, and I call `to_string()` as a method, diff --git a/src/doc/rustc-dev-guide/src/solve/normalization.md b/src/doc/rustc-dev-guide/src/solve/normalization.md index 8858258b54269..99dc20c46b5d4 100644 --- a/src/doc/rustc-dev-guide/src/solve/normalization.md +++ b/src/doc/rustc-dev-guide/src/solve/normalization.md @@ -1,5 +1,7 @@ # Normalization in the new solver +> FIXME: Normalization has been changed significantly since this chapter was written. + With the new solver we've made some fairly significant changes to normalization when compared to the existing implementation. @@ -52,12 +54,14 @@ before assigning the resulting rigid type to an inference variable. This is used This has to be used whenever we match on the value of some type, both inside and outside of the trait solver. + [structural_norm]: https://github.com/rust-lang/rust/blob/2627e9f3012a97d3136b3e11bf6bd0853c38a534/compiler/rustc_trait_selection/src/solve/alias_relate.rs#L140-L175 [structural-relate]: https://github.com/rust-lang/rust/blob/a0569fa8f91b5271e92d2f73fd252de7d3d05b9c/compiler/rustc_trait_selection/src/solve/alias_relate.rs#L88-L107 @@ -72,11 +76,13 @@ possible. However, this only works for aliases referencing bound variables if th not ambiguous as we're unable to replace the alias with a corresponding inference variable without leaking universes. + [generalize-no-alias]: https://github.com/rust-lang/rust/blob/a0569fa8f91b5271e92d2f73fd252de7d3d05b9c/compiler/rustc_infer/src/infer/relate/generalize.rs#L353-L358 diff --git a/src/doc/rustc-dev-guide/src/solve/opaque-types.md b/src/doc/rustc-dev-guide/src/solve/opaque-types.md index 87531705c2da4..672aab7708018 100644 --- a/src/doc/rustc-dev-guide/src/solve/opaque-types.md +++ b/src/doc/rustc-dev-guide/src/solve/opaque-types.md @@ -60,6 +60,7 @@ Finally, we check whether the item bounds of the opaque hold for the expected ty [eq-prev]: https://github.com/rust-lang/rust/blob/384d26fc7e3bdd7687cc17b2662b091f6017ec2a/compiler/rustc_trait_selection/src/solve/normalizes_to/opaque_types.rs#L51-L59 [insert-storage]: https://github.com/rust-lang/rust/blob/384d26fc7e3bdd7687cc17b2662b091f6017ec2a/compiler/rustc_trait_selection/src/solve/normalizes_to/opaque_types.rs#L68 [item-bounds-ck]: https://github.com/rust-lang/rust/blob/384d26fc7e3bdd7687cc17b2662b091f6017ec2a/compiler/rustc_trait_selection/src/solve/normalizes_to/opaque_types.rs#L69-L74 + [^1]: FIXME: this should ideally only result in a unique candidate given that we require the args to be placeholders and regions are always inference vars [^2]: FIXME: why do we check whether the expected type is rigid for this. @@ -101,6 +102,7 @@ The handling of member constraints does not change in the new solver. See the FIXME: We need to continue to support calling methods on still unconstrained opaque types in their defining scope. It's unclear how to best do this. + ```rust use std::future::Future; use futures::FutureExt; diff --git a/src/doc/rustc-dev-guide/src/tests/compiletest.md b/src/doc/rustc-dev-guide/src/tests/compiletest.md index 17106be46744c..459c082906eba 100644 --- a/src/doc/rustc-dev-guide/src/tests/compiletest.md +++ b/src/doc/rustc-dev-guide/src/tests/compiletest.md @@ -441,6 +441,46 @@ $ COMPILETEST_FORCE_STAGE0=1 x test --stage 0 tests/run-make/ Of course, some tests will not successfully *run* in this way. +#### Using rust-analyzer with `rmake.rs` + +Like other test programs, the `rmake.rs` scripts used by run-make tests do not +have rust-analyzer integration by default. + +To work around this when working on a particular test, temporarily create a +`Cargo.toml` file in the test's directory +(e.g. `tests/run-make/sysroot-crates-are-unstable/Cargo.toml`) +with these contents: + +
+Be careful not to add this `Cargo.toml` or its `Cargo.lock` to your actual PR! +
+ +```toml +# Convince cargo that this isn't part of an enclosing workspace. +[workspace] + +[package] +name = "rmake" +version = "0.1.0" +edition = "2021" + +[dependencies] +run_make_support = { path = "../../../src/tools/run-make-support" } + +[[bin]] +name = "rmake" +path = "rmake.rs" +``` + +Then add a corresponding entry to `"rust-analyzer.linkedProjects"` +(e.g. in `.vscode/settings.json`): + +```json +"rust-analyzer.linkedProjects": [ + "tests/run-make/sysroot-crates-are-unstable/Cargo.toml" +], +``` + #### Using Makefiles (legacy)
diff --git a/src/doc/rustc-dev-guide/src/tests/directives.md b/src/doc/rustc-dev-guide/src/tests/directives.md index b0527da7bf564..69f4c864186cf 100644 --- a/src/doc/rustc-dev-guide/src/tests/directives.md +++ b/src/doc/rustc-dev-guide/src/tests/directives.md @@ -2,7 +2,9 @@ -> **FIXME(jieyouxu)** completely revise this chapter. + Directives are special comments that tell compiletest how to build and interpret a test. They must appear before the Rust source in the test. They may also @@ -248,10 +250,11 @@ Consider writing the test as a proper incremental test instead. |-------------|--------------------------------------------------------------|------------------------------------------|---------------------------| | `doc-flags` | Flags passed to `rustdoc` when building the test or aux file | `rustdoc`, `js-doc-test`, `rustdoc-json` | Any valid `rustdoc` flags | -> **FIXME(rustdoc)**: what does `check-test-line-numbers-match` do? -> -> Asked in -> . + ### Pretty printing diff --git a/src/doc/rustc-dev-guide/src/traits/chalk.md b/src/doc/rustc-dev-guide/src/traits/chalk.md index 78deb367506c5..844f42b9879f8 100644 --- a/src/doc/rustc-dev-guide/src/traits/chalk.md +++ b/src/doc/rustc-dev-guide/src/traits/chalk.md @@ -10,7 +10,7 @@ stream and say hello! [Types team]: https://github.com/rust-lang/types-team [`#t-types`]: https://rust-lang.zulipchat.com/#narrow/stream/144729-t-types -The new-style trait solver is based on the work done in [chalk][chalk]. Chalk +The new-style trait solver is based on the work done in [chalk]. Chalk recasts Rust's trait system explicitly in terms of logic programming. It does this by "lowering" Rust code into a kind of logic program we can then execute queries against. @@ -30,7 +30,7 @@ You can read more about chalk itself in the ## Ongoing work The design of the new-style trait solving happens in two places: -**chalk**. The [chalk][chalk] repository is where we experiment with new ideas +**chalk**. The [chalk] repository is where we experiment with new ideas and designs for the trait system. **rustc**. Once we are happy with the logical rules, we proceed to diff --git a/src/doc/rustc-dev-guide/src/ty_module/early_binder.md b/src/doc/rustc-dev-guide/src/ty_module/early_binder.md index 69db189350fdd..e8ff3a5307801 100644 --- a/src/doc/rustc-dev-guide/src/ty_module/early_binder.md +++ b/src/doc/rustc-dev-guide/src/ty_module/early_binder.md @@ -47,10 +47,10 @@ fn bar(foo: Foo) { In the compiler the `instantiate` call for this is done in [`FieldDef::ty`] ([src][field_def_ty_src]), at some point during type checking `bar` we will wind up calling `FieldDef::ty(x, &[u32, f32])` in order to obtain the type of `foo.x`. -**Note on indices:** It is possible for the indices in `Param` to not match with what the `EarlyBinder` binds. For -example, the index could be out of bounds or it could be the index of a lifetime when we were expecting a type. -These sorts of errors would be caught earlier in the compiler when translating from a `rustc_hir::Ty` to a `ty::Ty`. -If they occur later, that is a compiler bug. +**Note on indices:** It is a bug if the index of a `Param` does not match what the `EarlyBinder` binds. For +example, if the index is out of bounds or the index index of a lifetime corresponds to a type parameter. +These sorts of errors are caught earlier in the compiler during name resolution where we disallow references +to generics parameters introduced by items that should not be nameable by the inner item. [`FieldDef::ty`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.FieldDef.html#method.ty [field_def_ty_src]: https://github.com/rust-lang/rust/blob/44d679b9021f03a79133021b94e6d23e9b55b3ab/compiler/rustc_middle/src/ty/mod.rs#L1421-L1426