From e15fcfb0b868501e7698c41c621f5a5d64ed19d3 Mon Sep 17 00:00:00 2001 From: Camelid Date: Sat, 23 Jan 2021 13:38:22 -0800 Subject: [PATCH 1/2] Implement date-checker This tool looks for HTML comments like `` in each Markdown source file and compiles a list of dates that are older than six months. It then opens an issue with that list, with checkboxes for each file and date. Note that it will only open an issue if there was at least one date older than six months; it does nothing if the list is empty. This tool is automatically run monthly in a GitHub Actions workflow. I have tested the tool on a private repo and confirmed that it works. --- .github/workflows/date-check.yml | 44 ++++++ .gitignore | 4 +- ci/date-check/Cargo.lock | 147 +++++++++++++++++++ ci/date-check/Cargo.toml | 12 ++ ci/date-check/src/main.rs | 236 +++++++++++++++++++++++++++++++ 5 files changed, 442 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/date-check.yml create mode 100644 ci/date-check/Cargo.lock create mode 100644 ci/date-check/Cargo.toml create mode 100644 ci/date-check/src/main.rs diff --git a/.github/workflows/date-check.yml b/.github/workflows/date-check.yml new file mode 100644 index 000000000..411117235 --- /dev/null +++ b/.github/workflows/date-check.yml @@ -0,0 +1,44 @@ +name: Date-Check + +on: + schedule: + # Run at noon UTC every 1st of the month + - cron: '00 12 01 * *' + + # Allow manually starting the workflow + workflow_dispatch: + +jobs: + date-check: + runs-on: ubuntu-latest + + steps: + - name: Checkout repo + uses: actions/checkout@v2 + + - name: Run `date-check` + working-directory: ci/date-check + run: | + cargo run -- ../../src/ > ../../date-check-output.txt + + - name: Open issue + uses: actions/github-script@v3 + with: + github-token: ${{secrets.GITHUB_TOKEN}} + script: | + const fs = require('fs'); + + const rawText = fs.readFileSync('date-check-output.txt', { encoding: 'utf8' }); + const title = rawText.split('\n')[0]; + if (title != 'empty') { + const body = rawText.split('\n').slice(1).join('\n'); + github.issues.create({ + owner: context.repo.owner, + repo: context.repo.repo, + title, + body, + }); + console.log('Opened issue.'); + } else { + console.log('No dates to triage.'); + } diff --git a/.gitignore b/.gitignore index b8cb34883..2901de5ed 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,6 @@ book -# prevent accidentally changes +# prevent accidental changes book.toml + +ci/date-check/target/ diff --git a/ci/date-check/Cargo.lock b/ci/date-check/Cargo.lock new file mode 100644 index 000000000..296a132d4 --- /dev/null +++ b/ci/date-check/Cargo.lock @@ -0,0 +1,147 @@ +# This file is automatically @generated by Cargo. +# It is not intended for manual editing. +[[package]] +name = "aho-corasick" +version = "0.7.15" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "7404febffaa47dac81aa44dba71523c9d069b1bdc50a77db41195149e17f68e5" +dependencies = [ + "memchr", +] + +[[package]] +name = "autocfg" +version = "1.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cdb031dd78e28731d87d56cc8ffef4a8f36ca26c38fe2de700543e627f8a464a" + +[[package]] +name = "chrono" +version = "0.4.19" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "670ad68c9088c2a963aaa298cb369688cf3f9465ce5e2d4ca10e6e0098a1ce73" +dependencies = [ + "libc", + "num-integer", + "num-traits", + "time", + "winapi", +] + +[[package]] +name = "date-check" +version = "0.1.0" +dependencies = [ + "chrono", + "glob", + "regex", +] + +[[package]] +name = "glob" +version = "0.3.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9b919933a397b79c37e33b77bb2aa3dc8eb6e165ad809e58ff75bc7db2e34574" + +[[package]] +name = "lazy_static" +version = "1.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e2abad23fbc42b3700f2f279844dc832adb2b2eb069b2df918f455c4e18cc646" + +[[package]] +name = "libc" +version = "0.2.82" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "89203f3fba0a3795506acaad8ebce3c80c0af93f994d5a1d7a0b1eeb23271929" + +[[package]] +name = "memchr" +version = "2.3.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0ee1c47aaa256ecabcaea351eae4a9b01ef39ed810004e298d2511ed284b1525" + +[[package]] +name = "num-integer" +version = "0.1.44" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d2cc698a63b549a70bc047073d2949cce27cd1c7b0a4a862d08a8031bc2801db" +dependencies = [ + "autocfg", + "num-traits", +] + +[[package]] +name = "num-traits" +version = "0.2.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9a64b1ec5cda2586e284722486d802acf1f7dbdc623e2bfc57e65ca1cd099290" +dependencies = [ + "autocfg", +] + +[[package]] +name = "regex" +version = "1.4.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "d9251239e129e16308e70d853559389de218ac275b515068abc96829d05b948a" +dependencies = [ + "aho-corasick", + "memchr", + "regex-syntax", + "thread_local", +] + +[[package]] +name = "regex-syntax" +version = "0.6.22" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "b5eb417147ba9860a96cfe72a0b93bf88fee1744b5636ec99ab20c1aa9376581" + +[[package]] +name = "thread_local" +version = "1.1.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "bb9bc092d0d51e76b2b19d9d85534ffc9ec2db959a2523cdae0697e2972cd447" +dependencies = [ + "lazy_static", +] + +[[package]] +name = "time" +version = "0.1.44" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "6db9e6914ab8b1ae1c260a4ae7a49b6c5611b40328a735b21862567685e73255" +dependencies = [ + "libc", + "wasi", + "winapi", +] + +[[package]] +name = "wasi" +version = "0.10.0+wasi-snapshot-preview1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1a143597ca7c7793eff794def352d41792a93c481eb1042423ff7ff72ba2c31f" + +[[package]] +name = "winapi" +version = "0.3.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419" +dependencies = [ + "winapi-i686-pc-windows-gnu", + "winapi-x86_64-pc-windows-gnu", +] + +[[package]] +name = "winapi-i686-pc-windows-gnu" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6" + +[[package]] +name = "winapi-x86_64-pc-windows-gnu" +version = "0.4.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f" diff --git a/ci/date-check/Cargo.toml b/ci/date-check/Cargo.toml new file mode 100644 index 000000000..95251fb12 --- /dev/null +++ b/ci/date-check/Cargo.toml @@ -0,0 +1,12 @@ +[package] +name = "date-check" +version = "0.1.0" +authors = ["Camelid "] +edition = "2018" + +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html + +[dependencies] +glob = "0.3" +regex = "1" +chrono = "0.4" diff --git a/ci/date-check/src/main.rs b/ci/date-check/src/main.rs new file mode 100644 index 000000000..d78b430b5 --- /dev/null +++ b/ci/date-check/src/main.rs @@ -0,0 +1,236 @@ +use std::{ + collections::BTreeMap, + convert::TryInto as _, + env, fmt, fs, + path::{Path, PathBuf}, +}; + +use chrono::{Datelike as _, TimeZone as _, Utc}; +use glob::glob; +use regex::Regex; + +#[derive(Debug, Copy, Clone, PartialEq, Eq)] +struct Date { + year: u32, + month: u32, +} + +impl Date { + fn months_since(self, other: Date) -> Option { + let self_chrono = Utc.ymd(self.year.try_into().unwrap(), self.month, 1); + let other_chrono = Utc.ymd(other.year.try_into().unwrap(), other.month, 1); + let duration_since = self_chrono.signed_duration_since(other_chrono); + let months_since = duration_since.num_days() / 30; + if months_since < 0 { + None + } else { + Some(months_since.try_into().unwrap()) + } + } +} + +impl fmt::Display for Date { + fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { + write!(f, "{:04}-{:02}", self.year, self.month) + } +} + +fn make_date_regex() -> Regex { + Regex::new( + r"(?x) # insignificant whitespace mode + ", + ) + .unwrap() +} + +fn collect_dates_from_file(date_regex: &Regex, text: &str) -> Vec<(usize, Date)> { + let mut line = 1; + let mut end_of_last_cap = 0; + date_regex + .captures_iter(&text) + .map(|cap| { + ( + cap.get(0).unwrap().range(), + Date { + year: cap["y"].parse().unwrap(), + month: cap["m"].parse().unwrap(), + }, + ) + }) + .map(|(byte_range, date)| { + line += text[end_of_last_cap..byte_range.end] + .chars() + .filter(|c| *c == '\n') + .count(); + end_of_last_cap = byte_range.end; + (line, date) + }) + .collect() +} + +fn collect_dates(paths: impl Iterator) -> BTreeMap> { + let date_regex = make_date_regex(); + let mut data = BTreeMap::new(); + for path in paths { + let text = fs::read_to_string(&path).unwrap(); + let dates = collect_dates_from_file(&date_regex, &text); + if !dates.is_empty() { + data.insert(path, dates); + } + } + data +} + +fn filter_dates( + current_month: Date, + min_months_since: u32, + dates_by_file: impl Iterator)>, +) -> impl Iterator)> { + dates_by_file + .map(move |(path, dates)| { + ( + path, + dates + .into_iter() + .filter(|(_, date)| { + current_month + .months_since(*date) + .expect("found date that is after current month") + >= min_months_since + }) + .collect::>(), + ) + }) + .filter(|(_, dates)| !dates.is_empty()) +} + +fn main() { + let root_dir = env::args() + .nth(1) + .expect("expect root Markdown directory as CLI argument"); + let root_dir_path = Path::new(&root_dir); + let glob_pat = format!("{}/**/*.md", root_dir); + let today_chrono = Utc::today(); + let current_month = Date { + year: today_chrono.year_ce().1, + month: today_chrono.month(), + }; + + let dates_by_file = collect_dates(glob(&glob_pat).unwrap().map(Result::unwrap)); + let dates_by_file: BTreeMap<_, _> = + filter_dates(current_month, 6, dates_by_file.into_iter()).collect(); + + if dates_by_file.is_empty() { + println!("empty"); + } else { + println!("Date Reference Triage for {}", current_month); + println!("## Procedure"); + println!(); + println!( + "Each of these dates should be checked to see if the docs they annotate are \ + up-to-date. Each date should be updated (in the Markdown file where it appears) to \ + use the current month ({current_month}), or removed if the docs it annotates are not \ + expected to fall out of date quickly.", + current_month = current_month + ); + println!(); + println!( + "Please check off each date once a PR to update it (and, if applicable, its \ + surrounding docs) has been merged. Please also mention that you are working on a \ + particular set of dates so duplicate work is avoided." + ); + println!(); + println!("Finally, once all the dates have been updated, please close this issue."); + println!(); + println!("## Dates"); + println!(); + + for (path, dates) in dates_by_file { + println!( + "- [ ] {}", + path.strip_prefix(&root_dir_path).unwrap().display() + ); + for (line, date) in dates { + println!(" - [ ] line {}: {}", line, date); + } + } + println!(); + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn test_months_since() { + let date1 = Date { + year: 2020, + month: 3, + }; + let date2 = Date { + year: 2021, + month: 1, + }; + assert_eq!(date2.months_since(date1), Some(10)); + } + + #[test] + fn test_date_regex() { + let regex = make_date_regex(); + assert!(regex.is_match("foo bar")); + } + + #[test] + fn test_collect_dates_from_file() { + let text = "Test1\n\nTest2\nFoo\nTest3\nTest4\nFooBar\n\nTest5\nTest6\nTest7\n\nTest8 + "; + assert_eq!( + collect_dates_from_file(&make_date_regex(), text), + vec![ + ( + 2, + Date { + year: 2021, + month: 1, + } + ), + ( + 4, + Date { + year: 2021, + month: 2, + } + ), + ( + 7, + Date { + year: 2021, + month: 3, + } + ), + ( + 8, + Date { + year: 2021, + month: 4, + } + ), + ( + 14, + Date { + year: 2021, + month: 5, + } + ), + ] + ); + } +} From 23b025aaab3e26672d9a085754d95dc490cc2f3e Mon Sep 17 00:00:00 2001 From: Camelid Date: Wed, 20 Jan 2021 16:42:10 -0800 Subject: [PATCH 2/2] Add lots of date-check annotations Also added dates for things that previously said "as of now" or "as of this writing" and cleaned up a couple of things along the way. --- src/backend/backend-agnostic.md | 5 +++-- .../region_inference/member_constraints.md | 16 +++++++--------- src/compiler-src.md | 11 ++++++----- src/contributing.md | 6 +++++- src/diagnostics.md | 6 +++--- src/diagnostics/lintstore.md | 7 ++++--- src/git.md | 12 ++++++------ src/llvm-coverage-instrumentation.md | 19 +++++++++---------- src/miri.md | 13 +++++++------ src/opaque-types-type-alias-impl-trait.md | 5 +++-- src/overview.md | 12 ++++++------ src/parallel-rustc.md | 11 ++++++----- src/profiling.md | 8 ++++---- src/queries/profiling.md | 4 ++-- .../query-evaluation-model-in-detail.md | 9 +++++---- src/query.md | 17 ++++++++--------- src/rustdoc-internals.md | 2 +- src/salsa.md | 8 ++++---- src/tests/adding.md | 14 +++++++------- src/tests/intro.md | 14 +++++++------- src/the-parser.md | 4 ++-- src/traits/chalk.md | 13 ++++++------- src/traits/resolution.md | 10 +++++----- src/type-inference.md | 4 ++-- 24 files changed, 118 insertions(+), 112 deletions(-) diff --git a/src/backend/backend-agnostic.md b/src/backend/backend-agnostic.md index 52532c258..f61bf62b3 100644 --- a/src/backend/backend-agnostic.md +++ b/src/backend/backend-agnostic.md @@ -2,8 +2,9 @@ -As of January 2021, `rustc_codegen_ssa` provides an abstract interface for all backends to -implement, to allow other codegen backends (e.g. [Cranelift]). +As of January 2021 , `rustc_codegen_ssa` provides an +abstract interface for all backends to implement, to allow other codegen +backends (e.g. [Cranelift]). [Cranelift]: https://github.com/bytecodealliance/wasmtime/tree/HEAD/cranelift diff --git a/src/borrow_check/region_inference/member_constraints.md b/src/borrow_check/region_inference/member_constraints.md index fd65acf1a..f64e39461 100644 --- a/src/borrow_check/region_inference/member_constraints.md +++ b/src/borrow_check/region_inference/member_constraints.md @@ -93,15 +93,13 @@ member constraints come in. ## Choices are always lifetime parameters -At present, the "choice" regions from a member constraint are always -lifetime parameters from the current function. As of January 2021, -this falls out from the placement of impl Trait, though in the future -it may not be the case. -We take some advantage of this fact, as it simplifies the current -code. In particular, we don't have to consider a case like `'0 member -of ['1, 'static]`, in which the value of both `'0` and `'1` are being -inferred and hence changing. See [rust-lang/rust#61773][#61773] for more -information. +At present, the "choice" regions from a member constraint are always lifetime +parameters from the current function. As of January 2021 , +this falls out from the placement of impl Trait, though in the future it may not +be the case. We take some advantage of this fact, as it simplifies the current +code. In particular, we don't have to consider a case like `'0 member of ['1, +'static]`, in which the value of both `'0` and `'1` are being inferred and hence +changing. See [rust-lang/rust#61773][#61773] for more information. [#61773]: https://github.com/rust-lang/rust/issues/61773 diff --git a/src/compiler-src.md b/src/compiler-src.md index 5965fd374..153bb1a3f 100644 --- a/src/compiler-src.md +++ b/src/compiler-src.md @@ -7,8 +7,9 @@ > top-level directory has separate directories for the compiler, build-system, > std libs, etc, rather than one huge `src/` directory. > -> As of January 2021, the std libs have been moved to `library/` and the crates -> that make up the `rustc` compiler itself have been moved to `compiler/` +> As of January 2021 , the standard libraries have been +> moved to `library/` and the crates that make up the `rustc` compiler itself +> have been moved to `compiler/`. Now that we have [seen what the compiler does](./overview.md), let's take a look at the structure of the contents of the rust-lang/rust repo. @@ -20,9 +21,9 @@ containing the compiler, the standard libraries (`core`, `alloc`, `std`, `proc_macro`, etc), and `rustdoc`, along with the build system and a bunch of tools and submodules for building a full Rust distribution. -As of this writing, this structure is gradually undergoing some transformation -to make it a bit less monolithic and more approachable, especially to -newcomers. +As of August 2020 , this structure is gradually undergoing +some transformation to make it a bit less monolithic and more approachable, +especially to newcomers. The repository consists of three main directories: diff --git a/src/contributing.md b/src/contributing.md index 83d5e95cb..fbcd2001a 100644 --- a/src/contributing.md +++ b/src/contributing.md @@ -410,9 +410,13 @@ Just a few things to keep in mind: Aim to provide a reasonable amount of context, possibly including but not limited to: - A reason for why the data may be out of date other than "change", as change is a constant across the project. - - A date the comment was added, e.g. instead of writing _"Currently, ..."_ consider writing + - The date the comment was added, e.g. instead of writing _"Currently, ..."_ + or _"As of now, ..."_, consider writing _"As of January 2021, ..."_. Try to format the date as ` ` to ease search. + - Additionally, include a machine-readable comment of the form `` (if the current month is January 2021). We have an automated + tool that uses these (in `ci/date-check`). - A link to a relevant WG, tracking issue, `rustc` rustdoc page, or similar, that may provide further explanation for the change process or a way to verify that the information is not outdated. diff --git a/src/diagnostics.md b/src/diagnostics.md index f59844d4c..6a447c00d 100644 --- a/src/diagnostics.md +++ b/src/diagnostics.md @@ -594,9 +594,9 @@ declare_lint! { } ``` -If you need a combination of options that's not supported by the -`declare_lint!` macro, you can always define your own static with a type of -`&Lint` but this is (as of January 2021) linted against in the compiler tree. +If you need a combination of options that's not supported by the `declare_lint!` +macro, you can always define your own static with a type of `&Lint` but this is +(as of January 2021 ) linted against in the compiler tree. #### Guidelines for creating a future incompatibility lint diff --git a/src/diagnostics/lintstore.md b/src/diagnostics/lintstore.md index e088185a7..d6fdd1e34 100644 --- a/src/diagnostics/lintstore.md +++ b/src/diagnostics/lintstore.md @@ -17,9 +17,10 @@ First, we have the lint declarations themselves: this is where the name and defa other metadata come from. These are normally defined by way of the [`declare_lint!`] macro, which boils down to a static with type `&rustc_session::lint::Lint`. -As of January 2021, we lint against direct declarations without the use of the macro today -(although this may change in the future, as the macro is somewhat unwieldy to add new fields to, -like all macros by example). +As of January 2021 , we lint against direct declarations +without the use of the macro today (although this may change in the future, as +the macro is somewhat unwieldy to add new fields to, like all macros by +example). Lint declarations don't carry any "state" - they are merely global identifers and descriptions of lints. We assert at runtime that they are not registered twice (by lint name). diff --git a/src/git.md b/src/git.md index 611c47124..69cdba839 100644 --- a/src/git.md +++ b/src/git.md @@ -144,12 +144,12 @@ Changes not staged for commit: no changes added to commit (use "git add" and/or "git commit -a") ``` -These changes are not changes to files: they are changes to submodules -(more on this [later](#git-submodules)). To get rid of those, run `git submodule update` (or run any -`x.py` command, which will automatically update the submodules). -Note that there is (as of January 2021) a bug if you use worktrees, submodules, and x.py in a commit -hook. -If you run into an error like: +These changes are not changes to files: they are changes to submodules (more on +this [later](#git-submodules)). To get rid of those, run `git submodule update` +(or run any `x.py` command, which will automatically update the submodules). +Note that there is (as of January 2021 ) a bug if you use +worktrees, submodules, and x.py in a commit hook. If you run into an error +like: ``` error: failed to read `/home/joshua/rustc-worktree/src/tools/miri/cargo-miri/Cargo.toml` diff --git a/src/llvm-coverage-instrumentation.md b/src/llvm-coverage-instrumentation.md index 88831f69d..9a78935e4 100644 --- a/src/llvm-coverage-instrumentation.md +++ b/src/llvm-coverage-instrumentation.md @@ -221,16 +221,15 @@ properly-configured variables in LLVM IR, according to very specific details of the [_LLVM Coverage Mapping Format_][coverage-mapping-format] (Version 4).[^llvm-and-covmap-versions] -[^llvm-and-covmap-versions]: The Rust compiler (as of January 2021) supports -_LLVM Coverage Mapping Format_ Version 4 (the most up-to-date version -of the format, at the time of this writing) for improved compatibility -with other LLVM-based compilers (like _Clang_), and to take advantage -of some format optimizations. Version 4 was introduced in _LLVM 11_, -which is currently the default LLVM version for Rust. Note that the -Rust compiler optionally supports some earlier LLVM versions, -prior to _LLVM 11_. If `rustc` is configured to use an incompatible -version of LLVM, compiling with `-Z instrument-coverage` will -generate an error message. +[^llvm-and-covmap-versions]: The Rust compiler (as of January 2021 ) supports _LLVM Coverage Mapping Format_ Version 4 (the most +up-to-date version of the format, at the time of this writing) for improved +compatibility with other LLVM-based compilers (like _Clang_), and to take +advantage of some format optimizations. Version 4 was introduced in _LLVM 11_, +which is currently the default LLVM version for Rust. Note that the Rust +compiler optionally supports some earlier LLVM versions, prior to _LLVM 11_. If +`rustc` is configured to use an incompatible version of LLVM, compiling with `-Z +instrument-coverage` will generate an error message. ```rust pub fn finalize<'ll, 'tcx>(cx: &CodegenCx<'ll, 'tcx>) { diff --git a/src/miri.md b/src/miri.md index d0766a07b..54f96391a 100644 --- a/src/miri.md +++ b/src/miri.md @@ -193,12 +193,13 @@ concrete integer. However, a variable of pointer or reference *type*, such as `*const T` or `&T`, does not have to have a pointer *value*: it could be obtaining by casting or -transmuting an integer to a pointer (as of January 2021 that is hard to do in const eval, -but eventually `transmute` will be stable as a `const fn`). And similarly, when -casting or transmuting a reference to some actual allocation to an integer, we -end up with a pointer *value* (`Scalar::Ptr`) at integer *type* (`usize`). This -is a problem because we cannot meaningfully perform integer operations such as -division on pointer values. +transmuting an integer to a pointer (as of January 2021 +that is hard to do in const eval, but eventually `transmute` will be stable as a +`const fn`). And similarly, when casting or transmuting a reference to some +actual allocation to an integer, we end up with a pointer *value* +(`Scalar::Ptr`) at integer *type* (`usize`). This is a problem because we +cannot meaningfully perform integer operations such as division on pointer +values. ## Interpretation diff --git a/src/opaque-types-type-alias-impl-trait.md b/src/opaque-types-type-alias-impl-trait.md index e95291fef..53522114d 100644 --- a/src/opaque-types-type-alias-impl-trait.md +++ b/src/opaque-types-type-alias-impl-trait.md @@ -14,8 +14,9 @@ This declares an opaque type named `Foo`, of which the only information is that it implements `Bar`. Therefore, any of `Bar`'s interface can be used on a `Foo`, but nothing else (regardless of whether it implements any other traits). -Since there needs to be a concrete background type, you can (as of January 2021) -express that type by using the opaque type in a "defining use site". +Since there needs to be a concrete background type, you can (as of January 2021 +) express that type by using the opaque type in a +"defining use site". ```rust,ignore struct Struct; diff --git a/src/overview.md b/src/overview.md index 5a63d6066..45ae0ab2e 100644 --- a/src/overview.md +++ b/src/overview.md @@ -247,12 +247,12 @@ to remain to ensure that unreachable functions still have their errors emitted. [passes]: https://github.com/rust-lang/rust/blob/45ebd5808afd3df7ba842797c0fcd4447ddf30fb/src/librustc_interface/passes.rs#L824 Moreover, the compiler wasn't originally built to use a query system; the query -system has been retrofitted into the compiler, so parts of it are not -query-fied yet. Also, LLVM isn't our code, so that isn't querified -either. The plan is to eventually query-fy all of the steps listed in the -previous section, but as of this writing, only the steps between HIR and -LLVM-IR are query-fied. That is, lexing and parsing are done all at once for -the whole program. +system has been retrofitted into the compiler, so parts of it are not query-fied +yet. Also, LLVM isn't our code, so that isn't querified either. The plan is to +eventually query-fy all of the steps listed in the previous section, but as of +April 2020 , only the steps between HIR and LLVM-IR are +query-fied. That is, lexing and parsing are done all at once for the whole +program. One other thing to mention here is the all-important "typing context", [`TyCtxt`], which is a giant struct that is at the center of all things. diff --git a/src/parallel-rustc.md b/src/parallel-rustc.md index cb36fef6f..6f7f6f54b 100644 --- a/src/parallel-rustc.md +++ b/src/parallel-rustc.md @@ -3,8 +3,9 @@ Most of the compiler is not parallel. This represents an opportunity for improving compiler performance. -As of January 2021, work on explicitly parallelizing the compiler has stalled. -There is a lot of design and correctness work that needs to be done. +As of January 2021 , work on explicitly parallelizing the +compiler has stalled. There is a lot of design and correctness work that needs +to be done. One can try out the current parallel compiler work by enabling it in the `config.toml`. @@ -21,9 +22,9 @@ There are a few basic ideas in this effort: [`rayon`]: https://crates.io/crates/rayon -As of this writing, much of this effort is on hold due to lack of manpower. We -have a working prototype with promising performance gains in many cases. -However, there are two blockers: +As of May 2020 , much of this effort is on hold due to +lack of manpower. We have a working prototype with promising performance gains +in many cases. However, there are two blockers: - It's not clear what invariants need to be upheld that might not hold in the face of concurrency. An auditing effort was underway, but seems to have diff --git a/src/profiling.md b/src/profiling.md index 902281f18..aa8bf27a2 100644 --- a/src/profiling.md +++ b/src/profiling.md @@ -88,7 +88,7 @@ codegen-units = 0 # num_cpus The llvm-lines output is affected by several options. `optimize = false` increases it from 2.1GB to 3.5GB and `codegen-units = 0` to 4.1GB. -MIR optimizations have little impact. Compared to the default `RUSTFLAGS="-Z mir-opt-level=1"`, -level 0 adds 0.3GB and level 2 removes 0.2GB. -As of January 2021, inlining currently only happens in LLVM but this might change in the future. - +MIR optimizations have little impact. Compared to the default `RUSTFLAGS="-Z +mir-opt-level=1"`, level 0 adds 0.3GB and level 2 removes 0.2GB. As of January +2021 , inlining currently only happens in LLVM but this +might change in the future. diff --git a/src/queries/profiling.md b/src/queries/profiling.md index 8cd4c07d8..d903eabff 100644 --- a/src/queries/profiling.md +++ b/src/queries/profiling.md @@ -89,8 +89,8 @@ The trace of the queries has a formal structure; see We style this formal structure as follows: - **Timed passes:** Green boxes, when present (via `-Z time-passes`), represent - _timed passes_ in the compiler. As of January 2021 these passes are not queries, but may be - replaced by queries in future versions. + _timed passes_ in the compiler. As of January 2021 + these passes are not queries, but may be replaced by queries in future versions. - **Labels:** Some green and red boxes are labeled with text. Where they are present, the labels give the following information: - The [query's _provider_](#queries), sans its _key_ and its _result_, which diff --git a/src/queries/query-evaluation-model-in-detail.md b/src/queries/query-evaluation-model-in-detail.md index 51501d3d5..eb6659420 100644 --- a/src/queries/query-evaluation-model-in-detail.md +++ b/src/queries/query-evaluation-model-in-detail.md @@ -76,10 +76,11 @@ executed, no results are cached. But the context already provides access to "input" data, i.e. pieces of immutable data that were computed before the context was created and that queries can access to do their computations. -As of January 2021, this input data consists mainly of the HIR map, upstream crate metadata, and the -command-line options the compiler was invoked with; but in the future inputs will just consist of -command-line options and a list of source files -- the HIR map will itself be provided by a query -which processes these source files. +As of January 2021 , this input data consists mainly of +the HIR map, upstream crate metadata, and the command-line options the compiler +was invoked with; but in the future inputs will just consist of command-line +options and a list of source files -- the HIR map will itself be provided by a +query which processes these source files. Without inputs, queries would live in a void without anything to compute their result from (remember, query providers only have access to other queries and diff --git a/src/query.md b/src/query.md index eb0bbe78e..b03aaa8b4 100644 --- a/src/query.md +++ b/src/query.md @@ -1,16 +1,15 @@ # Queries: demand-driven compilation -As described in [the high-level overview of the compiler][hl], the -Rust compiler is still (as of January 2021) transitioning from a traditional "pass-based" -setup to a "demand-driven" system. **The Compiler Query System is the -key to our new demand-driven organization.** The idea is pretty -simple. You have various queries that compute things about the input -– for example, there is a query called `type_of(def_id)` that, given -the [def-id] of some item, will compute the type of that item and return -it to you. +As described in [the high-level overview of the compiler][hl], the Rust compiler +is still (as of January 2021 ) transitioning from a +traditional "pass-based" setup to a "demand-driven" system. **The Compiler Query +System is the key to our new demand-driven organization.** The idea is pretty +simple. You have various queries that compute things about the input – for +example, there is a query called `type_of(def_id)` that, given the [def-id] of +some item, will compute the type of that item and return it to you. [def-id]: appendix/glossary.md#def-id -[hl]: compiler-src.html +[hl]: ./compiler-src.md Query execution is **memoized** – so the first time you invoke a query, it will go do the computation, but the next time, the result is diff --git a/src/rustdoc-internals.md b/src/rustdoc-internals.md index 288d762b8..7460c012c 100644 --- a/src/rustdoc-internals.md +++ b/src/rustdoc-internals.md @@ -66,7 +66,7 @@ these passes, please let us know!) [44136]: https://github.com/rust-lang/rust/issues/44136 -Here is current (as of this writing) list of passes: +Here is the list of passes as of March 2018 : - `propagate-doc-cfg` - propagates `#[doc(cfg(...))]` to child items. - `collapse-docs` concatenates all document attributes into one document diff --git a/src/salsa.md b/src/salsa.md index 38db066c5..67d813b28 100644 --- a/src/salsa.md +++ b/src/salsa.md @@ -9,10 +9,10 @@ want to watch [Salsa In More Depth](https://www.youtube.com/watch?v=i_IhACacPRY), also by Niko Matsakis. -> As of January 2021, although Salsa is inspired by (among other things) rustc's query system, -> it is not used directly in rustc. -> It _is_ used in chalk and extensively in `rust-analyzer`, but there are no medium or long-term -> concrete plans to integrate it into the compiler. +> As of January 2021 , although Salsa is inspired by +> (among other things) rustc's query system, it is not used directly in rustc. +> It _is_ used in chalk and extensively in `rust-analyzer`, but there are no +> medium or long-term concrete plans to integrate it into the compiler. ## What is Salsa? diff --git a/src/tests/adding.md b/src/tests/adding.md index 868bad2d7..c19271d2c 100644 --- a/src/tests/adding.md +++ b/src/tests/adding.md @@ -333,17 +333,17 @@ The error levels that you can have are: 1. `ERROR` 2. `WARNING` 3. `NOTE` -4. `HELP` and `SUGGESTION`* +4. `HELP` and `SUGGESTION`[^sugg-placement] -\* **Note**: `SUGGESTION` must follow immediately after `HELP`. +[^sugg-placement]: **Note**: `SUGGESTION` must follow immediately after `HELP`. ## Revisions -Certain classes of tests support "revisions" (as of the time of this -writing, this includes compile-fail, run-fail, and -incremental, though incremental tests are somewhat -different). Revisions allow a single test file to be used for multiple -tests. This is done by adding a special header at the top of the file: +Certain classes of tests support "revisions" (as of February 2018 , this includes compile-fail, run-fail, and incremental, though +incremental tests are somewhat different). Revisions allow a single test file to +be used for multiple tests. This is done by adding a special header at the top +of the file: ```rust // revisions: foo bar baz diff --git a/src/tests/intro.md b/src/tests/intro.md index cab06df55..ffc3b5a1d 100644 --- a/src/tests/intro.md +++ b/src/tests/intro.md @@ -123,13 +123,13 @@ launch a build that will run all tests on some configurations (x86_64-gnu-llvm-8 linux. x86_64-gnu-tools linux, mingw-check linux). In essence, it runs `./x.py test` after building for each of them. -The integration bot [bors] is used for coordinating merges to the master -branch. When a PR is approved, it goes into a [queue] where merges are tested -one at a time on a wide set of platforms using GitHub Actions (as of January 2021 over -50 different configurations). Due to the limit on the number of parallel jobs, -we run CI under the [rust-lang-ci] organization except for PRs. -Most platforms only run the build steps, some run a restricted set of tests, -only a subset run the full suite of tests (see Rust's [platform tiers]). +The integration bot [bors] is used for coordinating merges to the master branch. +When a PR is approved, it goes into a [queue] where merges are tested one at a +time on a wide set of platforms using GitHub Actions (as of January 2021 , over 50 different configurations). Due to the limit on the +number of parallel jobs, we run CI under the [rust-lang-ci] organization except +for PRs. Most platforms only run the build steps, some run a restricted set of +tests, only a subset run the full suite of tests (see Rust's [platform tiers]). [GitHub Actions]: https://github.com/rust-lang/rust/actions [rust-lang-ci]: https://github.com/rust-lang-ci/rust/actions diff --git a/src/the-parser.md b/src/the-parser.md index 915e4bb9a..9c3433884 100644 --- a/src/the-parser.md +++ b/src/the-parser.md @@ -1,7 +1,7 @@ # Lexing and Parsing -As of January 2021, the lexer and parser are undergoing refactoring to allow -extracting them into libraries. +As of January 2021 , the lexer and parser are undergoing +refactoring to allow extracting them into libraries. The very first thing the compiler does is take the program (in Unicode characters) and turn it into something the compiler can work with more diff --git a/src/traits/chalk.md b/src/traits/chalk.md index 540077cf0..8b2e20304 100644 --- a/src/traits/chalk.md +++ b/src/traits/chalk.md @@ -1,12 +1,11 @@ # Chalk-based trait solving -[Chalk][chalk] is an experimental trait solver for rust that is (as of January 2021) -under development by the [Traits Working Group][wg]. Its goal is -to enable a lot of trait system features and bug fixes that are -hard to implement (e.g. GATs or specialization). If you -would like to help in hacking on the new solver, you will find -instructions for getting involved in the -[Traits Working Group tracking issue][wg]. +[Chalk][chalk] is an experimental trait solver for Rust that is (as of January +2021 ) under development by the [Traits Working +Group][wg]. Its goal is to enable a lot of trait system features and bug fixes +that are hard to implement (e.g. GATs or specialization). If you would like to +help in hacking on the new solver, you will find instructions for getting +involved in the [Traits Working Group tracking issue][wg]. [wg]: https://github.com/rust-lang/rust/issues/48416 diff --git a/src/traits/resolution.md b/src/traits/resolution.md index 863631320..f2ffdcc97 100644 --- a/src/traits/resolution.md +++ b/src/traits/resolution.md @@ -118,11 +118,11 @@ candidate that is definitively applicable. In some cases, we may not know whether an impl/where-clause applies or not – this occurs when the obligation contains unbound inference variables. -The subroutines that decide whether a particular impl/where-clause/etc -applies to a particular obligation are collectively referred to as the -process of _matching_. As of January 2021, this amounts to -unifying the `Self` types, but in the future we may also recursively -consider some of the nested obligations, in the case of an impl. +The subroutines that decide whether a particular impl/where-clause/etc applies +to a particular obligation are collectively referred to as the process of +_matching_. As of January 2021 , this amounts to unifying +the `Self` types, but in the future we may also recursively consider some of the +nested obligations, in the case of an impl. **TODO**: what does "unifying the `Self` types" mean? The `Self` of the obligation with that of an impl? diff --git a/src/type-inference.md b/src/type-inference.md index 9d23b6278..6496b48ff 100644 --- a/src/type-inference.md +++ b/src/type-inference.md @@ -71,8 +71,8 @@ inference works, or perhaps this blog post on [Unification in the Chalk project]: http://smallcultfollowing.com/babysteps/blog/2017/03/25/unification-in-chalk-part-1/ -All told, the inference context stores four kinds of inference variables as of -this writing: +All told, the inference context stores four kinds of inference variables (as of +January 2018 ): - Type variables, which come in three varieties: - General type variables (the most common). These can be unified with any