diff --git a/src/doc/rustc-dev-guide/.github/workflows/ci.yml b/src/doc/rustc-dev-guide/.github/workflows/ci.yml index c9c23bf9935a9..76e1d0a8f7cf3 100644 --- a/src/doc/rustc-dev-guide/.github/workflows/ci.yml +++ b/src/doc/rustc-dev-guide/.github/workflows/ci.yml @@ -22,7 +22,7 @@ jobs: BASE_SHA: ${{ github.event.pull_request.base.sha }} GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@v5 with: # linkcheck needs the base commit. fetch-depth: 0 @@ -83,8 +83,18 @@ jobs: git commit -m "Deploy ${GITHUB_SHA} to gh-pages" git push --quiet -f "https://x-token:${{ secrets.GITHUB_TOKEN }}@github.com/${GITHUB_REPOSITORY}" HEAD:gh-pages + - name: Cache sembr build + uses: actions/cache@v4 + with: + path: | + ~/.cargo/registry/index/ + ~/.cargo/registry/cache/ + ~/.cargo/git/db/ + ci/sembr/target/ + key: sembr-${{ hashFiles('ci/sembr/Cargo.lock') }} + - name: Check if files comply with semantic line breaks continue-on-error: true run: | # using split_inclusive that uses regex feature that uses an unstable feature - RUSTC_BOOTSTRAP=1 cargo run --manifest-path ci/sembr/Cargo.toml src + RUSTC_BOOTSTRAP=1 cargo run --release --manifest-path ci/sembr/Cargo.toml src diff --git a/src/doc/rustc-dev-guide/.github/workflows/date-check.yml b/src/doc/rustc-dev-guide/.github/workflows/date-check.yml index 356aeb4e29739..3bac68d23b748 100644 --- a/src/doc/rustc-dev-guide/.github/workflows/date-check.yml +++ b/src/doc/rustc-dev-guide/.github/workflows/date-check.yml @@ -15,7 +15,7 @@ jobs: steps: - name: Checkout repo - uses: actions/checkout@v4 + uses: actions/checkout@v5 - name: Ensure Rust is up-to-date run: | diff --git a/src/doc/rustc-dev-guide/ci/sembr/Cargo.lock b/src/doc/rustc-dev-guide/ci/sembr/Cargo.lock index 1e690cc7f1e7c..077fa42d2e5b6 100644 --- a/src/doc/rustc-dev-guide/ci/sembr/Cargo.lock +++ b/src/doc/rustc-dev-guide/ci/sembr/Cargo.lock @@ -4,9 +4,9 @@ version = 4 [[package]] name = "aho-corasick" -version = "1.1.3" +version = "1.1.4" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "8e60d3430d3a69478ad0993f19238d2df97c507009a52b3c10addcd7f6bcb916" +checksum = "ddd31a130427c27518df266943a5308ed92d4b226cc639f5a8f1002816174301" dependencies = [ "memchr", ] @@ -69,9 +69,9 @@ checksum = "a23eb6b1614318a8071c9b2521f36b424b2c83db5eb3a0fead4a6c0809af6e61" [[package]] name = "bstr" -version = "1.12.0" +version = "1.12.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "234113d19d0d7d613b40e86fb654acf958910802bcceab913a4f9e7cda03b1a4" +checksum = "63044e1ae8e69f3b5a92c736ca6269b8d12fa7efe39bf34ddb06d102cf0e2cab" dependencies = [ "memchr", "serde", @@ -79,9 +79,9 @@ dependencies = [ [[package]] name = "clap" -version = "4.5.50" +version = "4.5.51" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0c2cfd7bf8a6017ddaa4e32ffe7403d547790db06bd171c1c53926faab501623" +checksum = "4c26d721170e0295f191a69bd9a1f93efcdb0aff38684b61ab5750468972e5f5" dependencies = [ "clap_builder", "clap_derive", @@ -89,9 +89,9 @@ dependencies = [ [[package]] name = "clap_builder" -version = "4.5.50" +version = "4.5.51" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0a4c05b9e80c5ccd3a7ef080ad7b6ba7d6fc00a985b8b157197075677c82c7a0" +checksum = "75835f0c7bf681bfd05abe44e965760fea999a5286c6eb2d59883634fd02011a" dependencies = [ "anstream", "anstyle", @@ -184,9 +184,9 @@ checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea" [[package]] name = "ignore" -version = "0.4.24" +version = "0.4.25" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "81776e6f9464432afcc28d03e52eb101c93b6f0566f52aef2427663e700f0403" +checksum = "d3d782a365a015e0f5c04902246139249abf769125006fbe7649e2ee88169b4a" dependencies = [ "crossbeam-deque", "globset", @@ -243,9 +243,9 @@ dependencies = [ [[package]] name = "quote" -version = "1.0.41" +version = "1.0.42" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ce25767e7b499d1b604768e7cde645d14cc8584231ea6b295e9c9eb22c02e1d1" +checksum = "a338cc41d27e6cc6dce6cefc13a0729dfbb81c262b1f519331575dd80ef3067f" dependencies = [ "proc-macro2", ] @@ -336,9 +336,9 @@ checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f" [[package]] name = "syn" -version = "2.0.108" +version = "2.0.110" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "da58917d35242480a05c2897064da0a80589a2a0476c9a3f2fdc83b53502e917" +checksum = "a99801b5bd34ede4cf3fc688c5919368fea4e4814a4664359503e6015b280aea" dependencies = [ "proc-macro2", "quote", @@ -347,9 +347,9 @@ dependencies = [ [[package]] name = "unicode-ident" -version = "1.0.20" +version = "1.0.22" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "462eeb75aeb73aea900253ce739c8e18a67423fadf006037cd3ff27e82748a06" +checksum = "9312f7c4f6ff9069b165498234ce8be658059c6728633667c526e27dc2cf1df5" [[package]] name = "utf8parse" diff --git a/src/doc/rustc-dev-guide/ci/sembr/src/main.rs b/src/doc/rustc-dev-guide/ci/sembr/src/main.rs index b50190c78b7b2..b74dbbe56bfe6 100644 --- a/src/doc/rustc-dev-guide/ci/sembr/src/main.rs +++ b/src/doc/rustc-dev-guide/ci/sembr/src/main.rs @@ -22,13 +22,15 @@ struct Cli { show_diff: bool, } -static REGEX_IGNORE: LazyLock = - LazyLock::new(|| Regex::new(r"^\s*(\d\.|\-|\*)\s+").unwrap()); -static REGEX_IGNORE_END: LazyLock = LazyLock::new(|| Regex::new(r"(\.|\?|;|!)$").unwrap()); +static REGEX_IGNORE_END: LazyLock = + LazyLock::new(|| Regex::new(r"(\.|\?|;|!|,|\-)$").unwrap()); static REGEX_IGNORE_LINK_TARGETS: LazyLock = LazyLock::new(|| Regex::new(r"^\[.+\]: ").unwrap()); static REGEX_SPLIT: LazyLock = - LazyLock::new(|| Regex::new(r"([^\.]\.|[^r]\?|;|!)\s+").unwrap()); + LazyLock::new(|| Regex::new(r"([^\.\d\-\*]\.|[^r]\?|;|!)\s").unwrap()); +// list elements, numbered (1.) or not (- and *) +static REGEX_LIST_ENTRY: LazyLock = + LazyLock::new(|| Regex::new(r"^\s*(\d\.|\-|\*)\s+").unwrap()); fn main() -> Result<()> { let cli = Cli::parse(); @@ -99,7 +101,6 @@ fn ignore(line: &str, in_code_block: bool) -> bool { || line.trim_start().starts_with('>') || line.starts_with('#') || line.trim().is_empty() - || REGEX_IGNORE.is_match(line) || REGEX_IGNORE_LINK_TARGETS.is_match(line) } @@ -120,11 +121,19 @@ fn comply(content: &str) -> String { continue; } if REGEX_SPLIT.is_match(&line) { - let indent = line.find(|ch: char| !ch.is_whitespace()).unwrap(); - let new_lines: Vec<_> = line - .split_inclusive(&*REGEX_SPLIT) - .map(|portion| format!("{:indent$}{}", "", portion.trim())) + let indent = if let Some(regex_match) = REGEX_LIST_ENTRY.find(&line) { + regex_match.len() + } else { + line.find(|ch: char| !ch.is_whitespace()).unwrap() + }; + let mut newly_split_lines = line.split_inclusive(&*REGEX_SPLIT); + let first = newly_split_lines.next().unwrap().trim_end().to_owned(); + let mut remaining: Vec<_> = newly_split_lines + .map(|portion| format!("{:indent$}{}", "", portion.trim_end())) .collect(); + let mut new_lines = Vec::new(); + new_lines.push(first); + new_lines.append(&mut remaining); new_content.splice(new_n..=new_n, new_lines.clone()); new_n += new_lines.len() - 1; } @@ -168,7 +177,10 @@ fn lengthen_lines(content: &str, limit: usize) -> String { let Some(next_line) = content.get(n + 1) else { continue; }; - if ignore(next_line, in_code_block) || REGEX_IGNORE_END.is_match(line) { + if ignore(next_line, in_code_block) + || REGEX_LIST_ENTRY.is_match(next_line) + || REGEX_IGNORE_END.is_match(line) + { continue; } if line.len() + next_line.len() < limit { @@ -182,42 +194,47 @@ fn lengthen_lines(content: &str, limit: usize) -> String { #[test] fn test_sembr() { - let original = "\ + let original = " # some. heading -must! be; split? and. normalizes space -1. ignore numbered +must! be; split? +1. ignore a dot after number. but no further ignore | tables ignore e.g. and ignore i.e. and ignore E.g. too -- ignore. list -* ignore. list +- list. entry + * list. entry ``` some code. block ``` sentence with *italics* should not be ignored. truly. git log main.. compiler + foo. bar. baz "; - let expected = "\ + let expected = " # some. heading must! be; split? -and. -normalizes space -1. ignore numbered +1. ignore a dot after number. + but no further ignore | tables ignore e.g. and ignore i.e. and ignore E.g. too -- ignore. list -* ignore. list +- list. + entry + * list. + entry ``` some code. block ``` sentence with *italics* should not be ignored. truly. git log main.. compiler + foo. + bar. + baz "; assert_eq!(expected, comply(original)); } @@ -230,12 +247,28 @@ short sentences
a bit of text inside
+preserve next line +1. one + +preserve next line +- two + +preserve next line +* three "; let expected = "\ do not split short sentences
a bit of text inside
+preserve next line +1. one + +preserve next line +- two + +preserve next line +* three "; assert_eq!(expected, lengthen_lines(original, 50)); } @@ -263,13 +296,13 @@ fn test_prettify_ignore_link_targets() { #[test] fn test_sembr_then_prettify() { - let original = "\ + let original = " hi there. do not split short sentences. hi again. "; - let expected = "\ + let expected = " hi there. do not split @@ -278,7 +311,7 @@ hi again. "; let processed = comply(original); assert_eq!(expected, processed); - let expected = "\ + let expected = " hi there. do not split short sentences. @@ -286,7 +319,7 @@ hi again. "; let processed = lengthen_lines(&processed, 50); assert_eq!(expected, processed); - let expected = "\ + let expected = " hi there. do not split short sentences. hi again. @@ -297,12 +330,12 @@ hi again. #[test] fn test_sembr_question_mark() { - let original = "\ + let original = " o? whatever r? @reviewer r? @reviewer "; - let expected = "\ + let expected = " o? whatever r? @reviewer diff --git a/src/doc/rustc-dev-guide/rust-version b/src/doc/rustc-dev-guide/rust-version index 04d41c96f5c08..8c841aac8eb60 100644 --- a/src/doc/rustc-dev-guide/rust-version +++ b/src/doc/rustc-dev-guide/rust-version @@ -1 +1 @@ -8401398e1f14a24670ee1a3203713dc2f0f8b3a8 +cc328c12382f05d8ddf6ffc8139deb7985270ad8 diff --git a/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md b/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md index efb21726e3c6a..c924216b8cd30 100644 --- a/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md +++ b/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md @@ -68,7 +68,7 @@ This instructs `git` to perform a "shallow clone", cloning the repository but tr the last `N` commits. Passing `--depth 1` tells `git` to clone the repository but truncate the history to the latest -commit that is on the `master` branch, which is usually fine for browsing the source code or +commit that is on the `main` branch, which is usually fine for browsing the source code or building the compiler. ```bash @@ -172,7 +172,7 @@ You can install it with `cargo install --path src/tools/x`. To clarify that this is another global installed binary util, which is similar to the one declared in section [What is `x.py`](#what-is-xpy), but -it works as an independent process to execute the `x.py` rather than calling the +it works as an independent process to execute the `x.py` rather than calling the shell to run the platform related scripts. ## Create a `bootstrap.toml` diff --git a/src/doc/rustc-dev-guide/src/building/suggested.md b/src/doc/rustc-dev-guide/src/building/suggested.md index 6d7d340e633e2..1c75de3e90421 100644 --- a/src/doc/rustc-dev-guide/src/building/suggested.md +++ b/src/doc/rustc-dev-guide/src/building/suggested.md @@ -296,7 +296,7 @@ lets you use `cargo fmt`. [the section on vscode]: suggested.md#configuring-rust-analyzer-for-rustc [the section on rustup]: how-to-build-and-run.md?highlight=rustup#creating-a-rustup-toolchain -## Faster Builds with CI-rustc +## Faster Builds with CI-rustc If you are not working on the compiler, you often don't need to build the compiler tree. For example, you can skip building the compiler and only build the `library` tree or the @@ -389,7 +389,7 @@ times, and having to update each clone individually. Fortunately, Git has a better solution called [worktrees]. This lets you create multiple "working trees", which all share the same Git database. Moreover, because all of the worktrees share the same object database, if you update a -branch (e.g. master) in any of them, you can use the new commits from any of the +branch (e.g. `main`) in any of them, you can use the new commits from any of the worktrees. One caveat, though, is that submodules do not get shared. They will still be cloned multiple times. @@ -403,10 +403,10 @@ command: git worktree add ../rust2 ``` -Creating a new worktree for a new branch based on `master` looks like: +Creating a new worktree for a new branch based on `main` looks like: ```bash -git worktree add -b my-feature ../rust2 master +git worktree add -b my-feature ../rust2 main ``` You can then use that rust2 folder as a separate workspace for modifying and diff --git a/src/doc/rustc-dev-guide/src/contributing.md b/src/doc/rustc-dev-guide/src/contributing.md index e30819ebccae0..8c764c31dbfa3 100644 --- a/src/doc/rustc-dev-guide/src/contributing.md +++ b/src/doc/rustc-dev-guide/src/contributing.md @@ -55,7 +55,7 @@ Instead, we have 3 release channels: stable, beta, and nightly. - **Stable**: this is the latest stable release for general usage. - **Beta**: this is the next release (will be stable within 6 weeks). -- **Nightly**: follows the `master` branch of the repo. +- **Nightly**: follows the `main` branch of the repo. This is the only channel where unstable features are intended to be used, which happens via opt-in feature gates. @@ -97,7 +97,7 @@ before approving). This is yet another bot that will compile a collection of benchmarks on a compiler with your changes. The numbers are reported -[here][perf], and you can see a comparison of your changes against the latest master. +[here][perf], and you can see a comparison of your changes against the latest `main`. > For an introduction to the performance of Rust code in general > which would also be useful in rustc development, see [The Rust Performance Book]. @@ -153,7 +153,7 @@ We have [a chapter](git.md) on how to use Git when contributing to Rust. ### Keeping your branch up-to-date -The CI in rust-lang/rust applies your patches directly against the current master, +The CI in rust-lang/rust applies your patches directly against current `main`, not against the commit your branch is based on. This can lead to unexpected failures if your branch is outdated, even when there are no explicit merge conflicts. @@ -164,7 +164,7 @@ During review, make incremental commits to address feedback. Prefer to squash or rebase only at the end, or when a reviewer requests it. When updating, use `git push --force-with-lease` and leave a brief comment explaining what changed. -Some repos prefer merging from `upstream/master` instead of rebasing; +Some repos prefer merging from `upstream/main` instead of rebasing; follow the project's conventions. See [keeping things up to date](git.md#keeping-things-up-to-date) for detailed instructions. @@ -264,7 +264,7 @@ It will look something like this: This tells [@bors], our lovable integration bot, that your pull request has been approved. The PR then enters the [merge queue], where [@bors] will run *all* the tests on *every* platform we support. -If it all works out, [@bors] will merge your code into `master` and close the pull request. +If it all works out, [@bors] will merge your code into `main` and close the pull request. Depending on the scale of the change, you may see a slightly different form of `r+`: @@ -288,7 +288,7 @@ You are now ready to file a pull request (PR)? Great! Here are a few points you should be aware of. -All pull requests should be filed against the `master` branch, +All pull requests should be filed against the `main` branch, unless you know for sure that you should target a different branch. Run some style checks before you submit the PR: @@ -303,7 +303,7 @@ Rust follows a _no merge-commit policy_, meaning that when you encounter merge conflicts, you are expected to always rebase instead of merging. For example, -always use rebase when bringing the latest changes from the master branch to your feature branch. +always use rebase when bringing the latest changes from the `main` branch to your feature branch. If your PR contains merge commits, it will get marked as `has-merge-commits`. Once you have removed the merge commits, e.g., through an interactive rebase, you should remove the label again: @@ -328,7 +328,7 @@ the issue in question. However, if your PR fixes a stable-to-beta or stable-to-stable regression and has been accepted for a beta and/or stable backport (i.e., it is marked `beta-accepted` and/or `stable-accepted`), please do *not* use any such keywords since we don't -want the corresponding issue to get auto-closed once the fix lands on master. +want the corresponding issue to get auto-closed once the fix lands on `main`. Please update the PR description while still mentioning the issue somewhere. For example, you could write `Fixes (after beta backport) #NNN.`. diff --git a/src/doc/rustc-dev-guide/src/conventions.md b/src/doc/rustc-dev-guide/src/conventions.md index 4356cf246f89e..cce1d18506946 100644 --- a/src/doc/rustc-dev-guide/src/conventions.md +++ b/src/doc/rustc-dev-guide/src/conventions.md @@ -165,7 +165,7 @@ individually using `./x fmt`. **No merges.** We do not allow merge commits into our history, other than those by bors. If you get a merge conflict, rebase instead via a -command like `git rebase -i rust-lang/master` (presuming you use the +command like `git rebase --interactive rust-lang/main` (presuming you use the name `rust-lang` for your remote). **Individual commits do not have to build (but it's nice).** We do not diff --git a/src/doc/rustc-dev-guide/src/external-repos.md b/src/doc/rustc-dev-guide/src/external-repos.md index fb291aa777ae7..d2b4e791df0e2 100644 --- a/src/doc/rustc-dev-guide/src/external-repos.md +++ b/src/doc/rustc-dev-guide/src/external-repos.md @@ -114,7 +114,7 @@ A `subtree pull` takes all changes since the last `subtree pull` from the tool repo and adds these commits to the rustc repo along with a merge commit that moves the tool changes into the specified directory in the Rust repository. -It is recommended that you always do a push first and get that merged to the tool master branch. +It is recommended that you always do a push first and get that merged to the default branch of the tool. Then, when you do a pull, the merge works without conflicts. While it's definitely possible to resolve conflicts during a pull, you may have to redo the conflict resolution if your PR doesn't get merged fast enough and there are new conflicts. Do not try to @@ -163,7 +163,7 @@ More information may be found on the Forge [Toolstate chapter]. In practice, it is very rare for documentation to have broken toolstate. Breakage is not allowed in the beta and stable channels, and must be addressed -before the PR is merged. They are also not allowed to be broken on master in +before the PR is merged. They are also not allowed to be broken on `main` in the week leading up to the beta cut. [git submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules diff --git a/src/doc/rustc-dev-guide/src/getting-started.md b/src/doc/rustc-dev-guide/src/getting-started.md index 64abd94c69e27..34bc5b59dd03c 100644 --- a/src/doc/rustc-dev-guide/src/getting-started.md +++ b/src/doc/rustc-dev-guide/src/getting-started.md @@ -140,7 +140,7 @@ You can find the list of such PRs [here][abandoned-prs]. If the PR has been implemented in some other way in the meantime, the `S-inactive` label should be removed from it. If not, and it seems that there is still interest in the change, -you can try to rebase the pull request on top of the latest `master` branch and send a new +you can try to rebase the pull request on top of the latest `main` branch and send a new pull request, continuing the work on the feature. [abandoned-prs]: https://github.com/rust-lang/rust/pulls?q=is%3Apr+label%3AS-inactive+is%3Aclosed diff --git a/src/doc/rustc-dev-guide/src/git.md b/src/doc/rustc-dev-guide/src/git.md index 56f1f01f26dbf..e7e84e2ea7f54 100644 --- a/src/doc/rustc-dev-guide/src/git.md +++ b/src/doc/rustc-dev-guide/src/git.md @@ -57,9 +57,9 @@ useful when contributing to other repositories in the Rust project. Below is the normal procedure that you're likely to use for most minor changes and PRs: - 1. Ensure that you're making your changes on top of master: - `git checkout master`. - 2. Get the latest changes from the Rust repo: `git pull upstream master --ff-only`. + 1. Ensure that you're making your changes on top of `main`: + `git checkout main`. + 2. Get the latest changes from the Rust repo: `git pull upstream main --ff-only`. (see [No-Merge Policy][no-merge-policy] for more info about this). 3. Make a new branch for your change: `git checkout -b issue-12345-fix`. 4. Make some changes to the repo and test them. @@ -72,7 +72,7 @@ and PRs: 6. Push your changes to your fork: `git push --set-upstream origin issue-12345-fix` (After adding commits, you can use `git push` and after rebasing or pulling-and-rebasing, you can use `git push --force-with-lease`). - 7. [Open a PR][ghpullrequest] from your fork to `rust-lang/rust`'s master branch. + 7. [Open a PR][ghpullrequest] from your fork to `rust-lang/rust`'s `main` branch. [ghpullrequest]: https://guides.github.com/activities/forking/#making-a-pull-request @@ -101,7 +101,7 @@ Here are some common issues you might run into: Git has two ways to update your branch with the newest changes: merging and rebasing. Rust [uses rebasing][no-merge-policy]. If you make a merge commit, it's not too hard to fix: -`git rebase -i upstream/master`. +`git rebase -i upstream/main`. See [Rebasing](#rebasing) for more about rebasing. @@ -151,7 +151,7 @@ replace `src/tools/cargo` with the path to that submodule): - If you modified the submodule in several different commits, you will need to repeat steps 1-3 for each commit you modified. You'll know when to stop when the `git log` command shows a commit that's not authored by you. -5. Squash your changes into the existing commits: `git rebase --autosquash -i upstream/master` +5. Squash your changes into the existing commits: `git rebase --autosquash -i upstream/main` 6. [Push your changes](#standard-process). ### I see "error: cannot rebase" when I try to rebase @@ -197,7 +197,7 @@ and just want to get a clean copy of the repository back, you can use `git reset ```console # WARNING: this throws out any local changes you've made! Consider resolving the conflicts instead. -git reset --hard master +git reset --hard main ``` ### failed to push some refs @@ -222,12 +222,12 @@ rebase! Use `git push --force-with-lease` instead. If you see many commits in your rebase list, or merge commits, or commits by other people that you didn't write, it likely means you're trying to rebase over the wrong branch. For example, you may -have a `rust-lang/rust` remote `upstream`, but ran `git rebase origin/master` instead of `git rebase -upstream/master`. The fix is to abort the rebase and use the correct branch instead: +have a `rust-lang/rust` remote `upstream`, but ran `git rebase origin/main` instead of `git rebase +upstream/main`. The fix is to abort the rebase and use the correct branch instead: ```console git rebase --abort -git rebase -i upstream/master +git rebase --interactive upstream/main ```
Click here to see an example of rebasing over the wrong branch @@ -243,8 +243,8 @@ Git says you have modified some files that you have never edited. For example, running `git status` gives you something like (note the `new commits` mention): ```console -On branch master -Your branch is up to date with 'origin/master'. +On branch main +Your branch is up to date with 'origin/main'. Changes not staged for commit: (use "git add ..." to update what will be committed) @@ -277,11 +277,11 @@ merged. To do that, you need to rebase your work on top of rust-lang/rust. ### Rebasing -To rebase your feature branch on top of the newest version of the master branch +To rebase your feature branch on top of the newest version of the `main` branch of rust-lang/rust, checkout your branch, and then run this command: ```console -git pull --rebase https://github.com/rust-lang/rust.git master +git pull --rebase https://github.com/rust-lang/rust.git main ``` > If you are met with the following error: @@ -293,10 +293,10 @@ git pull --rebase https://github.com/rust-lang/rust.git master > case, run `git stash` before rebasing, and then `git stash pop` after you > have rebased and fixed all conflicts. -When you rebase a branch on master, all the changes on your branch are -reapplied to the most recent version of master. In other words, Git tries to -pretend that the changes you made to the old version of master were instead -made to the new version of master. During this process, you should expect to +When you rebase a branch on main, all the changes on your branch are +reapplied to the most recent version of `main`. In other words, Git tries to +pretend that the changes you made to the old version of `main` were instead +made to the new version of `main`. During this process, you should expect to encounter at least one "rebase conflict." This happens when Git's attempt to reapply the changes fails because your changes conflicted with other changes that have been made. You can tell that this happened because you'll see @@ -318,9 +318,9 @@ Your code This represents the lines in the file that Git could not figure out how to rebase. The section between `<<<<<<< HEAD` and `=======` has the code from -master, while the other side has your version of the code. You'll need to +`main`, while the other side has your version of the code. You'll need to decide how to deal with the conflict. You may want to keep your changes, -keep the changes on master, or combine the two. +keep the changes on `main`, or combine the two. Generally, resolving the conflict consists of two steps: First, fix the particular conflict. Edit the file to make the changes you want and remove the @@ -343,15 +343,15 @@ guide on rebasing work and dealing with merge conflicts. Here is some general advice about how to keep your local repo up-to-date with upstream changes: -Using `git pull upstream master` while on your local master branch regularly +Using `git pull upstream main` while on your local `main` branch regularly will keep it up-to-date. You will also want to keep your feature branches up-to-date as well. After pulling, you can checkout the feature branches and rebase them: ```console -git checkout master -git pull upstream master --ff-only # to make certain there are no merge commits -git rebase master feature_branch +git checkout main +git pull upstream main --ff-only # to make certain there are no merge commits +git rebase main feature_branch git push --force-with-lease # (set origin to be the same as local) ``` @@ -360,7 +360,7 @@ To avoid merges as per the [No-Merge Policy](#no-merge-policy), you may want to to ensure that Git doesn't create merge commits when `git pull`ing, without needing to pass `--ff-only` or `--rebase` every time. -You can also `git push --force-with-lease` from master to double-check that your +You can also `git push --force-with-lease` from main to double-check that your feature branches are in sync with their state on the Github side. ## Advanced Rebasing @@ -373,14 +373,14 @@ On the one hand, you lose track of the steps in which changes were made, but the history becomes easier to work with. If there are no conflicts and you are just squashing to clean up the history, -use `git rebase --interactive --keep-base master`. This keeps the fork point +use `git rebase --interactive --keep-base main`. This keeps the fork point of your PR the same, making it easier to review the diff of what happened across your rebases. Squashing can also be useful as part of conflict resolution. If your branch contains multiple consecutive rewrites of the same code, or if the rebase conflicts are extremely severe, you can use -`git rebase --interactive master` to gain more control over the process. This +`git rebase --interactive main` to gain more control over the process. This allows you to choose to skip commits, edit the commits that you do not skip, change the order in which they are applied, or "squash" them into each other. @@ -388,8 +388,8 @@ Alternatively, you can sacrifice the commit history like this: ```console # squash all the changes into one commit so you only have to worry about conflicts once -git rebase -i --keep-base master # and squash all changes along the way -git rebase master +git rebase --interactive --keep-base main # and squash all changes along the way +git rebase main # fix all merge conflicts git rebase --continue ``` @@ -402,9 +402,9 @@ because they only represent "fixups" and not real changes. For example, After completing a rebase, and before pushing up your changes, you may want to review the changes between your old branch and your new one. You can do that -with `git range-diff master @{upstream} HEAD`. +with `git range-diff main @{upstream} HEAD`. -The first argument to `range-diff`, `master` in this case, is the base revision +The first argument to `range-diff`, `main` in this case, is the base revision that you're comparing your old and new branch against. The second argument is the old version of your branch; in this case, `@upstream` means the version that you've pushed to GitHub, which is the same as what people will see in your pull @@ -413,7 +413,7 @@ your branch; in this case, it is `HEAD`, which is the commit that is currently checked-out in your local repo. Note that you can also use the equivalent, abbreviated form `git range-diff -master @{u} HEAD`. +main @{u} HEAD`. Unlike in regular Git diffs, you'll see a `-` or `+` next to another `-` or `+` in the range-diff output. The marker on the left indicates a change between the @@ -481,7 +481,7 @@ to follow and understand. ### Hiding whitespace Github has a button for disabling whitespace changes that may be useful. -You can also use `git diff -w origin/master` to view changes locally. +You can also use `git diff -w origin/main` to view changes locally. ![hide whitespace](./img/github-whitespace-changes.png) diff --git a/src/doc/rustc-dev-guide/src/implementing_new_features.md b/src/doc/rustc-dev-guide/src/implementing_new_features.md index 00bce8599e430..4526a7af0f463 100644 --- a/src/doc/rustc-dev-guide/src/implementing_new_features.md +++ b/src/doc/rustc-dev-guide/src/implementing_new_features.md @@ -1,8 +1,12 @@ + + # Implementing new language features -When you want to implement a new significant feature in the compiler, you need to go through this process to make sure everything goes smoothly. +When you want to implement a new significant feature in the compiler, +you need to go through this process to make sure everything goes smoothly. -**NOTE: This section is for *language* features, not *library* features, which use [a different process].** +**NOTE: This section is for *language* features, not *library* features, +which use [a different process].** See also [the Rust Language Design Team's procedures][lang-propose] for proposing changes to the language. @@ -11,55 +15,117 @@ See also [the Rust Language Design Team's procedures][lang-propose] for proposin ## The @rfcbot FCP process -When the change is small, uncontroversial, non-breaking, and does not affect the stable language in any user-observable ways or add any new unstable features, then it can be done with just writing a PR and getting an r+ from someone who knows that part of the code. However, if not, more must be done. Even for compiler-internal work, it would be a bad idea to push a controversial change without consensus from the rest of the team (both in the "distributed system" sense to make sure you don't break anything you don't know about, and in the social sense to avoid PR fights). - -For changes that need the consensus of a team, we us the process of proposing a final comment period (FCP). If you're not on the relevant team (and thus don't have @rfcbot permissions), ask someone who is to start one; unless they have a concern themselves, they should. - -The FCP process is only needed if you need consensus – if no processes require consensus for your change and you don't think anyone would have a problem with it, it's OK to rely on only an r+. For example, it is OK to add or modify unstable command-line flags or attributes in the reserved compiler-internal `rustc_` namespace without an FCP for compiler development or standard library use, as long as you don't expect them to be in wide use in the nightly ecosystem. Some teams have lighter weight processes that they use in scenarios like this; for example, the compiler team recommends filing a Major Change Proposal ([MCP][mcp]) as a lightweight way to garner support and feedback without requiring full consensus. - -[mcp]: https://forge.rust-lang.org/compiler/proposals-and-stabilization.html#how-do-i-submit-an-mcp - -You don't need to have the implementation fully ready for r+ to propose an FCP, but it is generally a good idea to have at least a proof of concept so that people can see what you are talking about. - -When an FCP is proposed, it requires all members of the team to sign off on the FCP. After they all do so, there's a 10-day-long "final comment period" (hence the name) where everybody can comment, and if no concerns are raised, the PR/issue gets FCP approval. +When the change is small, uncontroversial, non-breaking, +and does not affect the stable language in any user-observable ways or add any new unstable features, +then it can be done with just writing a PR and getting an r+ from someone who knows that part of the code. +However, if not, more must be done. +Even for compiler-internal work, +it would be a bad idea to push a controversial change without consensus from the rest of the team +(both in the "distributed system" sense to make sure you don't break anything you don't know about, +and in the social sense to avoid PR fights). + +For changes that need the consensus of a team, +we use the process of proposing a final comment period (FCP). +If you're not on the relevant team (and thus don't have @rfcbot permissions), +ask someone who is to start one; +unless they have a concern themselves, they should. + +The FCP process is only needed if you need consensus – +if no processes require consensus for your change +and you don't think anyone would have a problem with it, it's OK to rely on only an r+. +For example, +it is OK to add or modify unstable command-line flags +or attributes in the reserved compiler-internal `rustc_` namespace +without an FCP for compiler development or standard library use, +as long as you don't expect them to be in wide use in the nightly ecosystem. +Some teams have lighter weight processes that they use in scenarios like this; +for example, +the compiler team recommends filing a Major Change Proposal ([MCP]) +as a lightweight way to garner support and feedback without requiring full consensus. + +[MCP]: https://forge.rust-lang.org/compiler/proposals-and-stabilization.html#how-do-i-submit-an-mcp + +You don't need to have the implementation fully ready for r+ to propose an FCP, +but it is generally a good idea to have at least a proof of concept +so that people can see what you are talking about. + +When an FCP is proposed, it requires all members of the team to sign off on the FCP. +After they all do so, +there's a 10-day-long "final comment period" (hence the name) where everybody can comment, +and if no concerns are raised, the PR/issue gets FCP approval. ## The logistics of writing features -There are a few "logistical" hoops you might need to go through in order to implement a feature in a working way. +There are a few "logistical" hoops you might need to go through +in order to implement a feature in a working way. ### Warning Cycles -In some cases, a feature or bugfix might break some existing programs in some edge cases. In that case, you'll want to do a crater run to assess the impact and possibly add a future-compatibility lint, similar to those used for [edition-gated lints](diagnostics.md#edition-gated-lints). +In some cases, a feature or bugfix might break some existing programs in some edge cases. +In that case, +you'll want to do a crater run to assess the impact and possibly add a future-compatibility lint, +similar to those used for [edition-gated lints](diagnostics.md#edition-gated-lints). ### Stability -We [value the stability of Rust]. Code that works and runs on stable should (mostly) not break. Because of that, we don't want to release a feature to the world with only team consensus and code review - we want to gain real-world experience on using that feature on nightly, and we might want to change the feature based on that experience. - -To allow for that, we must make sure users don't accidentally depend on that new feature - otherwise, especially if experimentation takes time or is delayed and the feature takes the trains to stable, it would end up de facto stable and we'll not be able to make changes in it without breaking people's code. - -The way we do that is that we make sure all new features are feature gated - they can't be used without enabling a feature gate (`#[feature(foo)]`), which can't be done in a stable/beta compiler. See the [stability in code] section for the technical details. - -Eventually, after we gain enough experience using the feature, make the necessary changes, and are satisfied, we expose it to the world using the stabilization process described [here]. Until then, the feature is not set in stone: every part of the feature can be changed, or the feature might be completely rewritten or removed. Features do not gain tenure by being unstable and unchanged for long periods of time. +We [value the stability of Rust]. +Code that works and runs on stable should (mostly) not break. +Because of that, +we don't want to release a feature to the world with only team consensus and code review - +we want to gain real-world experience on using that feature on nightly, +and we might want to change the feature based on that experience. + +To allow for that, +we must make sure users don't accidentally depend on that new feature - +otherwise, +especially if experimentation takes time or is delayed and the feature takes the trains to stable, +it would end up de facto stable +and we'll not be able to make changes in it without breaking people's code. + +The way we do that is that we make sure all new features are feature gated - +they can't be used without enabling a feature gate (`#[feature(foo)]`), +which can't be done in a stable/beta compiler. +See the [stability in code] section for the technical details. + +Eventually, after we gain enough experience using the feature, make the necessary changes, +and are satisfied, we expose it to the world using the stabilization process described [here]. +Until then, the feature is not set in stone: +every part of the feature can be changed, or the feature might be completely rewritten or removed. +Features do not gain tenure by being unstable and unchanged for long periods of time. ### Tracking Issues -To keep track of the status of an unstable feature, the experience we get while using it on -nightly, and of the concerns that block its stabilization, every feature-gate needs a tracking -issue. When creating issues and PRs related to the feature, reference this tracking issue, and when there are updates about the feature's progress, post those to the tracking issue. +To keep track of the status of an unstable feature, +the experience we get while using it on nightly, +and of the concerns that block its stabilization, +every feature-gate needs a tracking issue. +When creating issues and PRs related to the feature, reference this tracking issue, +and when there are updates about the feature's progress, post those to the tracking issue. -For features that are part of an accept RFC or approved lang experiment, use the tracking issue for that. +For features that are part of an accept RFC or approved lang experiment, +use the tracking issue for that. -For other features, create a tracking issue for that feature. The issue title should be "Tracking issue for YOUR FEATURE". Use the ["Tracking Issue" issue template][template]. +For other features, create a tracking issue for that feature. +The issue title should be "Tracking issue for YOUR FEATURE". +Use the ["Tracking Issue" issue template][template]. [template]: https://github.com/rust-lang/rust/issues/new?template=tracking_issue.md ### Lang experiments -To land in the compiler, features that have user-visible effects on the language (even unstable ones) must either be part of an accepted RFC or an approved [lang experiment]. +To land in the compiler, +features that have user-visible effects on the language (even unstable ones) +must either be part of an accepted RFC or an approved [lang experiment]. -To propose a new lang experiment, open an issue in `rust-lang/rust` that describes the motivation and the intended solution. If it's accepted, this issue will become the tracking issue for the experiment, so use the tracking issue [template] while also including these other details. Nominate the issue for the lang team and CC `@rust-lang/lang` and `@rust-lang/lang-advisors`. When the experiment is approved, the tracking issue will be marked as `B-experimental`. +To propose a new lang experiment, +open an issue in `rust-lang/rust` that describes the motivation and the intended solution. +If it's accepted, this issue will become the tracking issue for the experiment, +so use the tracking issue [template] while also including these other details. +Nominate the issue for the lang team and CC `@rust-lang/lang` and `@rust-lang/lang-advisors`. +When the experiment is approved, the tracking issue will be marked as `B-experimental`. -Feature flags related to a lang experiment must be marked as `incomplete` until an RFC is accepted for the feature. +Feature flags related to a lang experiment must be marked as `incomplete` +until an RFC is accepted for the feature. [lang experiment]: https://lang-team.rust-lang.org/how_to/experiment.html @@ -67,9 +133,12 @@ Feature flags related to a lang experiment must be marked as `incomplete` until The below steps needs to be followed in order to implement a new unstable feature: -1. Open or identify the [tracking issue]. For features that are part of an accept RFC or approved lang experiment, use the tracking issue for that. +1. Open or identify the [tracking issue]. + For features that are part of an accept RFC or approved lang experiment, + use the tracking issue for that. - Label the tracking issue with `C-tracking-issue` and the relevant `F-feature_name` label (adding that label if needed). + Label the tracking issue with `C-tracking-issue` and the relevant `F-feature_name` label + (adding that label if needed). 1. Pick a name for the feature gate (for RFCs, use the name in the RFC). @@ -77,14 +146,17 @@ The below steps needs to be followed in order to implement a new unstable featur Note that this block must be in alphabetical order. -1. Add a feature gate declaration to `rustc_feature/src/unstable.rs` in the unstable `declare_features` block. +1. Add a feature gate declaration to `rustc_feature/src/unstable.rs` + in the unstable `declare_features` block. ```rust ignore /// description of feature (unstable, $feature_name, "CURRENT_RUSTC_VERSION", Some($tracking_issue_number)) ``` - If you haven't yet opened a tracking issue (e.g. because you want initial feedback on whether the feature is likely to be accepted), you can temporarily use `None` - but make sure to update it before the PR is merged! + If you haven't yet opened a tracking issue + (e.g. because you want initial feedback on whether the feature is likely to be accepted), + you can temporarily use `None` - but make sure to update it before the PR is merged! For example: @@ -93,7 +165,9 @@ The below steps needs to be followed in order to implement a new unstable featur (unstable, non_ascii_idents, "CURRENT_RUSTC_VERSION", Some(55467), None), ``` - Features can be marked as incomplete, and trigger the warn-by-default [`incomplete_features` lint] by setting their type to `incomplete`: + Features can be marked as incomplete, + and trigger the warn-by-default [`incomplete_features` lint] + by setting their type to `incomplete`: [`incomplete_features` lint]: https://doc.rust-lang.org/rustc/lints/listing/warn-by-default.html#incomplete-features @@ -102,27 +176,48 @@ The below steps needs to be followed in order to implement a new unstable featur (incomplete, deref_patterns, "CURRENT_RUSTC_VERSION", Some(87121), None), ``` - Feature flags related to a lang experiment must be marked as `incomplete` until an RFC is accepted for the feature. + Feature flags related to a lang experiment must be marked as `incomplete` + until an RFC is accepted for the feature. - To avoid [semantic merge conflicts], use `CURRENT_RUSTC_VERSION` instead of `1.70` or another explicit version number. + To avoid [semantic merge conflicts], + use `CURRENT_RUSTC_VERSION` instead of `1.70` or another explicit version number. [semantic merge conflicts]: https://bors.tech/essay/2017/02/02/pitch/ -1. Prevent usage of the new feature unless the feature gate is set. You can check it in most places in the compiler using the expression `tcx.features().$feature_name()`. +1. Prevent usage of the new feature unless the feature gate is set. + You can check it in most places in the compiler + using the expression `tcx.features().$feature_name()`. - If the feature gate is not set, you should either maintain the pre-feature behavior or raise an error, depending on what makes sense. Errors should generally use [`rustc_session::parse::feature_err`]. For an example of adding an error, see [#81015]. + If the feature gate is not set, + you should either maintain the pre-feature behavior or raise an error, + depending on what makes sense. + Errors should generally use [`rustc_session::parse::feature_err`]. + For an example of adding an error, see [#81015]. - For features introducing new syntax, pre-expansion gating should be used instead. During parsing, when the new syntax is parsed, the symbol must be inserted to the current crate's [`GatedSpans`] via `self.sess.gated_span.gate(sym::my_feature, span)`. + For features introducing new syntax, pre-expansion gating should be used instead. + During parsing, when the new syntax is parsed, + the symbol must be inserted to the current crate's [`GatedSpans`] + via `self.sess.gated_span.gate(sym::my_feature, span)`. - After being inserted to the gated spans, the span must be checked in the [`rustc_ast_passes::feature_gate::check_crate`] function, which actually denies features. Exactly how it is gated depends on the exact type of feature, but most likely will use the `gate_all!()` macro. + After being inserted to the gated spans, + the span must be checked in the [`rustc_ast_passes::feature_gate::check_crate`] function, + which actually denies features. + Exactly how it is gated depends on the exact type of feature, + but most likely will use the `gate_all!()` macro. -1. Add a test to ensure the feature cannot be used without a feature gate, by creating `tests/ui/feature-gates/feature-gate-$feature_name.rs`. You can generate the corresponding `.stderr` file by running `./x test tests/ui/feature-gates/ --bless`. +1. Add a test to ensure the feature cannot be used without a feature gate, + by creating `tests/ui/feature-gates/feature-gate-$feature_name.rs`. + You can generate the corresponding `.stderr` file + by running `./x test tests/ui/feature-gates/ --bless`. -1. Add a section to the unstable book, in `src/doc/unstable-book/src/language-features/$feature_name.md`. +1. Add a section to the unstable book, + in `src/doc/unstable-book/src/language-features/$feature_name.md`. -1. Write a lot of tests for the new feature, preferably in `tests/ui/$feature_name/`. PRs without tests will not be accepted! +1. Write a lot of tests for the new feature, preferably in `tests/ui/$feature_name/`. + PRs without tests will not be accepted! -1. Get your PR reviewed and land it. You have now successfully implemented a feature in Rust! +1. Get your PR reviewed and land it. + You have now successfully implemented a feature in Rust! [`GatedSpans`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_session/parse/struct.GatedSpans.html [#81015]: https://github.com/rust-lang/rust/pull/81015 @@ -136,7 +231,10 @@ The below steps needs to be followed in order to implement a new unstable featur ## Call for testing -Once the implementation is complete, the feature will be available to nightly users but not yet part of stable Rust. This is a good time to write a blog post on [the main Rust blog][rust-blog] and issue a "call for testing". +Once the implementation is complete, +the feature will be available to nightly users but not yet part of stable Rust. +This is a good time to write a blog post on [the main Rust blog][rust-blog] +and issue a "call for testing". Some earlier such blog posts include: @@ -144,25 +242,40 @@ Some earlier such blog posts include: 2. [Changes to `impl Trait` in Rust 2024](https://blog.rust-lang.org/2024/09/05/impl-trait-capture-rules.html) 3. [Async Closures MVP: Call for Testing!](https://blog.rust-lang.org/inside-rust/2024/08/09/async-closures-call-for-testing/) -Alternatively, [*This Week in Rust*][twir] has a [section][twir-cft] for this. One example of this having been used is: +Alternatively, [*This Week in Rust*][twir] has a [section][twir-cft] for this. +One example of this having been used is: - [Call for testing on boolean literals as cfg predicates](https://github.com/rust-lang/rust/issues/131204#issuecomment-2569314526) -Which option to choose might depend on how significant the language change is, though note that the [*This Week in Rust*][twir] section might be less visible than a dedicated post on the main Rust blog. +Which option to choose might depend on how significant the language change is, +though note that the [*This Week in Rust*][twir] section might be less visible +than a dedicated post on the main Rust blog. ## Polishing -Giving users a polished experience means more than just implementing the feature in rustc. We need to think about all of the tools and resources that we ship. This work includes: +Giving users a polished experience means more than just implementing the feature in rustc. +We need to think about all of the tools and resources that we ship. +This work includes: - Documenting the language feature in the [Rust Reference][reference]. - Extending [`rustfmt`] to format any new syntax (if applicable). -- Extending [`rust-analyzer`] (if applicable). The extent of this work can depend on the nature of the language feature, as some features don't need to be blocked on *full* support. - - When a language feature degrades the user experience simply by existing before support is implemented in [`rust-analyzer`], that may lead the lang team to raise a blocking concern. - - Examples of such might include new syntax that [`rust-analyzer`] can't parse or type inference changes it doesn't understand when those lead to bogus diagnostics. +- Extending [`rust-analyzer`] (if applicable). + The extent of this work can depend on the nature of the language feature, + as some features don't need to be blocked on *full* support. + - When a language feature degrades the user experience + simply by existing before support is implemented in [`rust-analyzer`], + that may lead the lang team to raise a blocking concern. + - Examples of such might include new syntax that [`rust-analyzer`] can't parse + or type inference changes it doesn't understand when those lead to bogus diagnostics. ## Stabilization -The final step in the feature lifecycle is [stabilization][stab], which is when the feature becomes available to all Rust users. At this point, backward incompatible changes are generally no longer permitted (see the lang team's [defined semver policies](https://rust-lang.github.io/rfcs/1122-language-semver.html) for details). To learn more about stabilization, see the [stabilization guide][stab]. +The final step in the feature lifecycle is [stabilization][stab], +which is when the feature becomes available to all Rust users. +At this point, +backward incompatible changes are generally no longer permitted +(see the lang team's [defined semver policies](https://rust-lang.github.io/rfcs/1122-language-semver.html) for details). +To learn more about stabilization, see the [stabilization guide][stab]. [stab]: ./stabilization_guide.md diff --git a/src/doc/rustc-dev-guide/src/offload/usage.md b/src/doc/rustc-dev-guide/src/offload/usage.md index 9d5839334b1a9..7abf90aa6e0b6 100644 --- a/src/doc/rustc-dev-guide/src/offload/usage.md +++ b/src/doc/rustc-dev-guide/src/offload/usage.md @@ -76,7 +76,7 @@ rustc +offload --edition 2024 src/lib.rs -g --crate-type cdylib -C opt-level=3 - Now we generate the device code. Replace the target-cpu with the right code for your gpu. ``` -RUSTFLAGS="-Ctarget-cpu=gfx90a --emit=llvm-bc,llvm-ir" cargo +offload build -Zunstable-options -r -v --target amdgcn-amd-amdhsa -Zbuild-std=core +RUSTFLAGS="-Ctarget-cpu=gfx90a --emit=llvm-bc,llvm-ir -Zoffload=Enable -Zunstable-options" cargo +offload build -Zunstable-options -r -v --target amdgcn-amd-amdhsa -Zbuild-std=core ``` Now find the `.ll` under target/amdgcn-amd-amdhsa folder and copy it to a device.ll file (or adjust the file names below). @@ -90,13 +90,13 @@ rm bare.amdgcn.gfx90a.img* ``` ``` -clang-offload-packager" "-o" "host.out" "--image=file=device.bc,triple=amdgcn-amd-amdhsa,arch=gfx90a,kind=openmp" +"clang-offload-packager" "-o" "host.out" "--image=file=device.bc,triple=amdgcn-amd-amdhsa,arch=gfx90a,kind=openmp" -clang-21" "-cc1" "-triple" "x86_64-unknown-linux-gnu" "-S" "-save-temps=cwd" "-disable-free" "-clear-ast-before-backend" "-main-file-name" "lib.rs" "-mrelocation-model" "pic" "-pic-level" "2" "-pic-is-pie" "-mframe-pointer=all" "-fmath-errno" "-ffp-contract=on" "-fno-rounding-math" "-mconstructor-aliases" "-funwind-tables=2" "-target-cpu" "x86-64" "-tune-cpu" "generic" "-resource-dir" "//rust/build/x86_64-unknown-linux-gnu/llvm/lib/clang/21" "-ferror-limit" "19" "-fopenmp" "-fopenmp-offload-mandatory" "-fgnuc-version=4.2.1" "-fskip-odr-check-in-gmf" "-fembed-offload-object=host.out" "-fopenmp-targets=amdgcn-amd-amdhsa" "-faddrsig" "-D__GCC_HAVE_DWARF2_CFI_ASM=1" "-o" "host.s" "-x" "ir" "lib.bc" +"clang-21" "-cc1" "-triple" "x86_64-unknown-linux-gnu" "-S" "-save-temps=cwd" "-disable-free" "-clear-ast-before-backend" "-main-file-name" "lib.rs" "-mrelocation-model" "pic" "-pic-level" "2" "-pic-is-pie" "-mframe-pointer=all" "-fmath-errno" "-ffp-contract=on" "-fno-rounding-math" "-mconstructor-aliases" "-funwind-tables=2" "-target-cpu" "x86-64" "-tune-cpu" "generic" "-resource-dir" "//rust/build/x86_64-unknown-linux-gnu/llvm/lib/clang/21" "-ferror-limit" "19" "-fopenmp" "-fopenmp-offload-mandatory" "-fgnuc-version=4.2.1" "-fskip-odr-check-in-gmf" "-fembed-offload-object=host.out" "-fopenmp-targets=amdgcn-amd-amdhsa" "-faddrsig" "-D__GCC_HAVE_DWARF2_CFI_ASM=1" "-o" "host.s" "-x" "ir" "lib.bc" -clang-21" "-cc1as" "-triple" "x86_64-unknown-linux-gnu" "-filetype" "obj" "-main-file-name" "lib.rs" "-target-cpu" "x86-64" "-mrelocation-model" "pic" "-o" "host.o" "host.s" +"clang-21" "-cc1as" "-triple" "x86_64-unknown-linux-gnu" "-filetype" "obj" "-main-file-name" "lib.rs" "-target-cpu" "x86-64" "-mrelocation-model" "pic" "-o" "host.o" "host.s" -clang-linker-wrapper" "--should-extract=gfx90a" "--device-compiler=amdgcn-amd-amdhsa=-g" "--device-compiler=amdgcn-amd-amdhsa=-save-temps=cwd" "--device-linker=amdgcn-amd-amdhsa=-lompdevice" "--host-triple=x86_64-unknown-linux-gnu" "--save-temps" "--linker-path=/ABSOlUTE_PATH_TO/rust/build/x86_64-unknown-linux-gnu/lld/bin/ld.lld" "--hash-style=gnu" "--eh-frame-hdr" "-m" "elf_x86_64" "-pie" "-dynamic-linker" "/lib64/ld-linux-x86-64.so.2" "-o" "bare" "/lib/../lib64/Scrt1.o" "/lib/../lib64/crti.o" "/ABSOLUTE_PATH_TO/crtbeginS.o" "-L/ABSOLUTE_PATH_TO/rust/build/x86_64-unknown-linux-gnu/llvm/bin/../lib/x86_64-unknown-linux-gnu" "-L/ABSOLUTE_PATH_TO/rust/build/x86_64-unknown-linux-gnu/llvm/lib/clang/21/lib/x86_64-unknown-linux-gnu" "-L/lib/../lib64" "-L/usr/lib64" "-L/lib" "-L/usr/lib" "host.o" "-lstdc++" "-lm" "-lomp" "-lomptarget" "-L/ABSOLUTE_PATH_TO/rust/build/x86_64-unknown-linux-gnu/llvm/lib" "-lgcc_s" "-lgcc" "-lpthread" "-lc" "-lgcc_s" "-lgcc" "/ABSOLUTE_PATH_TO/crtendS.o" "/lib/../lib64/crtn.o" +"clang-linker-wrapper" "--should-extract=gfx90a" "--device-compiler=amdgcn-amd-amdhsa=-g" "--device-compiler=amdgcn-amd-amdhsa=-save-temps=cwd" "--device-linker=amdgcn-amd-amdhsa=-lompdevice" "--host-triple=x86_64-unknown-linux-gnu" "--save-temps" "--linker-path=/ABSOlUTE_PATH_TO/rust/build/x86_64-unknown-linux-gnu/lld/bin/ld.lld" "--hash-style=gnu" "--eh-frame-hdr" "-m" "elf_x86_64" "-pie" "-dynamic-linker" "/lib64/ld-linux-x86-64.so.2" "-o" "bare" "/lib/../lib64/Scrt1.o" "/lib/../lib64/crti.o" "/ABSOLUTE_PATH_TO/crtbeginS.o" "-L/ABSOLUTE_PATH_TO/rust/build/x86_64-unknown-linux-gnu/llvm/bin/../lib/x86_64-unknown-linux-gnu" "-L/ABSOLUTE_PATH_TO/rust/build/x86_64-unknown-linux-gnu/llvm/lib/clang/21/lib/x86_64-unknown-linux-gnu" "-L/lib/../lib64" "-L/usr/lib64" "-L/lib" "-L/usr/lib" "host.o" "-lstdc++" "-lm" "-lomp" "-lomptarget" "-L/ABSOLUTE_PATH_TO/rust/build/x86_64-unknown-linux-gnu/llvm/lib" "-lgcc_s" "-lgcc" "-lpthread" "-lc" "-lgcc_s" "-lgcc" "/ABSOLUTE_PATH_TO/crtendS.o" "/lib/../lib64/crtn.o" ``` Especially for the last command I recommend to not fix the paths, but rather just re-generate them by copying a bare-mode openmp example and compiling it with your clang. By adding `-###` to your clang invocation, you can see the invidual steps. diff --git a/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-gui-test-suite.md b/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-gui-test-suite.md index 419f03d020a83..d18021bf278d9 100644 --- a/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-gui-test-suite.md +++ b/src/doc/rustc-dev-guide/src/rustdoc-internals/rustdoc-gui-test-suite.md @@ -11,4 +11,4 @@ These use a NodeJS-based tool called [`browser-UI-test`] that uses [puppeteer] t [`browser-UI-test`]: https://github.com/GuillaumeGomez/browser-UI-test/ [puppeteer]: https://pptr.dev/ [rustdoc-gui-readme]: https://github.com/rust-lang/rust/blob/HEAD/tests/rustdoc-gui/README.md -[goml-script]: https://github.com/GuillaumeGomez/browser-UI-test/blob/master/goml-script.md +[goml-script]: https://github.com/GuillaumeGomez/browser-UI-test/blob/main/goml-script.md diff --git a/src/doc/rustc-dev-guide/src/sanitizers.md b/src/doc/rustc-dev-guide/src/sanitizers.md index 7b84335e3b906..673d650e6050b 100644 --- a/src/doc/rustc-dev-guide/src/sanitizers.md +++ b/src/doc/rustc-dev-guide/src/sanitizers.md @@ -2,8 +2,8 @@ The rustc compiler contains support for following sanitizers: -* [AddressSanitizer][clang-asan] a faster memory error detector. Can - detect out-of-bounds access to heap, stack, and globals, use after free, use +* [AddressSanitizer][clang-asan] a faster memory error detector. + Can detect out-of-bounds access to heap, stack, and globals, use after free, use after return, double free, invalid free, memory leaks. * [ControlFlowIntegrity][clang-cfi] LLVM Control Flow Integrity (CFI) provides forward-edge control flow protection. diff --git a/src/doc/rustc-dev-guide/src/stabilization_guide.md b/src/doc/rustc-dev-guide/src/stabilization_guide.md index c4b265ba034f7..19296b22cecf1 100644 --- a/src/doc/rustc-dev-guide/src/stabilization_guide.md +++ b/src/doc/rustc-dev-guide/src/stabilization_guide.md @@ -1,10 +1,12 @@ # Request for stabilization -**NOTE**: This page is about stabilizing *language* features. For stabilizing *library* features, see [Stabilizing a library feature]. +**NOTE**: This page is about stabilizing *language* features. +For stabilizing *library* features, see [Stabilizing a library feature]. [Stabilizing a library feature]: ./stability.md#stabilizing-a-library-feature -Once an unstable feature has been well-tested with no outstanding concerns, anyone may push for its stabilization, though involving the people who have worked on it is prudent. Follow these steps: +Once an unstable feature has been well-tested with no outstanding concerns, anyone may push for its stabilization, though involving the people who have worked on it is prudent. +Follow these steps: ## Write an RFC, if needed @@ -16,16 +18,23 @@ If the feature was part of a [lang experiment], the lang team generally will wan -The feature might be documented in the [`Unstable Book`], located at [`src/doc/unstable-book`]. Remove the page for the feature gate if it exists. Integrate any useful parts of that documentation in other places. +The feature might be documented in the [`Unstable Book`], located at [`src/doc/unstable-book`]. +Remove the page for the feature gate if it exists. +Integrate any useful parts of that documentation in other places. Places that may need updated documentation include: - [The Reference]: This must be updated, in full detail, and a member of the lang-docs team must review and approve the PR before the stabilization can be merged. -- [The Book]: This is updated as needed. If you're not sure, please open an issue on this repository and it can be discussed. -- Standard library documentation: This is updated as needed. Language features often don't need this, but if it's a feature that changes how idiomatic examples are written, such as when `?` was added to the language, updating these in the library documentation is important. Review also the keyword documentation and ABI documentation in the standard library, as these sometimes needs updates for language changes. +- [The Book]: This is updated as needed. + If you're not sure, please open an issue on this repository and it can be discussed. +- Standard library documentation: This is updated as needed. + Language features often don't need this, but if it's a feature that changes how idiomatic examples are written, such as when `?` was added to the language, updating these in the library documentation is important. + Review also the keyword documentation and ABI documentation in the standard library, as these sometimes need updates for language changes. - [Rust by Example]: This is updated as needed. -Prepare PRs to update documentation involving this new feature for the repositories mentioned above. Maintainers of these repositories will keep these PRs open until the whole stabilization process has completed. Meanwhile, we can proceed to the next step. +Prepare PRs to update documentation involving this new feature for the repositories mentioned above. +Maintainers of these repositories will keep these PRs open until the whole stabilization process has completed. +Meanwhile, we can proceed to the next step. ## Write a stabilization report @@ -34,7 +43,8 @@ Author a stabilization report using the [template found in this repository][srt] The stabilization reports summarizes: - The main design decisions and deviations since the RFC was accepted, including both decisions that were FCP'd or otherwise accepted by the language team as well as those being presented to the lang team for the first time. - - Often, the final stabilized language feature has significant design deviations from the original RFC. That's OK, but these deviations must be highlighted and explained carefully. + - Often, the final stabilized language feature has significant design deviations from the original RFC. + That's OK, but these deviations must be highlighted and explained carefully. - The work that has been done since the RFC was accepted, acknowledging the main contributors that helped drive the language feature forward. The [*Stabilization Template*][srt] includes a series of questions that aim to surface connections between this feature and lang's subteams (e.g. types, opsem, lang-docs, etc.) and to identify items that are commonly overlooked. @@ -51,14 +61,19 @@ Before the stabilization will be considered by the lang team, there must be a co ### Updating the feature-gate listing -There is a central listing of unstable feature-gates in [`compiler/rustc_feature/src/unstable.rs`]. Search for the `declare_features!` macro. There should be an entry for the feature you are aiming to stabilize, something like (this example is taken from [rust-lang/rust#32409]: +There is a central listing of unstable feature-gates in [`compiler/rustc_feature/src/unstable.rs`]. +Search for the `declare_features!` macro. +There should be an entry for the feature you are aiming to stabilize, +something like the following (taken from [rust-lang/rust#32409]: ```rust,ignore // pub(restricted) visibilities (RFC 1422) (unstable, pub_restricted, "CURRENT_RUSTC_VERSION", Some(32409)), ``` -The above line should be moved to [`compiler/rustc_feature/src/accepted.rs`]. Entries in the `declare_features!` call are sorted, so find the correct place. When it is done, it should look like: +The above line should be moved to [`compiler/rustc_feature/src/accepted.rs`]. +Entries in the `declare_features!` call are sorted, so find the correct place. +When it is done, it should look like: ```rust,ignore // pub(restricted) visibilities (RFC 1422) @@ -70,19 +85,26 @@ The above line should be moved to [`compiler/rustc_feature/src/accepted.rs`]. En ### Removing existing uses of the feature-gate -Next, search for the feature string (in this case, `pub_restricted`) in the codebase to find where it appears. Change uses of `#![feature(XXX)]` from the `std` and any rustc crates (this includes test folders under `library/` and `compiler/` but not the toplevel `tests/` one) to be `#![cfg_attr(bootstrap, feature(XXX))]`. This includes the feature-gate only for stage0, which is built using the current beta (this is needed because the feature is still unstable in the current beta). +Next, search for the feature string (in this case, `pub_restricted`) in the codebase to find where it appears. +Change uses of `#![feature(XXX)]` from the `std` and any rustc crates +(which includes test folders under `library/` and `compiler/` but not the toplevel `tests/` one) +to be `#![cfg_attr(bootstrap, feature(XXX))]`. +This includes the feature-gate only for stage0, which is built using the current beta (this is needed because the feature is still unstable in the current beta). Also, remove those strings from any tests (e.g. under `tests/`). If there are tests specifically targeting the feature-gate (i.e., testing that the feature-gate is required to use the feature, but nothing else), simply remove the test. ### Do not require the feature-gate to use the feature -Most importantly, remove the code which flags an error if the feature-gate is not present (since the feature is now considered stable). If the feature can be detected because it employs some new syntax, then a common place for that code to be is in `compiler/rustc_ast_passes/src/feature_gate.rs`. For example, you might see code like this: +Most importantly, remove the code which flags an error if the feature-gate is not present (since the feature is now considered stable). +If the feature can be detected because it employs some new syntax, then a common place for that code to be is in `compiler/rustc_ast_passes/src/feature_gate.rs`. +For example, you might see code like this: ```rust,ignore gate_all!(pub_restricted, "`pub(restricted)` syntax is experimental"); ``` -The `gate_all!` macro reports an error if the `pub_restricted` feature is not enabled. It is not needed now that `pub(restricted)` is stable. +The `gate_all!` macro reports an error if the `pub_restricted` feature is not enabled. +It is not needed now that `pub(restricted)` is stable. For more subtle features, you may find code like this: @@ -90,7 +112,9 @@ For more subtle features, you may find code like this: if self.tcx.features().async_fn_in_dyn_trait() { /* XXX */ } ``` -This `pub_restricted` field (named after the feature) would ordinarily be false if the feature flag is not present and true if it is. So transform the code to assume that the field is true. In this case, that would mean removing the `if` and leaving just the `/* XXX */`. +This `pub_restricted` field (named after the feature) would ordinarily be false if the feature flag is not present and true if it is. +So, transform the code to assume that the field is true. +In this case, that would mean removing the `if` and leaving just the `/* XXX */`. ```rust,ignore if self.tcx.sess.features.borrow().pub_restricted { /* XXX */ } @@ -126,7 +150,8 @@ When opening the stabilization PR, CC the lang team and its advisors (`@rust-lan - `@rust-lang/libs-api`, for changes to the standard library API or its guarantees. - `@rust-lang/lang-docs`, for questions about how this should be documented in the Reference. -After the stabilization PR is opened with the stabilization report, wait a bit for any immediate comments. When such comments "simmer down" and you feel the PR is ready for consideration by the lang team, [nominate the PR](https://lang-team.rust-lang.org/how_to/nominate.html) to get it on the agenda for consideration in an upcoming lang meeting. +After the stabilization PR is opened with the stabilization report, wait a bit for any immediate comments. +When such comments "simmer down" and you feel the PR is ready for consideration by the lang team, [nominate the PR](https://lang-team.rust-lang.org/how_to/nominate.html) to get it on the agenda for consideration in an upcoming lang meeting. If you are not a `rust-lang` organization member, you can ask your assigned reviewer to CC the relevant teams on your behalf. @@ -138,7 +163,8 @@ After the lang team and other relevant teams review the stabilization, and after @rfcbot fcp merge ``` -Once enough team members have reviewed, the PR will move into a "final comment period" (FCP). If no new concerns are raised, this period will complete and the PR can be merged after implementation review in the usual way. +Once enough team members have reviewed, the PR will move into a "final comment period" (FCP). +If no new concerns are raised, this period will complete and the PR can be merged after implementation review in the usual way. ## Reviewing and merging stabilizations @@ -151,4 +177,5 @@ On a stabilization, before giving it the `r+`, ensure that the PR: - Has sufficient tests to convincingly demonstrate these things. - Is accompanied by a PR to the Reference than has been reviewed and approved by a member of lang-docs. -In particular, when reviewing the PR, keep an eye out for any user-visible details that the lang team failed to consider and specify. If you find one, describe it and nominate the PR for the lang team. +In particular, when reviewing the PR, keep an eye out for any user-visible details that the lang team failed to consider and specify. +If you find one, describe it and nominate the PR for the lang team. diff --git a/src/doc/rustc-dev-guide/src/tests/adding.md b/src/doc/rustc-dev-guide/src/tests/adding.md index b02d8a0f02077..ebbbb1cfc0d3a 100644 --- a/src/doc/rustc-dev-guide/src/tests/adding.md +++ b/src/doc/rustc-dev-guide/src/tests/adding.md @@ -1,7 +1,7 @@ # Adding new tests **In general, we expect every PR that fixes a bug in rustc to come accompanied -by a regression test of some kind.** This test should fail in master but pass +by a regression test of some kind.** This test should fail in `main` but pass after the PR. These tests are really useful for preventing us from repeating the mistakes of the past. diff --git a/src/doc/rustc-dev-guide/src/tests/ci.md b/src/doc/rustc-dev-guide/src/tests/ci.md index 5b6accec476bf..a30af309a54eb 100644 --- a/src/doc/rustc-dev-guide/src/tests/ci.md +++ b/src/doc/rustc-dev-guide/src/tests/ci.md @@ -1,6 +1,6 @@ # Testing with CI -The primary goal of our CI system is to ensure that the `master` branch of +The primary goal of our CI system is to ensure that the `main` branch of `rust-lang/rust` is always in a valid state by passing our test suite. From a high-level point of view, when you open a pull request at @@ -16,7 +16,7 @@ From a high-level point of view, when you open a pull request at combines multiple PRs together, to reduce CI costs and merge delays. - Once the whole test suite finishes, two things can happen. Either CI fails with an error that needs to be addressed by the developer, or CI succeeds and - the merge commit is then pushed to the `master` branch. + the merge commit is then pushed to the `main` branch. If you want to modify what gets executed on CI, see [Modifying CI jobs](#modifying-ci-jobs). @@ -93,7 +93,7 @@ directly on the PR, in the "CI checks" section at the bottom of the PR page. ### Auto builds -Before a commit can be merged into the `master` branch, it needs to pass our complete test suite. +Before a commit can be merged into the `main` branch, it needs to pass our complete test suite. We call this an `auto` build. This build runs tens of CI jobs that exercise various tests across operating systems and targets. The full test suite is quite slow; @@ -169,10 +169,15 @@ the `@bors jobs=` parameter. The job pattern needs to match one or more jobs defined in the `auto` or `optional` sections of [`jobs.yml`]: -- `auto` jobs are executed before a commit is merged into the `master` branch. +- `auto` jobs are executed before a commit is merged into the `main` branch. - `optional` jobs are executed only when explicitly requested via a try build. They are typically used for tier 2 and tier 3 targets. +One reason to do a try build is to do a perf run, as described above, with `@rust-timer queue`. +This perf build then compares against some commit on main. +With `@bors try parent=` you can base your try build and subsequent perf run on a specific commit on `main`, +to help make the perf comparison as fair as possible. + > **Using `try-job` PR description directives** > > 1. Identify which set of try-jobs you would like to exercise. You can @@ -270,12 +275,12 @@ one or two should be sufficient in most cases. ## Merging PRs serially with bors CI services usually test the last commit of a branch merged with the last commit -in `master`, and while that’s great to check if the feature works in isolation, +in `main`, and while that’s great to check if the feature works in isolation, it doesn’t provide any guarantee the code is going to work once it’s merged. Breakages like these usually happen when another, incompatible PR is merged after the build happened. -To ensure a `master` branch that works all the time, we forbid manual merges. +To ensure a `main` branch that works all the time, we forbid manual merges. Instead, all PRs have to be approved through our bot, [bors] (the software behind it is called [homu]). All the approved PRs are put in a [merge queue] @@ -288,8 +293,8 @@ merge commit it wants to test to specific branches (like `auto` or `try`), which are configured to execute CI checks. Bors then detects the outcome of the build by listening for either Commit Statuses or Check Runs. Since the merge commit is -based on the latest `master` and only one can be tested at the same time, when -the results are green, `master` is fast-forwarded to that merge commit. +based on the latest `main` and only one can be tested at the same time, when +the results are green, `main` is fast-forwarded to that merge commit. Unfortunately, testing a single PR at a time, combined with our long CI (~2 hours for a full run), means we can’t merge a lot of PRs in a single day, and a @@ -359,7 +364,7 @@ caching], with the intermediate artifacts being stored on [ghcr.io]. We also push the built Docker images to ghcr, so that they can be reused by other tools (rustup) or by developers running the Docker build locally (to speed up their build). -Since we test multiple, diverged branches (`master`, `beta` and `stable`), we +Since we test multiple, diverged branches (`main`, `beta` and `stable`), we can’t rely on a single cache for the images, otherwise builds on a branch would override the cache for the others. Instead, we store the images under different