Document not found (404)
+This URL is invalid, sorry. Please use the navigation bar or search to continue.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/coherence.html b/coherence.html
new file mode 100644
index 000000000..fc2bfec01
--- /dev/null
+++ b/coherence.html
@@ -0,0 +1,272 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Closure Capture Inference
+This section describes how rustc handles closures. Closures in Rust are
+effectively "desugared" into structs that contain the values they use (or
+references to the values they use) from their creator's stack frame. rustc has
+the job of figuring out which values a closure uses and how, so it can decide
+whether to capture a given variable by shared reference, mutable reference, or
+by move. rustc also has to figure out which of the closure traits (Fn,
+FnMut, or FnOnce) a closure is capable of
+implementing.
Let's start with a few examples:
+Example 1
+To start, let's take a look at how the closure in the following example is desugared:
++fn closure(f: impl Fn()) { + f(); +} + +fn main() { + let x: i32 = 10; + closure(|| println!("Hi {}", x)); // The closure just reads x. + println!("Value of x after return {}", x); +} +
Let's say the above is the content of a file called immut.rs. If we compile
+immut.rs using the following command. The -Z dump-mir=all flag will cause
+rustc to generate and dump the MIR to a directory called mir_dump.
> rustc +stage1 immut.rs -Z dump-mir=all
+After we run this command, we will see a newly generated directory in our
+current working directory called mir_dump, which will contain several files.
+If we look at file rustc.main.-------.mir_map.0.mir, we will find, among
+other things, it also contains this line:
_4 = &_1;
+_3 = [closure@immut.rs:7:13: 7:36] { x: move _4 };
+Note that in the MIR examples in this chapter, _1 is x.
Here in first line _4 = &_1;, the mir_dump tells us that x was borrowed
+as an immutable reference. This is what we would hope as our closure just
+reads x.
Example 2
+Here is another example:
++fn closure(mut f: impl FnMut()) { + f(); +} + +fn main() { + let mut x: i32 = 10; + closure(|| { + x += 10; // The closure mutates the value of x + println!("Hi {}", x) + }); + println!("Value of x after return {}", x); +} +
_4 = &mut _1;
+_3 = [closure@mut.rs:7:13: 10:6] { x: move _4 };
+This time along, in the line _4 = &mut _1;, we see that the borrow is changed to mutable borrow.
+Fair enough! The closure increments x by 10.
Example 3
+One more example:
++fn closure(f: impl FnOnce()) { + f(); +} + +fn main() { + let x = vec![21]; + closure(|| { + drop(x); // Makes x unusable after the fact. + }); + // println!("Value of x after return {:?}", x); +} +
_6 = [closure@move.rs:7:13: 9:6] { x: move _1 }; // bb16[3]: scope 1 at move.rs:7:13: 9:6
+Here, x is directly moved into the closure and the access to it will not be permitted after the
+closure.
Inferences in the compiler
+Now let's dive into rustc code and see how all these inferences are done by the compiler.
+Let's start with defining a term that we will be using quite a bit in the rest of the discussion -
+upvar. An upvar is a variable that is local to the function where the closure is defined. So,
+in the above examples, x will be an upvar to the closure. They are also sometimes referred to as
+the free variables meaning they are not bound to the context of the closure.
+compiler/rustc_passes/src/upvars.rs defines a query called upvars_mentioned
+for this purpose.
Other than lazy invocation, one other thing that distinguishes a closure from a
+normal function is that it can use the upvars. It borrows these upvars from its surrounding
+context; therefore the compiler has to determine the upvar's borrow type. The compiler starts with
+assigning an immutable borrow type and lowers the restriction (that is, changes it from
+immutable to mutable to move) as needed, based on the usage. In the Example 1 above, the
+closure only uses the variable for printing but does not modify it in any way and therefore, in the
+mir_dump, we find the borrow type for the upvar x to be immutable. In example 2, however, the
+closure modifies x and increments it by some value. Because of this mutation, the compiler, which
+started off assigning x as an immutable reference type, has to adjust it as a mutable reference.
+Likewise in the third example, the closure drops the vector and therefore this requires the variable
+x to be moved into the closure. Depending on the borrow kind, the closure has to implement the
+appropriate trait: Fn trait for immutable borrow, FnMut for mutable borrow,
+and FnOnce for move semantics.
Most of the code related to the closure is in the
+compiler/rustc_hir_typeck/src/upvar.rs file and the data structures are
+declared in the file compiler/rustc_middle/src/ty/mod.rs.
Before we go any further, let's discuss how we can examine the flow of control through the rustc
+codebase. For closures specifically, set the RUSTC_LOG env variable as below and collect the
+output in a file:
> RUSTC_LOG=rustc_hir_typeck::upvar rustc +stage1 -Z dump-mir=all \
+ <.rs file to compile> 2> <file where the output will be dumped>
+This uses the stage1 compiler and enables debug! logging for the
+rustc_hir_typeck::upvar module.
The other option is to step through the code using lldb or gdb.
+-
+
rust-lldb build/host/stage1/bin/rustc test.rs
+- In lldb:
+
-
+
b upvar.rs:134// Setting the breakpoint on a certain line in the upvar.rs file`
+r// Run the program until it hits the breakpoint
+
+
Let's start with upvar.rs. This file has something called
+the euv::ExprUseVisitor which walks the source of the closure and
+invokes a callback for each upvar that is borrowed, mutated, or moved.
+fn main() { + let mut x = vec![21]; + let _cl = || { + let y = x[0]; // 1. + x[0] += 1; // 2. + }; +} +
In the above example, our visitor will be called twice, for the lines marked 1 and 2, once for a +shared borrow and another one for a mutable borrow. It will also tell us what was borrowed.
+The callbacks are defined by implementing the Delegate trait. The
+InferBorrowKind type implements Delegate and keeps a map that
+records for each upvar which mode of capture was required. The modes of capture
+can be ByValue (moved) or ByRef (borrowed). For ByRef borrows, the possible
+BorrowKinds are ImmBorrow, UniqueImmBorrow, MutBorrow as defined in the
+compiler/rustc_middle/src/ty/mod.rs.
Delegate defines a few different methods (the different callbacks):
+consume for move of a variable, borrow for a borrow of some kind
+(shared or mutable), and mutate when we see an assignment of something.
All of these callbacks have a common argument cmt which stands for Category,
+Mutability and Type and is defined in
+compiler/rustc_hir_typeck/src/expr_use_visitor.rs. Borrowing from the code
+comments, "cmt is a complete categorization of a value indicating where it
+originated and how it is located, as well as the mutability of the memory in
+which the value is stored". Based on the callback (consume, borrow etc.), we
+will call the relevant adjust_upvar_borrow_kind_for_<something> and pass the
+cmt along. Once the borrow type is adjusted, we store it in the table, which
+basically says what borrows were made for each closure.
self.tables
+ .borrow_mut()
+ .upvar_capture_map
+ .extend(delegate.adjust_upvar_captures);
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/compiler-debugging.html b/compiler-debugging.html
new file mode 100644
index 000000000..a96230ab7
--- /dev/null
+++ b/compiler-debugging.html
@@ -0,0 +1,536 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Coherence
+++NOTE: this is based on notes by @lcnr
+
Coherence checking is what detects both of trait impls and inherent impls overlapping with others.
+(reminder: inherent impls are impls of concrete types like impl MyStruct {})
Overlapping trait impls always produce an error, +while overlapping inherent impls result in an error only if they have methods with the same name.
+Checking for overlaps is split in two parts. First there's the overlap check(s), +which finds overlaps between traits and inherent implementations that the compiler currently knows about.
+However, Coherence also results in an error if any other impls could exist, +even if they are currently unknown. +This affects impls which may get added to upstream crates in a backwards compatible way, +and impls from downstream crates. +This is called the Orphan check.
+Overlap checks
+Overlap checks are performed for both inherent impls, and for trait impls. +This uses the same overlap checking code, really done as two separate analyses. +Overlap checks always consider pairs of implementations, comparing them to each other.
+Overlap checking for inherent impl blocks is done through fn check_item in coherence/inherent_impls_overlap.rs),
+where you can very clearly see that (at least for small n), the check really performs n^2
+comparisons between impls.
In the case of traits, this check is currently done as part of building the specialization graph, +to handle specializing impls overlapping with their parent, but this may change in the future.
+In both cases, all pairs of impls are checked for overlap.
+Overlapping is sometimes partially allowed:
+-
+
- for marker traits +
- under specialization +
but normally isn't.
+The overlap check has various modes (see OverlapMode).
+Importantly, there's the explicit negative impl check, and the implicit negative impl check.
+Both try to prove that an overlap is definitely impossible.
The explicit negative impl check
+This check is done in impl_intersection_has_negative_obligation.
This check tries to find a negative trait implementation. +For example:
++#![allow(unused)] +fn main() { +struct MyCustomErrorType; + +// both in your own crate +impl From<&str> for MyCustomErrorType {} +impl<E> From<E> for MyCustomErrorType where E: Error {} +} +
In this example, we'd get:
+MyCustomErrorType: From<&str> and MyCustomErrorType: From<?E>, giving ?E = &str.
And thus, these two implementations would overlap.
+However, libstd provides &str: !Error, and therefore guarantees that there
+will never be a positive implementation of &str: Error, and thus there is no overlap.
Note that for this kind of negative impl check, we must have explicit negative implementations provided. +This is not currently stable.
+The implicit negative impl check
+This check is done in impl_intersection_has_impossible_obligation,
+and does not rely on negative trait implementations and is stable.
Let's say there's a
++#![allow(unused)] +fn main() { +impl From<MyLocalType> for Box<dyn Error> {} // in your own crate +impl<E> From<E> for Box<dyn Error> where E: Error {} // in std +} +
This would give: Box<dyn Error>: From<MyLocalType>, and Box<dyn Error>: From<?E>,
+giving ?E = MyLocalType.
In your crate there's no MyLocalType: Error, downstream crates cannot implement Error (a remote trait) for MyLocalType (a remote type).
+Therefore, these two impls do not overlap.
+Importantly, this works even if there isn't a impl !Error for MyLocalType.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/compiler-src.html b/compiler-src.html
new file mode 100644
index 000000000..919fc2172
--- /dev/null
+++ b/compiler-src.html
@@ -0,0 +1,359 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Configuring CodeLLDB for debugging
+
+
+
+
+ Debugging the compiler
+-
+
- Configuring the compiler +
- Suppressing the ICE file +
- Getting a backtrace +
-Zflags + +
+- Getting logging output +
- Narrowing (Bisecting) Regressions +
- Downloading Artifacts from Rust's CI +
#[rustc_*]TEST attributes + +
+- Configuring CodeLLDB for debugging
rustc
+
This chapter contains a few tips to debug the compiler. These tips aim to be +useful no matter what you are working on. Some of the other chapters have +advice about specific parts of the compiler (e.g. the Queries Debugging and +Testing chapter or the LLVM Debugging +chapter).
+Configuring the compiler
+By default, rustc is built without most debug information. To enable debug info,
+set debug = true in your config.toml.
Setting debug = true turns on many different debug options (e.g., debug-assertions,
+debug-logging, etc.) which can be individually tweaked if you want to, but many people
+simply set debug = true.
If you want to use GDB to debug rustc, please set config.toml with options:
[rust]
+debug = true
+debuginfo-level = 2
+++NOTE: +This will use a lot of disk space +(upwards of 35GB), +and will take a lot more compile time. +With
+debuginfo-level = 1(the default whendebug = true), +you will be able to track the execution path, +but will lose the symbol information for debugging.
The default configuration will enable symbol-mangling-version v0.
+This requires at least GDB v10.2,
+otherwise you need to disable new symbol-mangling-version in config.toml.
[rust]
+new-symbol-mangling = false
+++See the comments in
+config.example.tomlfor more info.
You will need to rebuild the compiler after changing any configuration option.
+Suppressing the ICE file
+By default, if rustc encounters an Internal Compiler Error (ICE) it will dump the ICE contents to an
+ICE file within the current working directory named rustc-ice-<timestamp>-<pid>.txt. If this is
+not desirable, you can prevent the ICE file from being created with RUSTC_ICE=0.
Getting a backtrace
+When you have an ICE (panic in the compiler), you can set
+RUST_BACKTRACE=1 to get the stack trace of the panic! like in
+normal Rust programs. IIRC backtraces don't work on MinGW,
+sorry. If you have trouble or the backtraces are full of unknown,
+you might want to find some way to use Linux, Mac, or MSVC on Windows.
In the default configuration (without debug set to true), you don't have line numbers
+enabled, so the backtrace looks like this:
stack backtrace:
+ 0: std::sys::imp::backtrace::tracing::imp::unwind_backtrace
+ 1: std::sys_common::backtrace::_print
+ 2: std::panicking::default_hook::{{closure}}
+ 3: std::panicking::default_hook
+ 4: std::panicking::rust_panic_with_hook
+ 5: std::panicking::begin_panic
+ (~~~~ LINES REMOVED BY ME FOR BREVITY ~~~~)
+ 32: rustc_typeck::check_crate
+ 33: <std::thread::local::LocalKey<T>>::with
+ 34: <std::thread::local::LocalKey<T>>::with
+ 35: rustc::ty::context::TyCtxt::create_and_enter
+ 36: rustc_driver::driver::compile_input
+ 37: rustc_driver::run_compiler
+If you set debug = true, you will get line numbers for the stack trace.
+Then the backtrace will look like this:
stack backtrace:
+ (~~~~ LINES REMOVED BY ME FOR BREVITY ~~~~)
+ at /home/user/rust/compiler/rustc_typeck/src/check/cast.rs:110
+ 7: rustc_typeck::check::cast::CastCheck::check
+ at /home/user/rust/compiler/rustc_typeck/src/check/cast.rs:572
+ at /home/user/rust/compiler/rustc_typeck/src/check/cast.rs:460
+ at /home/user/rust/compiler/rustc_typeck/src/check/cast.rs:370
+ (~~~~ LINES REMOVED BY ME FOR BREVITY ~~~~)
+ 33: rustc_driver::driver::compile_input
+ at /home/user/rust/compiler/rustc_driver/src/driver.rs:1010
+ at /home/user/rust/compiler/rustc_driver/src/driver.rs:212
+ 34: rustc_driver::run_compiler
+ at /home/user/rust/compiler/rustc_driver/src/lib.rs:253
+-Z flags
+The compiler has a bunch of -Z * flags. These are unstable flags that are only
+enabled on nightly. Many of them are useful for debugging. To get a full listing
+of -Z flags, use -Z help.
One useful flag is -Z verbose-internals, which generally enables printing more
+info that could be useful for debugging.
Right below you can find elaborate explainers on a selected few.
+Getting a backtrace for errors
+If you want to get a backtrace to the point where the compiler emits an
+error message, you can pass the -Z treat-err-as-bug=n, which will make
+the compiler panic on the nth error. If you leave off =n, the compiler will
+assume 1 for n and thus panic on the first error it encounters.
For example:
+$ cat error.rs
++fn main() { + 1 + (); +} +
$ rustc +stage1 error.rs
+error[E0277]: cannot add `()` to `{integer}`
+ --> error.rs:2:7
+ |
+2 | 1 + ();
+ | ^ no implementation for `{integer} + ()`
+ |
+ = help: the trait `Add<()>` is not implemented for `{integer}`
+
+error: aborting due to previous error
+Now, where does the error above come from?
+$ RUST_BACKTRACE=1 rustc +stage1 error.rs -Z treat-err-as-bug
+error[E0277]: the trait bound `{integer}: std::ops::Add<()>` is not satisfied
+ --> error.rs:2:7
+ |
+2 | 1 + ();
+ | ^ no implementation for `{integer} + ()`
+ |
+ = help: the trait `std::ops::Add<()>` is not implemented for `{integer}`
+
+error: internal compiler error: unexpected panic
+
+note: the compiler unexpectedly panicked. this is a bug.
+
+note: we would appreciate a bug report: https://github.com/rust-lang/rust/blob/master/CONTRIBUTING.md#bug-reports
+
+note: rustc 1.24.0-dev running on x86_64-unknown-linux-gnu
+
+note: run with `RUST_BACKTRACE=1` for a backtrace
+
+thread 'rustc' panicked at 'encountered error with `-Z treat_err_as_bug',
+/home/user/rust/compiler/rustc_errors/src/lib.rs:411:12
+note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose
+backtrace.
+stack backtrace:
+ (~~~ IRRELEVANT PART OF BACKTRACE REMOVED BY ME ~~~)
+ 7: rustc::traits::error_reporting::<impl rustc::infer::InferCtxt<'a, 'tcx>>
+ ::report_selection_error
+ at /home/user/rust/compiler/rustc_middle/src/traits/error_reporting.rs:823
+ 8: rustc::traits::error_reporting::<impl rustc::infer::InferCtxt<'a, 'tcx>>
+ ::report_fulfillment_errors
+ at /home/user/rust/compiler/rustc_middle/src/traits/error_reporting.rs:160
+ at /home/user/rust/compiler/rustc_middle/src/traits/error_reporting.rs:112
+ 9: rustc_typeck::check::FnCtxt::select_obligations_where_possible
+ at /home/user/rust/compiler/rustc_typeck/src/check/mod.rs:2192
+ (~~~ IRRELEVANT PART OF BACKTRACE REMOVED BY ME ~~~)
+ 36: rustc_driver::run_compiler
+ at /home/user/rust/compiler/rustc_driver/src/lib.rs:253
+Cool, now I have a backtrace for the error!
+Debugging delayed bugs
+The -Z eagerly-emit-delayed-bugs option makes it easy to debug delayed bugs.
+It turns them into normal errors, i.e. makes them visible. This can be used in
+combination with -Z treat-err-as-bug to stop at a particular delayed bug and
+get a backtrace.
Getting the error creation location
+-Z track-diagnostics can help figure out where errors are emitted. It uses #[track_caller]
+for this and prints its location alongside the error:
$ RUST_BACKTRACE=1 rustc +stage1 error.rs -Z track-diagnostics
+error[E0277]: cannot add `()` to `{integer}`
+ --> src\error.rs:2:7
+ |
+2 | 1 + ();
+ | ^ no implementation for `{integer} + ()`
+-Ztrack-diagnostics: created at compiler/rustc_trait_selection/src/traits/error_reporting/mod.rs:638:39
+ |
+ = help: the trait `Add<()>` is not implemented for `{integer}`
+ = help: the following other types implement trait `Add<Rhs>`:
+ <&'a f32 as Add<f32>>
+ <&'a f64 as Add<f64>>
+ <&'a i128 as Add<i128>>
+ <&'a i16 as Add<i16>>
+ <&'a i32 as Add<i32>>
+ <&'a i64 as Add<i64>>
+ <&'a i8 as Add<i8>>
+ <&'a isize as Add<isize>>
+ and 48 others
+
+For more information about this error, try `rustc --explain E0277`.
+This is similar but different to -Z treat-err-as-bug:
-
+
- it will print the locations for all errors emitted +
- it does not require a compiler built with debug symbols +
- you don't have to read through a big stack trace. +
Getting logging output
+The compiler uses the tracing crate for logging.
For details see the guide section on tracing
+Narrowing (Bisecting) Regressions
+The cargo-bisect-rustc tool can be used as a quick and easy way to
+find exactly which PR caused a change in rustc behavior. It automatically
+downloads rustc PR artifacts and tests them against a project you provide
+until it finds the regression. You can then look at the PR to get more context
+on why it was changed. See this tutorial on how to use
+it.
Downloading Artifacts from Rust's CI
+The rustup-toolchain-install-master tool by kennytm can be used to
+download the artifacts produced by Rust's CI for a specific SHA1 -- this
+basically corresponds to the successful landing of some PR -- and then sets
+them up for your local use. This also works for artifacts produced by @bors try. This is helpful when you want to examine the resulting build of a PR
+without doing the build yourself.
#[rustc_*] TEST attributes
+The compiler defines a whole lot of internal (perma-unstable) attributes some of which are useful
+for debugging by dumping extra compiler-internal information. These are prefixed with rustc_ and
+are gated behind the internal feature rustc_attrs (enabled via e.g. #![feature(rustc_attrs)]).
For a complete and up to date list, see builtin_attrs. More specifically, the ones marked TEST.
+Here are some notable ones:
| Attribute | Description |
|---|---|
rustc_def_path | Dumps the def_path_str of an item. |
rustc_dump_def_parents | Dumps the chain of DefId parents of certain definitions. |
rustc_dump_item_bounds | Dumps the item_bounds of an item. |
rustc_dump_predicates | Dumps the predicates_of an item. |
rustc_dump_vtable | |
rustc_hidden_type_of_opaques | Dumps the hidden type of each opaque types in the crate. |
rustc_layout | See this section. |
rustc_object_lifetime_default | Dumps the object lifetime defaults of an item. |
rustc_outlives | Dumps implied bounds of an item. More precisely, the inferred_outlives_of an item. |
rustc_regions | Dumps NLL closure region requirements. |
rustc_symbol_name | Dumps the mangled & demangled symbol_name of an item. |
rustc_variances | Dumps the variances of an item. |
Right below you can find elaborate explainers on a selected few.
+Formatting Graphviz output (.dot files)
+Some compiler options for debugging specific features yield graphviz graphs -
+e.g. the #[rustc_mir(borrowck_graphviz_postflow="suffix.dot")] attribute
+dumps various borrow-checker dataflow graphs.
These all produce .dot files. To view these files, install graphviz (e.g.
+apt-get install graphviz) and then run the following commands:
$ dot -T pdf maybe_init_suffix.dot > maybe_init_suffix.pdf
+$ firefox maybe_init_suffix.pdf # Or your favorite pdf viewer
+Debugging type layouts
+The internal attribute #[rustc_layout] can be used to dump the Layout of
+the type it is attached to. For example:
+#![allow(unused)] +#![feature(rustc_attrs)] + +fn main() { +#[rustc_layout(debug)] +type T<'a> = &'a u32; +} +
Will emit the following:
+error: layout_of(&'a u32) = Layout {
+ fields: Primitive,
+ variants: Single {
+ index: 0,
+ },
+ abi: Scalar(
+ Scalar {
+ value: Pointer,
+ valid_range: 1..=18446744073709551615,
+ },
+ ),
+ largest_niche: Some(
+ Niche {
+ offset: Size {
+ raw: 0,
+ },
+ scalar: Scalar {
+ value: Pointer,
+ valid_range: 1..=18446744073709551615,
+ },
+ },
+ ),
+ align: AbiAndPrefAlign {
+ abi: Align {
+ pow2: 3,
+ },
+ pref: Align {
+ pow2: 3,
+ },
+ },
+ size: Size {
+ raw: 8,
+ },
+}
+ --> src/lib.rs:4:1
+ |
+4 | type T<'a> = &'a u32;
+ | ^^^^^^^^^^^^^^^^^^^^^
+
+error: aborting due to previous error
+Configuring CodeLLDB for debugging rustc
+If you are using VSCode, and have edited your config.toml to request debugging
+level 1 or 2 for the parts of the code you're interested in, then you should be
+able to use the CodeLLDB extension in VSCode to debug it.
Here is a sample launch.json file, being used to run a stage 1 compiler direct
+from the directory where it is built (does not have to be "installed"):
// .vscode/launch.json
+{
+ "version": "0.2.0",
+ "configurations": [
+ {
+ "type": "lldb",
+ "request": "launch",
+ "name": "Launch",
+ "args": [], // array of string command-line arguments to pass to compiler
+ "program": "${workspaceFolder}/build/host/stage1/bin/rustc",
+ "windows": { // applicable if using windows
+ "program": "${workspaceFolder}/build/host/stage1/bin/rustc.exe"
+ },
+ "cwd": "${workspaceFolder}", // current working directory at program start
+ "stopOnEntry": false,
+ "sourceLanguages": ["rust"]
+ }
+ ]
+ }
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/compiler-team.html b/compiler-team.html
new file mode 100644
index 000000000..669568edd
--- /dev/null
+++ b/compiler-team.html
@@ -0,0 +1,315 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ High-level overview of the compiler source
+-
+
- Workspace structure +
- Compiler
+
-
+
- Big picture +
+ - rustdoc +
- Tests +
- Build System +
- Standard library +
- Other +
Now that we have seen what the compiler does,
+let's take a look at the structure of the rust-lang/rust repository,
+where the rustc source code lives.
++You may find it helpful to read the "Overview of the compiler" +chapter, which introduces how the compiler works, before this one.
+
Workspace structure
+The rust-lang/rust repository consists of a single large cargo workspace
+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.
The repository consists of three main directories:
+-
+
-
+
+compiler/contains the source code forrustc. It consists of many crates +that together make up the compiler.
+ -
+
+library/contains the standard libraries (core,alloc,std, +proc_macro,test), as well as the Rust runtime (backtrace,rtstartup, +lang_start).
+ -
+
+tests/contains the compiler tests.
+ -
+
+src/contains the source code forrustdoc,clippy,cargo, the build system, +language docs, etc.
+
Compiler
+The compiler is implemented in the various compiler/ crates.
+The compiler/ crates all have names starting with rustc_*. These are a
+collection of around 50 interdependent crates ranging in size from tiny to
+huge. There is also the rustc crate which is the actual binary (i.e. the
+main function); it doesn't actually do anything besides calling the
+rustc_driver crate, which drives the various parts of compilation in other
+crates.
The dependency structure of these crates is complex, but roughly it is +something like this:
+-
+
rustc(the binary) callsrustc_driver::main. +-
+
rustc_driverdepends on a lot of other crates, but the main one is +rustc_interface. +-
+
rustc_interfacedepends on most of the other compiler crates. It +is a fairly generic interface for driving the whole compilation. +-
+
- Most of the other
rustc_*crates depend onrustc_middle, +which defines a lot of central data structures in the compiler. +-
+
rustc_middleand most of the other crates depend on a +handful of crates representing the early parts of the +compiler (e.g. the parser), fundamental data structures (e.g. +Span), or error reporting:rustc_data_structures, +rustc_span,rustc_errors, etc.
+
+
+- Most of the other
+
+
You can see the exact dependencies by reading the Cargo.toml for the various
+crates, just like a normal Rust crate.
One final thing: src/llvm-project is a submodule for our fork of LLVM.
+During bootstrapping, LLVM is built and the compiler/rustc_llvm crate
+contains Rust wrappers around LLVM (which is written in C++), so that the
+compiler can interface with it.
Most of this book is about the compiler, so we won't have any further +explanation of these crates here.
+Big picture
+The dependency structure of the compiler is influenced by two main factors:
+-
+
- Organization. The compiler is a huge codebase; it would be an impossibly +large crate. In part, the dependency structure reflects the code structure +of the compiler. +
- Compile-time. By breaking the compiler into multiple crates, we can take +better advantage of incremental/parallel compilation using cargo. In +particular, we try to have as few dependencies between crates as possible so +that we don't have to rebuild as many crates if you change one. +
At the very bottom of the dependency tree are a handful of crates that are used
+by the whole compiler (e.g. rustc_span). The very early parts of the
+compilation process (e.g. parsing and the Abstract Syntax Tree (AST))
+depend on only these.
After the AST is constructed and other early analysis is done, the
+compiler's query system gets set up. The query system is set up in a
+clever way using function pointers. This allows us to break dependencies
+between crates, allowing more parallel compilation. The query system is defined
+in rustc_middle, so nearly all subsequent parts of the compiler depend on
+this crate. It is a really large crate, leading to long compile times. Some
+efforts have been made to move stuff out of it with varying success. Another
+side-effect is that sometimes related functionality gets scattered across
+different crates. For example, linting functionality is found across earlier
+parts of the crate, rustc_lint, rustc_middle, and other places.
Ideally there would be fewer, more cohesive crates, with incremental and +parallel compilation making sure compile times stay reasonable. However, +incremental and parallel compilation haven't gotten good enough for that yet, +so breaking things into separate crates has been our solution so far.
+At the top of the dependency tree is rustc_driver and rustc_interface
+which is an unstable wrapper around the query system helping drive various
+stages of compilation. Other consumers of the compiler may use this interface
+in different ways (e.g. rustdoc or maybe eventually rust-analyzer). The
+rustc_driver crate first parses command line arguments and then uses
+rustc_interface to drive the compilation to completion.
rustdoc
+The bulk of rustdoc is in librustdoc. However, the rustdoc binary
+itself is src/tools/rustdoc, which does nothing except call rustdoc::main.
There is also JavaScript and CSS for the docs in src/tools/rustdoc-js
+and src/tools/rustdoc-themes.
You can read more about rustdoc in this chapter.
Tests
+The test suite for all of the above is in tests/. You can read more
+about the test suite in this chapter.
The test harness is in src/tools/compiletest/.
Build System
+There are a number of tools in the repository just for building the compiler,
+standard library, rustdoc, etc, along with testing, building a full Rust
+distribution, etc.
One of the primary tools is src/bootstrap/. You can read more about
+bootstrapping in this chapter. The process may also use other tools
+from src/tools/, such as tidy/ or compiletest/.
Standard library
+This code is fairly similar to most other Rust crates except that it must be
+built in a special way because it can use unstable (nightly) features.
+The standard library is sometimes referred to as libstd or the "standard facade".
Other
+There are a lot of other things in the rust-lang/rust repo that are related
+to building a full Rust distribution. Most of the time you don't need to worry about them.
These include:
+ + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/compiletest.html b/compiletest.html
new file mode 100644
index 000000000..b90209360
--- /dev/null
+++ b/compiletest.html
@@ -0,0 +1,12 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ About the compiler team
+rustc is maintained by the Rust compiler team. The people who belong to +this team collectively work to track regressions and implement new features. +Members of the Rust compiler team are people who have made significant +contributions to rustc and its design.
+Discussion
+Currently the compiler team chats in Zulip:
+-
+
- Team chat occurs in the
t-compilerstream on the Zulip instance
+ - There are also a number of other associated Zulip streams,
+such as
t-compiler/help, where people can ask for help +with rustc development, ort-compiler/meetings, +where the team holds their weekly triage and steering meetings.
+
Reviewers
+If you're interested in figuring out who can answer questions about a +particular part of the compiler, or you'd just like to know who works on what, +check out triagebot.toml's assign section. +It contains a listing of the various parts of the compiler and a list of people +who are reviewers of each part.
+Rust compiler meeting
+The compiler team has a weekly meeting where we do triage and try to +generally stay on top of new bugs, regressions, and discuss important +things in general. +They are held on Zulip. It works roughly as follows:
+-
+
- Announcements, MCPs/FCPs, and WG-check-ins: We share some +announcements with the rest of the team about important things we want +everyone to be aware of. We also share the status of MCPs and FCPs and we +use the opportunity to have a couple of WGs giving us an update about +their work. +
- Check for beta and stable nominations: These are nominations of things to +backport to beta and stable respectively. +We then look for new cases where the compiler broke previously working +code in the wild. Regressions are important issues to fix, so it's +likely that they are tagged as P-critical or P-high; the major +exception would be bug fixes (though even there we often aim to give +warnings first). +
- Review P-critical and P-high bugs: P-critical and P-high bugs are +those that are sufficiently important for us to actively track +progress. P-critical and P-high bugs should ideally always have an +assignee. +
- Check S-waiting-on-team and I-nominated issues: These are issues where feedback from +the team is desired. +
- Look over the performance triage report: We check for PRs that made the +performance worse and try to decide if it's worth reverting the performance regression or if +the regression can be addressed in a future PR. +
The meeting currently takes place on Thursdays at 10am Boston time +(UTC-4 typically, but daylight savings time sometimes makes things +complicated).
+Team membership
+Membership in the Rust team is typically offered when someone has been +making significant contributions to the compiler for some +time. Membership is both a recognition but also an obligation: +compiler team members are generally expected to help with upkeep as +well as doing reviews and other work.
+If you are interested in becoming a compiler team member, the first +thing to do is to start fixing some bugs, or get involved in a working +group. One good way to find bugs is to look for +open issues tagged with E-easy +or +E-mentor.
+You can also dig through the graveyard of PRs that were +closed due to inactivity, +some of them may contain work that is still useful - refer to the +associated issues, if any - and only needs some finishing touches +for which the original author didn't have time.
+r+ rights
+Once you have made a number of individual PRs to rustc, we will often +offer r+ privileges. This means that you have the right to instruct +"bors" (the robot that manages which PRs get landed into rustc) to +merge a PR +(here are some instructions for how to talk to bors).
+The guidelines for reviewers are as follows:
+-
+
- You are always welcome to review any PR, regardless of who it is
+assigned to. However, do not r+ PRs unless:
+
-
+
- You are confident in that part of the code. +
- You are confident that nobody else wants to review it first.
+
-
+
- For example, sometimes people will express a desire to review a +PR before it lands, perhaps because it touches a particularly +sensitive part of the code. +
+
+ - Always be polite when reviewing: you are a representative of the +Rust project, so it is expected that you will go above and beyond +when it comes to the Code of Conduct. +
Reviewer rotation
+Once you have r+ rights, you can also be added to the reviewer rotation.
+triagebot is the bot that automatically assigns incoming PRs to reviewers.
+If you are added, you will be randomly selected to review
+PRs. If you find you are assigned a PR that you don't feel comfortable
+reviewing, you can also leave a comment like r? @so-and-so to assign
+to someone else — if you don't know who to request, just write r? @nikomatsakis for reassignment and @nikomatsakis will pick someone
+for you.
Getting on the reviewer rotation is much appreciated as it lowers the +review burden for all of us! However, if you don't have time to give +people timely feedback on their PRs, it may be better that you don't +get on the list.
+Full team membership
+Full team membership is typically extended once someone made many +contributions to the Rust compiler over time, ideally (but not +necessarily) to multiple areas. Sometimes this might be implementing a +new feature, but it is also important — perhaps more important! — to +have time and willingness to help out with general upkeep such as +bugfixes, tracking regressions, and other less glamorous work.
+ +Redirecting to... tests/compiletest.html.
+ + diff --git a/const-eval.html b/const-eval.html new file mode 100644 index 000000000..e24aadd5e --- /dev/null +++ b/const-eval.html @@ -0,0 +1,253 @@ + + + + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/const-eval/interpret.html b/const-eval/interpret.html
new file mode 100644
index 000000000..9735e4d0b
--- /dev/null
+++ b/const-eval/interpret.html
@@ -0,0 +1,396 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Constant Evaluation
+Constant evaluation is the process of computing values at compile time. For a +specific item (constant/static/array length) this happens after the MIR for the +item is borrow-checked and optimized. In many cases trying to const evaluate an +item will trigger the computation of its MIR for the first time.
+Prominent examples are:
+-
+
- The initializer of a
static
+ - Array length
+
-
+
- needs to be known to reserve stack or heap space +
+ - Enum variant discriminants
+
-
+
- needs to be known to prevent two variants from having the same +discriminant +
+ - Patterns
+
-
+
- need to be known to check for overlapping patterns +
+
Additionally constant evaluation can be used to reduce the workload or binary +size at runtime by precomputing complex operations at compiletime and only +storing the result.
+All uses of constant evaluation can either be categorized as "influencing the type system" +(array lengths, enum variant discriminants, const generic parameters), or as solely being +done to precompute expressions to be used at runtime.
+Constant evaluation can be done by calling the const_eval_* functions of TyCtxt.
+They're the wrappers of the const_eval query.
-
+
const_eval_global_id_for_typeckevaluates a constant to a valtree, +so the result value can be further inspected by the compiler.
+const_eval_global_idevaluate a constant to an "opaque blob" containing its final value; +this is only useful for codegen backends and the CTFE evaluator engine itself.
+eval_static_initializerspecifically computes the initial values of a static. +Statics are special; all other functions do not represent statics correctly +and have thus assertions preventing their use on statics.
+
The const_eval_* functions use a ParamEnv of environment
+in which the constant is evaluated (e.g. the function within which the constant is used)
+and a GlobalId. The GlobalId is made up of an Instance referring to a constant
+or static or of an Instance of a function and an index into the function's Promoted table.
Constant evaluation returns an EvalToValTreeResult for type system constants
+or EvalToConstValueResult with either the error, or a representation of the
+evaluated constant: a valtree or a MIR constant
+value, respectively.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/contributing.html b/contributing.html
new file mode 100644
index 000000000..95a1a043d
--- /dev/null
+++ b/contributing.html
@@ -0,0 +1,618 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Interpreter
+-
+
- Datastructures +
- Memory + + +
- Interpretation +
The interpreter is a virtual machine for executing MIR without compiling to
+machine code. It is usually invoked via tcx.const_eval_* functions. The
+interpreter is shared between the compiler (for compile-time function
+evaluation, CTFE) and the tool Miri, which
+uses the same virtual machine to detect Undefined Behavior in (unsafe) Rust
+code.
If you start out with a constant:
++#![allow(unused)] +fn main() { +const FOO: usize = 1 << 12; +} +
rustc doesn't actually invoke anything until the constant is either used or +placed into metadata.
+Once you have a use-site like:
+type Foo = [u8; FOO - 42];
+The compiler needs to figure out the length of the array before being able to +create items that use the type (locals, constants, function arguments, ...).
+To obtain the (in this case empty) parameter environment, one can call
+let param_env = tcx.param_env(length_def_id);. The GlobalId needed is
let gid = GlobalId {
+ promoted: None,
+ instance: Instance::mono(length_def_id),
+};
+Invoking tcx.const_eval(param_env.and(gid)) will now trigger the creation of
+the MIR of the array length expression. The MIR will look something like this:
Foo::{{constant}}#0: usize = {
+ let mut _0: usize;
+ let mut _1: (usize, bool);
+
+ bb0: {
+ _1 = CheckedSub(const FOO, const 42usize);
+ assert(!move (_1.1: bool), "attempt to subtract with overflow") -> bb1;
+ }
+
+ bb1: {
+ _0 = move (_1.0: usize);
+ return;
+ }
+}
+Before the evaluation, a virtual memory location (in this case essentially a
+vec![u8; 4] or vec![u8; 8]) is created for storing the evaluation result.
At the start of the evaluation, _0 and _1 are
+Operand::Immediate(Immediate::Scalar(ScalarMaybeUndef::Undef)). This is quite
+a mouthful: Operand can represent either data stored somewhere in the
+interpreter memory (Operand::Indirect), or (as an optimization)
+immediate data stored in-line. And Immediate can either be a single
+(potentially uninitialized) scalar value (integer or thin pointer),
+or a pair of two of them. In our case, the single scalar value is not (yet)
+initialized.
When the initialization of _1 is invoked, the value of the FOO constant is
+required, and triggers another call to tcx.const_eval_*, which will not be shown
+here. If the evaluation of FOO is successful, 42 will be subtracted from its
+value 4096 and the result stored in _1 as
+Operand::Immediate(Immediate::ScalarPair(Scalar::Raw { data: 4054, .. }, Scalar::Raw { data: 0, .. }). The first part of the pair is the computed value,
+the second part is a bool that's true if an overflow happened. A Scalar::Raw
+also stores the size (in bytes) of this scalar value; we are eliding that here.
The next statement asserts that said boolean is 0. In case the assertion
+fails, its error message is used for reporting a compile-time error.
Since it does not fail, Operand::Immediate(Immediate::Scalar(Scalar::Raw { data: 4054, .. })) is stored in the virtual memory it was allocated before the
+evaluation. _0 always refers to that location directly.
After the evaluation is done, the return value is converted from Operand to
+ConstValue by op_to_const: the former representation is geared towards
+what is needed during const evaluation, while ConstValue is shaped by the
+needs of the remaining parts of the compiler that consume the results of const
+evaluation. As part of this conversion, for types with scalar values, even if
+the resulting Operand is Indirect, it will return an immediate
+ConstValue::Scalar(computed_value) (instead of the usual ConstValue::ByRef).
+This makes using the result much more efficient and also more convenient, as no
+further queries need to be executed in order to get at something as simple as a
+usize.
Future evaluations of the same constants will not actually invoke +the interpreter, but just use the cached result.
+Datastructures
+The interpreter's outside-facing datastructures can be found in
+rustc_middle/src/mir/interpret.
+This is mainly the error enum and the ConstValue and Scalar types. A
+ConstValue can be either Scalar (a single Scalar, i.e., integer or thin
+pointer), Slice (to represent byte slices and strings, as needed for pattern
+matching) or ByRef, which is used for anything else and refers to a virtual
+allocation. These allocations can be accessed via the methods on
+tcx.interpret_interner. A Scalar is either some Raw integer or a pointer;
+see the next section for more on that.
If you are expecting a numeric result, you can use eval_usize (panics on
+anything that can't be represented as a u64) or try_eval_usize which results
+in an Option<u64> yielding the Scalar if possible.
Memory
+To support any kind of pointers, the interpreter needs to have a "virtual memory" that the
+pointers can point to. This is implemented in the Memory type. In the
+simplest model, every global variable, stack variable and every dynamic
+allocation corresponds to an Allocation in that memory. (Actually using an
+allocation for every MIR stack variable would be very inefficient; that's why we
+have Operand::Immediate for stack variables that are both small and never have
+their address taken. But that is purely an optimization.)
Such an Allocation is basically just a sequence of u8 storing the value of
+each byte in this allocation. (Plus some extra data, see below.) Every
+Allocation has a globally unique AllocId assigned in Memory. With that, a
+Pointer consists of a pair of an AllocId (indicating the allocation) and
+an offset into the allocation (indicating which byte of the allocation the
+pointer points to). It may seem odd that a Pointer is not just an integer
+address, but remember that during const evaluation, we cannot know at which
+actual integer address the allocation will end up -- so we use AllocId as
+symbolic base addresses, which means we need a separate offset. (As an aside,
+it turns out that pointers at run-time are
+more than just integers, too.)
These allocations exist so that references and raw pointers have something to
+point to. There is no global linear heap in which things are allocated, but each
+allocation (be it for a local variable, a static or a (future) heap allocation)
+gets its own little memory with exactly the required size. So if you have a
+pointer to an allocation for a local variable a, there is no possible (no
+matter how unsafe) operation that you can do that would ever change said pointer
+to a pointer to a different local variable b.
+Pointer arithmetic on a will only ever change its offset; the AllocId stays the same.
This, however, causes a problem when we want to store a Pointer into an
+Allocation: we cannot turn it into a sequence of u8 of the right length!
+AllocId and offset together are twice as big as a pointer "seems" to be. This
+is what the relocation field of Allocation is for: the byte offset of the
+Pointer gets stored as a bunch of u8, while its AllocId gets stored
+out-of-band. The two are reassembled when the Pointer is read from memory.
+The other bit of extra data an Allocation needs is undef_mask for keeping
+track of which of its bytes are initialized.
Global memory and exotic allocations
+Memory exists only during evaluation; it gets destroyed when the
+final value of the constant is computed. In case that constant contains any
+pointers, those get "interned" and moved to a global "const eval memory" that is
+part of TyCtxt. These allocations stay around for the remaining computation
+and get serialized into the final output (so that dependent crates can use
+them).
Moreover, to also support function pointers, the global memory in TyCtxt can
+also contain "virtual allocations": instead of an Allocation, these contain an
+Instance. That allows a Pointer to point to either normal data or a
+function, which is needed to be able to evaluate casts from function pointers to
+raw pointers.
Finally, the GlobalAlloc type used in the global memory also contains a
+variant Static that points to a particular const or static item. This is
+needed to support circular statics, where we need to have a Pointer to a
+static for which we cannot yet have an Allocation as we do not know the
+bytes of its value.
Pointer values vs Pointer types
+One common cause of confusion in the interpreter is that being a pointer value and having
+a pointer type are entirely independent properties. By "pointer value", we
+refer to a Scalar::Ptr containing a Pointer and thus pointing somewhere into
+the interpreter's virtual memory. This is in contrast to Scalar::Raw, which is just some
+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 obtained by casting or
+transmuting an integer to a pointer.
+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
+Although the main entry point to constant evaluation is the tcx.const_eval_*
+functions, there are additional functions in
+rustc_const_eval/src/const_eval
+that allow accessing the fields of a ConstValue (ByRef or otherwise). You should
+never have to access an Allocation directly except for translating it to the
+compilation target (at the moment just LLVM).
The interpreter starts by creating a virtual stack frame for the current constant that is +being evaluated. There's essentially no difference between a constant and a +function with no arguments, except that constants do not allow local (named) +variables at the time of writing this guide.
+A stack frame is defined by the Frame type in
+rustc_const_eval/src/interpret/eval_context.rs
+and contains all the local
+variables memory (None at the start of evaluation). Each frame refers to the
+evaluation of either the root constant or subsequent calls to const fn. The
+evaluation of another constant simply calls tcx.const_eval_*, which produce an
+entirely new and independent stack frame.
The frames are just a Vec<Frame>, there's no way to actually refer to a
+Frame's memory even if horrible shenanigans are done via unsafe code. The only
+memory that can be referred to are Allocations.
The interpreter now calls the step method (in
+rustc_const_eval/src/interpret/step.rs
+) until it either returns an error or has no further statements to execute. Each
+statement will now initialize or modify the locals or the virtual memory
+referred to by a local. This might require evaluating other constants or
+statics, which just recursively invokes tcx.const_eval_*.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/conventions.html b/conventions.html
new file mode 100644
index 000000000..8aa6677e6
--- /dev/null
+++ b/conventions.html
@@ -0,0 +1,323 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Contribution Procedures
+-
+
- Bug reports +
- Bug fixes or "normal" code changes +
- New features + + +
- Pull requests
+
-
+
- r? +
- Waiting for reviews +
- CI +
- r+ +
- Opening a PR +
- Reverting a PR +
+ - External dependencies +
- Writing documentation + + +
- Issue triage + + +
- Helpful links and information +
Bug reports
+While bugs are unfortunate, they're a reality in software. We can't fix what we +don't know about, so please report liberally. If you're not sure if something +is a bug or not, feel free to file a bug anyway.
+If you believe reporting your bug publicly represents a security risk to Rust users, +please follow our instructions for reporting security vulnerabilities.
+If you're using the nightly channel, please check if the bug exists in the +latest toolchain before filing your bug. It might be fixed already.
+If you have the chance, before reporting a bug, please search existing issues, +as it's possible that someone else has already reported your error. This doesn't +always work, and sometimes it's hard to know what to search for, so consider this +extra credit. We won't mind if you accidentally file a duplicate report.
+Similarly, to help others who encountered the bug find your issue, consider +filing an issue with a descriptive title, which contains information that might +be unique to it. This can be the language or compiler feature used, the +conditions that trigger the bug, or part of the error message if there is any. +An example could be: "impossible case reached" on lifetime inference for impl +Trait in return position.
+Opening an issue is as easy as following this +link and filling out the fields +in the appropriate provided template.
+Bug fixes or "normal" code changes
+For most PRs, no special procedures are needed. You can just open a PR, and it +will be reviewed, approved, and merged. This includes most bug fixes, +refactorings, and other user-invisible changes. The next few sections talk +about exceptions to this rule.
+Also, note that it is perfectly acceptable to open WIP PRs or GitHub Draft PRs. +Some people prefer to do this so they can get feedback along the +way or share their code with a collaborator. Others do this so they can utilize +the CI to build and test their PR (e.g. when developing on a slow machine).
+New features
+Rust has strong backwards-compatibility guarantees. Thus, new features can't +just be implemented directly in stable Rust. 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
masterbranch of the repo. This is the only +channel where unstable, incomplete, or experimental features are usable with +feature gates.
+
See this chapter on implementing new features for more +information.
+Breaking changes
+Breaking changes have a dedicated section in the dev-guide.
+Major changes
+The compiler team has a special process for large changes, whether or not they +cause breakage. This process is called a Major Change Proposal (MCP). MCP is a +relatively lightweight mechanism for getting feedback on large changes to the +compiler (as opposed to a full RFC or a design meeting with the team).
+Example of things that might require MCPs include major refactorings, changes +to important types, or important changes to how the compiler does something, or +smaller user-facing changes.
+When in doubt, ask on zulip. It would be a shame to put a lot of work +into a PR that ends up not getting merged! See this document for +more info on MCPs.
+Performance
+Compiler performance is important. We have put a lot of effort over the last +few years into gradually improving it.
+If you suspect that your change may cause a performance regression (or +improvement), you can request a "perf run" (and your reviewer may also request one +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, and you can see a comparison of your changes against the latest +master.
+++For an introduction to the performance of Rust code in general +which would also be useful in rustc development, see The Rust Performance Book.
+
Pull requests
+Pull requests (or PRs for short) are the primary mechanism we use to change Rust. +GitHub itself has some great documentation on using the +Pull Request feature. We use the "fork and pull" model described here, +where contributors push changes to their personal fork and create pull requests to +bring those changes into the source repository. We have more info about how to use git +when contributing to Rust under the git section.
+++Advice for potentially large, complex, cross-cutting and/or very domain-specific changes
+The compiler reviewers on rotation usually each have areas of the compiler that they know well, +but also have areas that they are not very familiar with. If your PR contains changes that are +large, complex, cross-cutting and/or highly domain-specific, it becomes very difficult to find a +suitable reviewer who is comfortable in reviewing all of the changes in such a PR. This is also +true if the changes are not only compiler-specific but also contains changes which fall under the +purview of reviewers from other teams, like the standard library team. There's a bot +which notifies the relevant teams and pings people who have setup specific alerts based on the +files modified.
+Before making such changes, you are strongly encouraged to discuss your proposed changes with +the compiler team beforehand (and with other teams that the changes would require approval +from), and work with the compiler team to see if we can help you break down a large potentially +unreviewable PR into a series of smaller more individually reviewable PRs.
+You can communicate with the compiler team by creating a #t-compiler thread on zulip +to discuss your proposed changes.
+Communicating with the compiler team beforehand helps in several ways:
++
+- It increases the likelihood of your PRs being reviewed in a timely manner. +
++
+- We can help you identify suitable reviewers before you open actual PRs, or help find +advisors and liaisons to help you navigate the change procedures, or help with running +try-jobs, perf runs and crater runs as suitable.
+- It helps the compiler team track your changes.
+- The compiler team can perform vibe checks on your changes early and often, to see if the +direction of the changes align with what the compiler team prefers to see.
+- Helps to avoid situations where you may have invested significant time and effort into large +changes that the compiler team might not be willing to accept, or finding out very late that the +changes are in a direction that the compiler team disagrees with.
+
r?
+All pull requests are reviewed by another person. We have a bot, +@rustbot, that will automatically assign a random person +to review your request based on which files you changed.
+If you want to request that a specific person reviews your pull request, you
+can add an r? to the pull request description or in a comment. For example,
+if you want to ask a review to @awesome-reviewer, add
r? @awesome-reviewer
+to the end of the pull request description, and @rustbot will assign +them instead of a random person. This is entirely optional.
+You can also assign a random reviewer from a specific team by writing r? rust-lang/groupname.
+As an example,
+if you were making a diagnostics change,
+then you could get a reviewer from the diagnostics team by adding:
r? rust-lang/diagnostics
+For a full list of possible groupnames,
+check the adhoc_groups section at the triagebot.toml config file,
+or the list of teams in the rust-lang teams database.
Waiting for reviews
+++NOTE
+Pull request reviewers are often working at capacity, +and many of them are contributing on a volunteer basis. +In order to minimize review delays, +pull request authors and assigned reviewers should ensure that the review label +(
+S-waiting-on-reviewandS-waiting-on-author) stays updated, +invoking these commands when appropriate:+
+- +
++
@rustbot author: +the review is finished, +and PR author should check the comments and take action accordingly.- +
++
@rustbot review: +the author is ready for a review, +and this PR will be queued again in the reviewer's queue.
Please note that the reviewers are humans, who for the most part work on rustc
+in their free time. This means that they can take some time to respond and review
+your PR. It also means that reviewers can miss some PRs that are assigned to them.
To try to move PRs forward, the Triage WG regularly goes through all PRs that +are waiting for review and haven't been discussed for at least 2 weeks. If you +don't get a review within 2 weeks, feel free to ask the Triage WG on +Zulip (#t-release/triage). They have knowledge of when to ping, who might be +on vacation, etc.
+The reviewer may request some changes using the GitHub code review interface. +They may also request special procedures for some PRs. +See Crater and Breaking Changes chapters for some examples of such procedures.
+CI
+In addition to being reviewed by a human, pull requests are automatically tested, +thanks to continuous integration (CI). Basically, every time you open and update +a pull request, CI builds the compiler and tests it against the +compiler test suite, and also performs other tests such as checking that +your pull request is in compliance with Rust's style guidelines.
+Running continuous integration tests allows PR authors to catch mistakes early +without going through a first review cycle, and also helps reviewers stay aware +of the status of a particular pull request.
+Rust has plenty of CI capacity, and you should never have to worry about wasting
+computational resources each time you push a change. It is also perfectly fine
+(and even encouraged!) to use the CI to test your changes if it can help your
+productivity. In particular, we don't recommend running the full ./x test suite locally,
+since it takes a very long time to execute.
r+
+After someone has reviewed your pull request, they will leave an annotation
+on the pull request with an r+. It will look something like this:
@bors r+
+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.
Depending on the scale of the change, you may see a slightly different form of r+:
@bors r+ rollup
+The additional rollup tells @bors that this change should always be "rolled up".
+Changes that are rolled up are tested and merged alongside other PRs, to
+speed the process up. Typically only small changes that are expected not to conflict
+with one another are marked as "always roll up".
Be patient; this can take a while and the queue can sometimes be long. PRs are never merged by hand.
+Opening a PR
+You are now ready to file a pull request? Great! Here are a few points you +should be aware of.
+All pull requests should be filed against the master branch,
+unless you know for sure that you should target a different branch.
Make sure your pull request is in compliance with Rust's style guidelines by running
+$ ./x test tidy --bless
+We recommend to make this check before every pull request (and every new commit +in a pull request); you can add git hooks +before every push to make sure you never forget to make this check. +The CI will also run tidy and will fail if tidy fails.
+Rust follows a no merge-commit policy, meaning, when you encounter merge
+conflicts you are expected to always rebase instead of merging. E.g. always use
+rebase when bringing the latest changes from the master 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:
@rustbot label -has-merge-commits
+See this chapter for more details.
+If you encounter merge conflicts or when a reviewer asks you to perform some
+changes, your PR will get marked as S-waiting-on-author. When you resolve
+them, you should use @rustbot to mark it as S-waiting-on-review:
@rustbot ready
+GitHub allows closing issues using keywords. This feature +should be used to keep the issue tracker tidy. However, it is generally preferred +to put the "closes #123" text in the PR description rather than the issue commit; +particularly during rebasing, citing the issue number in the commit can "spam" +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.
+Please update the PR description while still mentioning the issue somewhere.
+For example, you could write Fixes (after beta backport) #NNN..
As for further actions, please keep a sharp look-out for a PR whose title begins with
+[beta] or [stable] and which backports the PR in question. When that one gets
+merged, the relevant issue can be closed. The closing comment should mention all
+PRs that were involved. If you don't have the permissions to close the issue, please
+leave a comment on the original PR asking the reviewer to close it for you.
Reverting a PR
+When a PR leads to miscompile, significant performance regressions, or other critical issues, we may +want to revert that PR with a regression test case. You can also check out the revert policy on +Forge docs (which is mainly targeted for reviewers, but contains useful info for PR authors too).
+If the PR contains huge changes, it can be challenging to revert, making it harder to review +incremental fixes in subsequent updates. Or if certain code in that PR is heavily depended upon by +subsequent PRs, reverting it can become difficult.
+In such cases, we can identify the problematic code and disable it for some input, as shown in #128271.
+For MIR optimizations, we can also use the -Zunsound-mir-opt option to gate the mir-opt, as shown
+in #132356.
External dependencies
+This section has moved to "Using External Repositories".
+Writing documentation
+Documentation improvements are very welcome. The source of doc.rust-lang.org
+is located in src/doc in the tree, and standard API documentation is generated
+from the source code itself (e.g. library/std/src/lib.rs). Documentation pull requests
+function in the same way as other pull requests.
To find documentation-related issues, sort by the A-docs label.
+You can find documentation style guidelines in RFC 1574.
+To build the standard library documentation, use x doc --stage 0 library --open.
+To build the documentation for a book (e.g. the unstable book), use x doc src/doc/unstable-book.
+Results should appear in build/host/doc, as well as automatically open in your default browser.
+See Building Documentation for more
+information.
You can also use rustdoc directly to check small fixes. For example,
+rustdoc src/doc/reference.md will render reference to doc/reference.html.
+The CSS might be messed up, but you can verify that the HTML is right.
Contributing to rustc-dev-guide
+Contributions to the rustc-dev-guide are always welcome, and can be made directly at +the rust-lang/rustc-dev-guide repo. +The issue tracker in that repo is also a great way to find things that need doing. +There are issues for beginners and advanced compiler devs alike!
+Just a few things to keep in mind:
+-
+
-
+
Please try to avoid overly long lines and use semantic line breaks (where you break the line after each sentence). +There is no strict limit on line lengths; let the sentence or part of the sentence flow to its proper end on the same line.
+
+ -
+
When contributing text to the guide, please contextualize the information with some time period +and/or a reason so that the reader knows how much to trust or mistrust the information. +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.
+
+ -
+
The date the comment was added, e.g. instead of writing "Currently, ..." +or "As of now, ...", +consider adding the date, in one of the following formats:
+-
+
- Jan 2021 +
- January 2021 +
- jan 2021 +
- january 2021 +
There is a CI action (in
+~/.github/workflows/date-check.yml) +that generates a monthly showing those that are over 6 months old +(example).For the action to pick the date, +add a special annotation before specifying the date:
+
+<!-- date-check --> Sep 2024 +Example:
+
+As of <!-- date-check --> Sep 2024, the foo did the bar. +For cases where the date should not be part of the visible rendered output, +use the following instead:
+
+<!-- date-check: Sep 2024 --> +
+ -
+
A link to a relevant WG, tracking issue,
+rustcrustdoc page, or similar, that may provide +further explanation for the change process or a way to verify that the information is not +outdated.
+
+ -
+
-
+
If a text grows rather long (more than a few page scrolls) or complicated (more than four +subsections), +it might benefit from having a Table of Contents at the beginning, +which you can auto-generate by including the
+<!-- toc -->marker at the top.
+
Issue triage
+Sometimes, an issue will stay open, even though the bug has been fixed. +And sometimes, the original bug may go stale because something has changed in the meantime.
+It can be helpful to go through older bug reports and make sure that they are still valid. +Load up an older issue, double check that it's still true, +and leave a comment letting us know if it is or is not. +The least recently updated sort is good for finding issues like this.
+Thanks to @rustbot, anyone can help triage issues by adding
+appropriate labels to issues that haven't been triaged yet:
| Labels | Color | Description |
|---|---|---|
| A- | Yellow | The area of the project an issue relates to. |
| B- | Magenta | Issues which are blockers. |
| beta- | Dark Blue | Tracks changes which need to be backported to beta |
| C- | Light Purple | The category of an issue. |
| D- | Mossy Green | Issues for diagnostics. |
| E- | Green | The experience level necessary to fix an issue. |
| F- | Peach | Issues for nightly features. |
| I- | Red | The importance of the issue. |
| I-*-nominated | Red | The issue has been nominated for discussion at the next meeting of the corresponding team. |
| I-prioritize | Red | The issue has been nominated for prioritization by the team tagged with a T-prefixed label. |
| L- | Teal | The relevant lint. |
| metabug | Purple | Bugs that collect other bugs. |
| O- | Purple Grey | The operating system or platform that the issue is specific to. |
| P- | Orange | The issue priority. These labels can be assigned by anyone that understand the issue and is able to prioritize it, and remove the I-prioritize label. |
| regression- | Pink | Tracks regressions from a stable release. |
| relnotes | Light Orange | Changes that should be documented in the release notes of the next release. |
| S- | Gray | Tracks the status of pull requests. |
| S-tracking- | Steel Blue | Tracks the status of tracking issues. |
| stable- | Dark Blue | Tracks changes which need to be backported to stable in anticipation of a point release. |
| T- | Blue | Denotes which team the issue belongs to. |
| WG- | Green | Denotes which working group the issue belongs to. |
Rfcbot labels
+rfcbot uses its own labels for tracking the process of coordinating +asynchronous decisions, such as approving or rejecting a change. +This is used for RFCs, issues, and pull requests.
+| Labels | Color | Description |
|---|---|---|
| proposed-final-comment-period | Gray | Currently awaiting signoff of all team members in order to enter the final comment period. |
| disposition-merge | Green | Indicates the intent is to merge the change. |
| disposition-close | Red | Indicates the intent is to not accept the change and close it. |
| disposition-postpone | Gray | Indicates the intent is to not accept the change at this time and postpone it to a later date. |
| final-comment-period | Blue | Currently soliciting final comments before merging or closing. |
| finished-final-comment-period | Light Yellow | The final comment period has concluded, and the issue will be merged or closed. |
| postponed | Yellow | The issue has been postponed. |
| closed | Red | The issue has been rejected. |
| to-announce | Gray | Issues that have finished their final-comment-period and should be publicly announced. Note: the rust-lang/rust repository uses this label differently, to announce issues at the triage meetings. |
Helpful links and information
+This section has moved to the "About this guide" chapter.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/coroutine-closures.html b/coroutine-closures.html
new file mode 100644
index 000000000..ed6fea947
--- /dev/null
+++ b/coroutine-closures.html
@@ -0,0 +1,468 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ This file offers some tips on the coding conventions for rustc. This +chapter covers formatting, coding for correctness, +using crates from crates.io, and some tips on +structuring your PR for easy review.
+ +Formatting and the tidy script
+rustc is moving towards the Rust standard coding style.
+However, for now we don't use stable rustfmt; we use a pinned version with a
+special config, so this may result in different style from normal rustfmt.
+Therefore, formatting this repository using cargo fmt is not recommended.
Instead, formatting should be done using ./x fmt. It's a good habit to run
+./x fmt before every commit, as this reduces conflicts later.
Formatting is checked by the tidy script. It runs automatically when you do
+./x test and can be run in isolation with ./x fmt --check.
If you want to use format-on-save in your editor, the pinned version of
+rustfmt is built under build/<target>/stage0/bin/rustfmt. You'll have to
+pass the --edition=2021 argument yourself when calling
+rustfmt directly.
Formatting C++ code
+The compiler contains some C++ code for interfacing with parts of LLVM that +don't have a stable C API. +When modifying that code, use this command to format it:
+./x test tidy --extra-checks=cpp:fmt --bless
+This uses a pinned version of clang-format, to avoid relying on the local
+environment.
Copyright notice
+ +In the past, files began with a copyright and license notice. Please omit +this notice for new files licensed under the standard terms (dual +MIT/Apache-2.0).
+All of the copyright notices should be gone by now, but if you come across one +in the rust-lang/rust repo, feel free to open a PR to remove it.
+Line length
+Lines should be at most 100 characters. It's even better if you can +keep things to 80.
+Ignoring the line length limit. Sometimes – in particular for +tests – it can be necessary to exempt yourself from this limit. In +that case, you can add a comment towards the top of the file like so:
++#![allow(unused)] +fn main() { +// ignore-tidy-linelength +} +
Tabs vs spaces
+Prefer 4-space indent.
+ +Coding for correctness
+Beyond formatting, there are a few other tips that are worth +following.
+Prefer exhaustive matches
+Using _ in a match is convenient, but it means that when new
+variants are added to the enum, they may not get handled correctly.
+Ask yourself: if a new variant were added to this enum, what's the
+chance that it would want to use the _ code, versus having some
+other treatment? Unless the answer is "low", then prefer an
+exhaustive match. (The same advice applies to if let and while let, which are effectively tests for a single variant.)
Use "TODO" comments for things you don't want to forget
+As a useful tool to yourself, you can insert a // TODO comment
+for something that you want to get back to before you land your PR:
fn do_something() {
+ if something_else {
+ unimplemented!(); // TODO write this
+ }
+}
+The tidy script will report an error for a // TODO comment, so this
+code would not be able to land until the TODO is fixed (or removed).
This can also be useful in a PR as a way to signal from one commit that you are +leaving a bug that a later commit will fix:
+if foo {
+ return true; // TODO wrong, but will be fixed in a later commit
+}
+Using crates from crates.io
+See the crates.io dependencies section.
+ +How to structure your PR
+How you prepare the commits in your PR can make a big difference for the +reviewer. Here are some tips.
+Isolate "pure refactorings" into their own commit. For example, if +you rename a method, then put that rename into its own commit, along +with the renames of all the uses.
+More commits is usually better. If you are doing a large change, +it's almost always better to break it up into smaller steps that can +be independently understood. The one thing to be aware of is that if +you introduce some code following one strategy, then change it +dramatically (versus adding to it) in a later commit, that +'back-and-forth' can be confusing.
+Format liberally. While only the final commit of a PR must be correctly
+formatted, it is both easier to review and less noisy to format each commit
+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
+name rust-lang for your remote).
Individual commits do not have to build (but it's nice). We do not +require that every intermediate commit successfully builds – we only +expect to be able to bisect at a PR level. However, if you can make +individual commits build, that is always helpful.
+Naming conventions
+Apart from normal Rust style/naming conventions, there are also some specific +to the compiler.
+-
+
-
+
+cxtends to be short for "context" and is often used as a suffix. For +example,tcxis a common name for the Typing Context.
+ -
+
+'tcxis used as the lifetime name for the Typing Context.
+ -
+
Because
+crateis a keyword, if you need a variable to represent something +crate-related, often the spelling is changed tokrate.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/crates-io.html b/crates-io.html
new file mode 100644
index 000000000..834c01b7f
--- /dev/null
+++ b/crates-io.html
@@ -0,0 +1,220 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+The data we need to carry along to construct a
+When do async closures implement the regular
+By-move body +
+Follow-up: When do async closures implement the regular
+
+
+
+
+ Please read RFC 3668 to understand the general motivation of the feature. This is a very technical and somewhat "vertical" chapter; ideally we'd split this and sprinkle it across all the relevant chapters, but for the purposes of understanding async closures holistically, I've put this together all here in one chapter.
+Coroutine-closures -- a technical deep dive
+Coroutine-closures are a generalization of async closures, being special syntax for closure expressions which return a coroutine, notably one that is allowed to capture from the closure's upvars.
+For now, the only usable kind of coroutine-closure is the async closure, and supporting async closures is the extent of this PR. We may eventually support gen || {}, etc., and most of the problems and curiosities described in this document apply to all coroutine-closures in general.
As a consequence of the code being somewhat general, this document may flip between calling them "async closures" and "coroutine-closures". The future that is returned by the async closure will generally be called the "coroutine" or the "child coroutine".
+HIR
+Async closures (and in the future, other coroutine flavors such as gen) are represented in HIR as a hir::Closure whose closure-kind is ClosureKind::CoroutineClosure(_)1, which wraps an async block, which is also represented in HIR as a hir::Closure) and whose closure-kind is ClosureKind::Closure(CoroutineKind::Desugared(_, CoroutineSource::Closure))2.
Like async fn, when lowering an async closure's body, we need to unconditionally move all of the closures arguments into the body so they are captured. This is handled by lower_coroutine_body_with_moved_arguments3. The only notable quirk with this function is that the async block we end up generating as a capture kind of CaptureBy::ByRef4. We later force all of the closure args to be captured by-value5, but we don't want the whole async block to act as if it were an async move, since that would defeat the purpose of the self-borrowing of an async closure.
rustc_middle::ty Representation
+For the purposes of keeping the implementation mostly future-compatible (i.e. with gen || {} and async gen || {}), most of this section calls async closures "coroutine-closures".
The main thing that this PR introduces is a new TyKind called CoroutineClosure6 and corresponding variants on other relevant enums in typeck and borrowck (UpvarArgs, DefiningTy, AggregateKind).
We introduce a new TyKind instead of generalizing the existing TyKind::Closure due to major representational differences in the type. The major differences between CoroutineClosures can be explored by first inspecting the CoroutineClosureArgsParts, which is the "unpacked" representation of the coroutine-closure's generics.
Similarities to closures
+Like a closure, we have parent_args, a closure_kind_ty, and a tupled_upvars_ty. These represent the same thing as their closure counterparts; namely: the generics inherited from the body that the closure is defined in, the maximum "calling capability" of the closure (i.e. must it be consumed to be called, like FnOnce, or can it be called by-ref), and the captured upvars of the closure itself.
The signature
+A traditional closure has a fn_sig_as_fn_ptr_ty which it uses to represent the signature of the closure. In contrast, we store the signature of a coroutine closure in a somewhat "exploded" way, since coroutine-closures have two signatures depending on what AsyncFn* trait you call it with (see below sections).
Conceptually, the coroutine-closure may be thought as containing several different signature types depending on whether it is being called by-ref or by-move.
+To conveniently recreate both of these signatures, the signature_parts_ty stores all of the relevant parts of the coroutine returned by this coroutine-closure. This signature parts type will have the general shape of fn(tupled_inputs, resume_ty) -> (return_ty, yield_ty), where resume_ty, return_ty, and yield_ty are the respective types for the coroutine returned by the coroutine-closure7.
The compiler mainly deals with the CoroutineClosureSignature type8, which is created by extracting the relevant types out of the fn() ptr type described above, and which exposes methods that can be used to construct the coroutine that the coroutine-closure ultimately returns.
The data we need to carry along to construct a Coroutine return type
+Along with the data stored in the signature, to construct a TyKind::Coroutine to return, we also need to store the "witness" of the coroutine.
So what about the upvars of the Coroutine that is returned? Well, for AsyncFnOnce (i.e. call-by-move), this is simply the same upvars that the coroutine returns. But for AsyncFnMut/AsyncFn, the coroutine that is returned from the coroutine-closure borrows data from the coroutine-closure with a given "environment" lifetime9. This corresponds to the &self lifetime10 on the AsyncFnMut/AsyncFn call signature, and the GAT lifetime of the ByRef11.
Actually getting the coroutine return type(s)
+To most easily construct the Coroutine that a coroutine-closure returns, you can use the to_coroutine_given_kind_and_upvars12 helper on CoroutineClosureSignature, which can be acquired from the CoroutineClosureArgs.
Most of the args to that function will be components that you can get out of the CoroutineArgs, except for the goal_kind: ClosureKind which controls which flavor of coroutine to return based off of the ClosureKind passed in -- i.e. it will prepare the by-ref coroutine if ClosureKind::Fn | ClosureKind::FnMut, and the by-move coroutine if ClosureKind::FnOnce.
Trait Hierarchy
+We introduce a parallel hierarchy of Fn* traits that are implemented for . The motivation for the introduction was covered in a blog post: Async Closures.
All currently-stable callable types (i.e., closures, function items, function pointers, and dyn Fn* trait objects) automatically implement AsyncFn*() -> T if they implement Fn*() -> Fut for some output type Fut, and Fut implements Future<Output = T>13.
Async closures implement AsyncFn* as their bodies permit; i.e. if they end up using upvars in a way that is compatible (i.e. if they consume or mutate their upvars, it may affect whether they implement AsyncFn and AsyncFnMut...)
Lending
+We may in the future move AsyncFn* onto a more general set of LendingFn* traits; however, there are some concrete technical implementation details that limit our ability to use LendingFn ergonomically in the compiler today. These have to do with:
-
+
- Closure signature inference. +
- Limitations around higher-ranked trait bounds. +
- Shortcomings with error messages. +
These limitations, plus the fact that the underlying trait should have no effect on the user experience of async closures and async Fn trait bounds, leads us to AsyncFn* for now. To ensure we can eventually move to these more general traits, the precise AsyncFn* trait definitions (including the associated types) are left as an implementation detail.
When do async closures implement the regular Fn* traits?
+We mention above that "regular" callable types can implement AsyncFn*, but the reverse question exists of "can async closures implement Fn* too"? The short answer is "when it's valid", i.e. when the coroutine that would have been returned from AsyncFn/AsyncFnMut does not actually have any upvars that are "lent" from the parent coroutine-closure.
See the "follow-up: when do..." section below for an elaborated answer. The full answer describes a pretty interesting and hopefully thorough heuristic that is used to ensure that most async closures "just work".
+Tale of two bodies...
+When async closures are called with AsyncFn/AsyncFnMut, they return a coroutine that borrows from the closure. However, when they are called via AsyncFnOnce, we consume that closure, and cannot return a coroutine that borrows from data that is now dropped.
To work around around this limitation, we synthesize a separate by-move MIR body for calling AsyncFnOnce::call_once on a coroutine-closure that can be called by-ref.
This body operates identically to the "normal" coroutine returned from calling the coroutine-closure, except for the fact that it has a different set of upvars, since we must move the captures from the parent coroutine-closure into the child coroutine.
+Synthesizing the by-move body
+When we want to access the by-move body of the coroutine returned by a coroutine-closure, we can do so via the coroutine_by_move_body_def_id14 query.
This query synthesizes a new MIR body by copying the MIR body of the coroutine and inserting additional derefs and field projections15 to preserve the semantics of the body.
+ +Since we've synthesized a new def id, this query is also responsible for feeding a ton of other relevant queries for the MIR body. This query is ensure()d16 during the mir_promoted query, since it operates on the built mir of the coroutine.
Closure signature inference
+The closure signature inference algorithm for async closures is a bit more complicated than the inference algorithm for "traditional" closures. Like closures, we iterate through all of the clauses that may be relevant (for the expectation type passed in)17.
+To extract a signature, we consider two situations:
+-
+
- Projection predicates with
AsyncFnOnce::Output, which we will use to extract the inputs and output type for the closure. This corresponds to the situation that there was aF: AsyncFn*() -> Tbound18.
+ - Projection predicates with
FnOnce::Output, which we will use to extract the inputs. For the output, we also try to deduce an output by looking for relevantFuture::Outputprojection predicates. This corresponds to the situation that there was anF: Fn*() -> T, T: Future<Output = U>bound.19 +-
+
- If there is no
Futurebound, we simply use a fresh infer var for the output. This corresponds to the case where one can pass an async closure to a combinator function likeOption::map.20
+
+ - If there is no
We support the latter case simply to make it easier for users to simply drop-in async || {} syntax, even when they're calling an API that was designed before first-class AsyncFn* traits were available.
Calling a closure before its kind has been inferred
+We defer21 the computation of a coroutine-closure's "kind" (i.e. its maximum calling mode: AsyncFnOnce/AsyncFnMut/AsyncFn) until the end of typeck. However, since we want to be able to call that coroutine-closure before the end of typeck, we need to come up with the return type of the coroutine-closure before that.
Unlike regular closures, whose return type does not change depending on what Fn* trait we call it with, coroutine-closures do end up returning different coroutine types depending on the flavor of AsyncFn* trait used to call it.
Specifically, while the def-id of the returned coroutine does not change, the upvars22 (which are either borrowed or moved from the parent coroutine-closure) and the coroutine-kind23 are dependent on the calling mode.
+ + +We introduce a AsyncFnKindHelper trait which allows us to defer the question of "does this coroutine-closure support this calling mode"24 via a trait goal, and "what are the tupled upvars of this calling mode"25 via an associated type, which can be computed by appending the input types of the coroutine-closure to either the upvars or the "by ref" upvars computed during upvar analysis.
Ok, so why?
+This seems a bit roundabout and complex, and I admit that it is. But let's think of the "do nothing" alternative -- we could instead mark all AsyncFn* goals as ambiguous until upvar analysis, at which point we would know exactly what to put into the upvars of the coroutine we return. However, this is actually very detrimental to inference in the program, since it means that programs like this would not be valid:
+#![allow(unused)] +fn main() { +let c = async || -> String { .. }; +let s = c().await; +// ^^^ If we can't project `<{c} as AsyncFn>::call()` to a coroutine, then the `IntoFuture::into_future` call inside of the `.await` stalls, and the type of `s` is left unconstrained as an infer var. +s.as_bytes(); +// ^^^ That means we can't call any methods on the awaited return of a coroutine-closure, like... at all! +} +
So instead, we use this alias (in this case, a projection: AsyncFnKindHelper::Upvars<'env, ...>) to delay the computation of the tupled upvars and give us something to put in its place, while still allowing us to return a TyKind::Coroutine (which is a rigid type) and we may successfully confirm the built-in traits we need (in our case, Future), since the Future implementation doesn't depend on the upvars at all.
Upvar analysis
+By and large, the upvar analysis for coroutine-closures and their child coroutines proceeds like normal upvar analysis. However, there are several interesting bits that happen to account for async closures' special natures:
+Forcing all inputs to be captured
+Like async fn, all input arguments are captured. We explicitly force26 all of these inputs to be captured by move so that the future coroutine returned by async closures does not depend on whether the input is used by the body or not, which would impart an interesting semver hazard.
+ +Computing the by-ref captures
+For a coroutine-closure that supports AsyncFn/AsyncFnMut, we must also compute the relationship between the captures of the coroutine-closure and its child coroutine. Specifically, the coroutine-closure may move a upvar into its captures, but the coroutine may only borrow that upvar.
We compute the "coroutine_captures_by_ref_ty" by looking at all of the child coroutine's captures and comparing them to the corresponding capture of the parent coroutine-closure27. This coroutine_captures_by_ref_ty ends up being represented as a for<'env> fn() -> captures... type, with the additional binder lifetime representing the "&self" lifetime of calling AsyncFn::async_call or AsyncFnMut::async_call_mut. We instantiate that binder later when actually calling the methods.
Note that not every by-ref capture from the parent coroutine-closure results in a "lending" borrow. See the Follow-up: When do async closures implement the regular Fn* traits? section below for more details, since this intimately influences whether or not the coroutine-closure is allowed to implement the Fn* family of traits.
By-move body + FnOnce quirk
+There are several situations where the closure upvar analysis ends up inferring upvars for the coroutine-closure's child coroutine that are too relaxed, and end up resulting in borrow-checker errors. This is best illustrated via examples. For example, given:
++#![allow(unused)] +fn main() { +fn force_fnonce<T: async FnOnce()>(t: T) -> T { t } + +let x = String::new(); +let c = force_fnonce(async move || { + println!("{x}"); +}); +} +
x will be moved into the coroutine-closure, but the coroutine that is returned would only borrow &x. However, since force_fnonce forces the coroutine-closure to AsyncFnOnce, which is not lending, we must force the capture to happen by-move28.
Similarly:
++#![allow(unused)] +fn main() { +let x = String::new(); +let y = String::new(); +let c = async move || { + drop(y); + println!("{x}"); +}; +} +
x will be moved into the coroutine-closure, but the coroutine that is returned would only borrow &x. However, since we also capture y and drop it, the coroutine-closure is forced to be AsyncFnOnce. We must also force the capture of x to happen by-move. To determine this situation in particular, since unlike the last example the coroutine-kind's closure-kind has not yet been constrained, we must analyze the body of the coroutine-closure to see if how all of the upvars are used, to determine if they've been used in a way that is "consuming" -- i.e. that would force it to FnOnce29.
Follow-up: When do async closures implement the regular Fn* traits?
+Well, first of all, all async closures implement FnOnce since they can always be called at least once.
For Fn/FnMut, the detailed answer involves answering a related question: is the coroutine-closure lending? Because if it is, then it cannot implement the non-lending Fn/FnMut traits.
Determining when the coroutine-closure must lend its upvars is implemented in the should_reborrow_from_env_of_parent_coroutine_closure helper function30. Specifically, this needs to happen in two places:
-
+
- Are we borrowing data owned by the parent closure? We can determine if that is the case by checking if the parent capture is by-move, EXCEPT if we apply a deref projection, which means we're reborrowing a reference that we captured by-move. +
+#![allow(unused)] +fn main() { +let x = &1i32; // Let's call this lifetime `'1`. +let c = async move || { + println!("{:?}", *x); + // Even though the inner coroutine borrows by ref, we're only capturing `*x`, + // not `x`, so the inner closure is allowed to reborrow the data for `'1`. +}; +} +
-
+
- If a coroutine is mutably borrowing from a parent capture, then that mutable borrow cannot live for longer than either the parent or the borrow that we have on the original upvar. Therefore we always need to borrow the child capture with the lifetime of the parent coroutine-closure's env. +
+#![allow(unused)] +fn main() { +let mut x = 1i32; +let c = async || { + x = 1; + // The parent borrows `x` for some `&'1 mut i32`. + // However, when we call `c()`, we implicitly autoref for the signature of + // `AsyncFnMut::async_call_mut`. Let's call that lifetime `'call`. Since + // the maximum that `&'call mut &'1 mut i32` can be reborrowed is `&'call mut i32`, + // the inner coroutine should capture w/ the lifetime of the coroutine-closure. +}; +} +
If either of these cases apply, then we should capture the borrow with the lifetime of the parent coroutine-closure's env. Luckily, if this function is not correct, then the program is not unsound, since we still borrowck and validate the choices made from this function -- the only side-effect is that the user may receive unnecessary borrowck errors.
+Instance resolution
+If a coroutine-closure has a closure-kind of FnOnce, then its AsyncFnOnce::call_once and FnOnce::call_once implementations resolve to the coroutine-closure's body31, and the Future::poll of the coroutine that gets returned resolves to the body of the child closure.
If a coroutine-closure has a closure-kind of FnMut/Fn, then the same applies to AsyncFn and the corresponding Future implementation of the coroutine that gets returned.31 However, we use a MIR shim to generate the implementation of AsyncFnOnce::call_once/FnOnce::call_once32, and Fn::call/FnMut::call_mut instances if they exist33.
This is represented by the ConstructCoroutineInClosureShim34. The receiver_by_ref bool will be true if this is the instance of Fn::call/FnMut::call_mut.35 The coroutine that all of these instances returns corresponds to the by-move body we will have synthesized by this point.36
Borrow-checking
+It turns out that borrow-checking async closures is pretty straightforward. After adding a new DefiningTy::CoroutineClosure37 variant, and teaching borrowck how to generate the signature of the coroutine-closure38, borrowck proceeds totally fine.
One thing to note is that we don't borrow-check the synthetic body we make for by-move coroutines, since by construction (and the validity of the by-ref coroutine body it was derived from) it must be valid.
+ + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/css/chrome.css b/css/chrome.css
new file mode 100644
index 000000000..10fa4b365
--- /dev/null
+++ b/css/chrome.css
@@ -0,0 +1,534 @@
+/* CSS for UI elements (a.k.a. chrome) */
+
+@import 'variables.css';
+
+::-webkit-scrollbar {
+ background: var(--bg);
+}
+::-webkit-scrollbar-thumb {
+ background: var(--scrollbar);
+}
+html {
+ scrollbar-color: var(--scrollbar) var(--bg);
+}
+#searchresults a,
+.content a:link,
+a:visited,
+a > .hljs {
+ color: var(--links);
+}
+
+/* Menu Bar */
+
+#menu-bar,
+#menu-bar-hover-placeholder {
+ z-index: 101;
+ margin: auto calc(0px - var(--page-padding));
+}
+#menu-bar {
+ position: relative;
+ display: flex;
+ flex-wrap: wrap;
+ background-color: var(--bg);
+ border-bottom-color: var(--bg);
+ border-bottom-width: 1px;
+ border-bottom-style: solid;
+}
+#menu-bar.sticky,
+.js #menu-bar-hover-placeholder:hover + #menu-bar,
+.js #menu-bar:hover,
+.js.sidebar-visible #menu-bar {
+ position: -webkit-sticky;
+ position: sticky;
+ top: 0 !important;
+}
+#menu-bar-hover-placeholder {
+ position: sticky;
+ position: -webkit-sticky;
+ top: 0;
+ height: var(--menu-bar-height);
+}
+#menu-bar.bordered {
+ border-bottom-color: var(--table-border-color);
+}
+#menu-bar i, #menu-bar .icon-button {
+ position: relative;
+ padding: 0 8px;
+ z-index: 10;
+ line-height: var(--menu-bar-height);
+ cursor: pointer;
+ transition: color 0.5s;
+}
+@media only screen and (max-width: 420px) {
+ #menu-bar i, #menu-bar .icon-button {
+ padding: 0 5px;
+ }
+}
+
+.icon-button {
+ border: none;
+ background: none;
+ padding: 0;
+ color: inherit;
+}
+.icon-button i {
+ margin: 0;
+}
+
+.right-buttons {
+ margin: 0 15px;
+}
+.right-buttons a {
+ text-decoration: none;
+}
+
+.left-buttons {
+ display: flex;
+ margin: 0 5px;
+}
+.no-js .left-buttons {
+ display: none;
+}
+
+.menu-title {
+ display: inline-block;
+ font-weight: 200;
+ font-size: 2.4rem;
+ line-height: var(--menu-bar-height);
+ text-align: center;
+ margin: 0;
+ flex: 1;
+ white-space: nowrap;
+ overflow: hidden;
+ text-overflow: ellipsis;
+}
+.js .menu-title {
+ cursor: pointer;
+}
+
+.menu-bar,
+.menu-bar:visited,
+.nav-chapters,
+.nav-chapters:visited,
+.mobile-nav-chapters,
+.mobile-nav-chapters:visited,
+.menu-bar .icon-button,
+.menu-bar a i {
+ color: var(--icons);
+}
+
+.menu-bar i:hover,
+.menu-bar .icon-button:hover,
+.nav-chapters:hover,
+.mobile-nav-chapters i:hover {
+ color: var(--icons-hover);
+}
+
+/* Nav Icons */
+
+.nav-chapters {
+ font-size: 2.5em;
+ text-align: center;
+ text-decoration: none;
+
+ position: fixed;
+ top: 0;
+ bottom: 0;
+ margin: 0;
+ max-width: 150px;
+ min-width: 90px;
+
+ display: flex;
+ justify-content: center;
+ align-content: center;
+ flex-direction: column;
+
+ transition: color 0.5s, background-color 0.5s;
+}
+
+.nav-chapters:hover {
+ text-decoration: none;
+ background-color: var(--theme-hover);
+ transition: background-color 0.15s, color 0.15s;
+}
+
+.nav-wrapper {
+ margin-top: 50px;
+ display: none;
+}
+
+.mobile-nav-chapters {
+ font-size: 2.5em;
+ text-align: center;
+ text-decoration: none;
+ width: 90px;
+ border-radius: 5px;
+ background-color: var(--sidebar-bg);
+}
+
+.previous {
+ float: left;
+}
+
+.next {
+ float: right;
+ right: var(--page-padding);
+}
+
+@media only screen and (max-width: 1080px) {
+ .nav-wide-wrapper { display: none; }
+ .nav-wrapper { display: block; }
+}
+
+@media only screen and (max-width: 1380px) {
+ .sidebar-visible .nav-wide-wrapper { display: none; }
+ .sidebar-visible .nav-wrapper { display: block; }
+}
+
+/* Inline code */
+
+:not(pre) > .hljs {
+ display: inline;
+ padding: 0.1em 0.3em;
+ border-radius: 3px;
+}
+
+:not(pre):not(a) > .hljs {
+ color: var(--inline-code-color);
+ overflow-x: initial;
+}
+
+a:hover > .hljs {
+ text-decoration: underline;
+}
+
+pre {
+ position: relative;
+}
+pre > .buttons {
+ position: absolute;
+ z-index: 100;
+ right: 0px;
+ top: 2px;
+ margin: 0px;
+ padding: 2px 0px;
+
+ color: var(--sidebar-fg);
+ cursor: pointer;
+ visibility: hidden;
+ opacity: 0;
+ transition: visibility 0.1s linear, opacity 0.1s linear;
+}
+pre:hover > .buttons {
+ visibility: visible;
+ opacity: 1
+}
+pre > .buttons :hover {
+ color: var(--sidebar-active);
+ border-color: var(--icons-hover);
+ background-color: var(--theme-hover);
+}
+pre > .buttons i {
+ margin-left: 8px;
+}
+pre > .buttons button {
+ cursor: inherit;
+ margin: 0px 5px;
+ padding: 3px 5px;
+ font-size: 14px;
+
+ border-style: solid;
+ border-width: 1px;
+ border-radius: 4px;
+ border-color: var(--icons);
+ background-color: var(--theme-popup-bg);
+ transition: 100ms;
+ transition-property: color,border-color,background-color;
+ color: var(--icons);
+}
+@media (pointer: coarse) {
+ pre > .buttons button {
+ /* On mobile, make it easier to tap buttons. */
+ padding: 0.3rem 1rem;
+ }
+}
+pre > code {
+ padding: 1rem;
+}
+
+/* FIXME: ACE editors overlap their buttons because ACE does absolute
+ positioning within the code block which breaks padding. The only solution I
+ can think of is to move the padding to the outer pre tag (or insert a div
+ wrapper), but that would require fixing a whole bunch of CSS rules.
+*/
+.hljs.ace_editor {
+ padding: 0rem 0rem;
+}
+
+pre > .result {
+ margin-top: 10px;
+}
+
+/* Search */
+
+#searchresults a {
+ text-decoration: none;
+}
+
+mark {
+ border-radius: 2px;
+ padding: 0 3px 1px 3px;
+ margin: 0 -3px -1px -3px;
+ background-color: var(--search-mark-bg);
+ transition: background-color 300ms linear;
+ cursor: pointer;
+}
+
+mark.fade-out {
+ background-color: rgba(0,0,0,0) !important;
+ cursor: auto;
+}
+
+.searchbar-outer {
+ margin-left: auto;
+ margin-right: auto;
+ max-width: var(--content-max-width);
+}
+
+#searchbar {
+ width: 100%;
+ margin: 5px auto 0px auto;
+ padding: 10px 16px;
+ transition: box-shadow 300ms ease-in-out;
+ border: 1px solid var(--searchbar-border-color);
+ border-radius: 3px;
+ background-color: var(--searchbar-bg);
+ color: var(--searchbar-fg);
+}
+#searchbar:focus,
+#searchbar.active {
+ box-shadow: 0 0 3px var(--searchbar-shadow-color);
+}
+
+.searchresults-header {
+ font-weight: bold;
+ font-size: 1em;
+ padding: 18px 0 0 5px;
+ color: var(--searchresults-header-fg);
+}
+
+.searchresults-outer {
+ margin-left: auto;
+ margin-right: auto;
+ max-width: var(--content-max-width);
+ border-bottom: 1px dashed var(--searchresults-border-color);
+}
+
+ul#searchresults {
+ list-style: none;
+ padding-left: 20px;
+}
+ul#searchresults li {
+ margin: 10px 0px;
+ padding: 2px;
+ border-radius: 2px;
+}
+ul#searchresults li.focus {
+ background-color: var(--searchresults-li-bg);
+}
+ul#searchresults span.teaser {
+ display: block;
+ clear: both;
+ margin: 5px 0 0 20px;
+ font-size: 0.8em;
+}
+ul#searchresults span.teaser em {
+ font-weight: bold;
+ font-style: normal;
+}
+
+/* Sidebar */
+
+.sidebar {
+ position: fixed;
+ left: 0;
+ top: 0;
+ bottom: 0;
+ width: var(--sidebar-width);
+ font-size: 0.875em;
+ box-sizing: border-box;
+ -webkit-overflow-scrolling: touch;
+ overscroll-behavior-y: contain;
+ background-color: var(--sidebar-bg);
+ color: var(--sidebar-fg);
+}
+.sidebar-resizing {
+ -moz-user-select: none;
+ -webkit-user-select: none;
+ -ms-user-select: none;
+ user-select: none;
+}
+.js:not(.sidebar-resizing) .sidebar {
+ transition: transform 0.3s; /* Animation: slide away */
+}
+.sidebar code {
+ line-height: 2em;
+}
+.sidebar .sidebar-scrollbox {
+ overflow-y: auto;
+ position: absolute;
+ top: 0;
+ bottom: 0;
+ left: 0;
+ right: 0;
+ padding: 10px 10px;
+}
+.sidebar .sidebar-resize-handle {
+ position: absolute;
+ cursor: col-resize;
+ width: 0;
+ right: 0;
+ top: 0;
+ bottom: 0;
+}
+.js .sidebar .sidebar-resize-handle {
+ cursor: col-resize;
+ width: 5px;
+}
+.sidebar-hidden .sidebar {
+ transform: translateX(calc(0px - var(--sidebar-width)));
+}
+.sidebar::-webkit-scrollbar {
+ background: var(--sidebar-bg);
+}
+.sidebar::-webkit-scrollbar-thumb {
+ background: var(--scrollbar);
+}
+
+.sidebar-visible .page-wrapper {
+ transform: translateX(var(--sidebar-width));
+}
+@media only screen and (min-width: 620px) {
+ .sidebar-visible .page-wrapper {
+ transform: none;
+ margin-left: var(--sidebar-width);
+ }
+}
+
+.chapter {
+ list-style: none outside none;
+ padding-left: 0;
+ line-height: 2.2em;
+}
+
+.chapter ol {
+ width: 100%;
+}
+
+.chapter li {
+ display: flex;
+ color: var(--sidebar-non-existant);
+}
+.chapter li a {
+ display: block;
+ padding: 0;
+ text-decoration: none;
+ color: var(--sidebar-fg);
+}
+
+.chapter li a:hover {
+ color: var(--sidebar-active);
+}
+
+.chapter li a.active {
+ color: var(--sidebar-active);
+}
+
+.chapter li > a.toggle {
+ cursor: pointer;
+ display: block;
+ margin-left: auto;
+ padding: 0 10px;
+ user-select: none;
+ opacity: 0.68;
+}
+
+.chapter li > a.toggle div {
+ transition: transform 0.5s;
+}
+
+/* collapse the section */
+.chapter li:not(.expanded) + li > ol {
+ display: none;
+}
+
+.chapter li.chapter-item {
+ line-height: 1.5em;
+ margin-top: 0.6em;
+}
+
+.chapter li.expanded > a.toggle div {
+ transform: rotate(90deg);
+}
+
+.spacer {
+ width: 100%;
+ height: 3px;
+ margin: 5px 0px;
+}
+.chapter .spacer {
+ background-color: var(--sidebar-spacer);
+}
+
+@media (-moz-touch-enabled: 1), (pointer: coarse) {
+ .chapter li a { padding: 5px 0; }
+ .spacer { margin: 10px 0; }
+}
+
+.section {
+ list-style: none outside none;
+ padding-left: 20px;
+ line-height: 1.9em;
+}
+
+/* Theme Menu Popup */
+
+.theme-popup {
+ position: absolute;
+ left: 10px;
+ top: var(--menu-bar-height);
+ z-index: 1000;
+ border-radius: 4px;
+ font-size: 0.7em;
+ color: var(--fg);
+ background: var(--theme-popup-bg);
+ border: 1px solid var(--theme-popup-border);
+ margin: 0;
+ padding: 0;
+ list-style: none;
+ display: none;
+}
+.theme-popup .default {
+ color: var(--icons);
+}
+.theme-popup .theme {
+ width: 100%;
+ border: 0;
+ margin: 0;
+ padding: 2px 10px;
+ line-height: 25px;
+ white-space: nowrap;
+ text-align: left;
+ cursor: pointer;
+ color: inherit;
+ background: inherit;
+ font-size: inherit;
+}
+.theme-popup .theme:hover {
+ background-color: var(--theme-hover);
+}
+.theme-popup .theme:hover:first-child,
+.theme-popup .theme:hover:last-child {
+ border-top-left-radius: inherit;
+ border-top-right-radius: inherit;
+}
diff --git a/css/general.css b/css/general.css
new file mode 100644
index 000000000..0e4f07a50
--- /dev/null
+++ b/css/general.css
@@ -0,0 +1,191 @@
+/* Base styles and content styles */
+
+@import 'variables.css';
+
+:root {
+ /* Browser default font-size is 16px, this way 1 rem = 10px */
+ font-size: 62.5%;
+}
+
+html {
+ font-family: "Open Sans", sans-serif;
+ color: var(--fg);
+ background-color: var(--bg);
+ text-size-adjust: none;
+ -webkit-text-size-adjust: none;
+}
+
+body {
+ margin: 0;
+ font-size: 1.6rem;
+ overflow-x: hidden;
+}
+
+code {
+ font-family: "Source Code Pro", Consolas, "Ubuntu Mono", Menlo, "DejaVu Sans Mono", monospace, monospace !important;
+ font-size: 0.875em; /* please adjust the ace font size accordingly in editor.js */
+}
+
+/* make long words/inline code not x overflow */
+main {
+ overflow-wrap: break-word;
+}
+
+/* make wide tables scroll if they overflow */
+.table-wrapper {
+ overflow-x: auto;
+}
+
+/* Don't change font size in headers. */
+h1 code, h2 code, h3 code, h4 code, h5 code, h6 code {
+ font-size: unset;
+}
+
+.left { float: left; }
+.right { float: right; }
+.boring { opacity: 0.6; }
+.hide-boring .boring { display: none; }
+.hidden { display: none !important; }
+
+h2, h3 { margin-top: 2.5em; }
+h4, h5 { margin-top: 2em; }
+
+.header + .header h3,
+.header + .header h4,
+.header + .header h5 {
+ margin-top: 1em;
+}
+
+h1:target::before,
+h2:target::before,
+h3:target::before,
+h4:target::before,
+h5:target::before,
+h6:target::before {
+ display: inline-block;
+ content: "»";
+ margin-left: -30px;
+ width: 30px;
+}
+
+/* This is broken on Safari as of version 14, but is fixed
+ in Safari Technology Preview 117 which I think will be Safari 14.2.
+ https://bugs.webkit.org/show_bug.cgi?id=218076
+*/
+:target {
+ scroll-margin-top: calc(var(--menu-bar-height) + 0.5em);
+}
+
+.page {
+ outline: 0;
+ padding: 0 var(--page-padding);
+ margin-top: calc(0px - var(--menu-bar-height)); /* Compensate for the #menu-bar-hover-placeholder */
+}
+.page-wrapper {
+ box-sizing: border-box;
+}
+.js:not(.sidebar-resizing) .page-wrapper {
+ transition: margin-left 0.3s ease, transform 0.3s ease; /* Animation: slide away */
+}
+
+.content {
+ overflow-y: auto;
+ padding: 0 5px 50px 5px;
+}
+.content main {
+ margin-left: auto;
+ margin-right: auto;
+ max-width: var(--content-max-width);
+}
+.content p { line-height: 1.45em; }
+.content ol { line-height: 1.45em; }
+.content ul { line-height: 1.45em; }
+.content a { text-decoration: none; }
+.content a:hover { text-decoration: underline; }
+.content img, .content video { max-width: 100%; }
+.content .header:link,
+.content .header:visited {
+ color: var(--fg);
+}
+.content .header:link,
+.content .header:visited:hover {
+ text-decoration: none;
+}
+
+table {
+ margin: 0 auto;
+ border-collapse: collapse;
+}
+table td {
+ padding: 3px 20px;
+ border: 1px var(--table-border-color) solid;
+}
+table thead {
+ background: var(--table-header-bg);
+}
+table thead td {
+ font-weight: 700;
+ border: none;
+}
+table thead th {
+ padding: 3px 20px;
+}
+table thead tr {
+ border: 1px var(--table-header-bg) solid;
+}
+/* Alternate background colors for rows */
+table tbody tr:nth-child(2n) {
+ background: var(--table-alternate-bg);
+}
+
+
+blockquote {
+ margin: 20px 0;
+ padding: 0 20px;
+ color: var(--fg);
+ background-color: var(--quote-bg);
+ border-top: .1em solid var(--quote-border);
+ border-bottom: .1em solid var(--quote-border);
+}
+
+
+:not(.footnote-definition) + .footnote-definition,
+.footnote-definition + :not(.footnote-definition) {
+ margin-top: 2em;
+}
+.footnote-definition {
+ font-size: 0.9em;
+ margin: 0.5em 0;
+}
+.footnote-definition p {
+ display: inline;
+}
+
+.tooltiptext {
+ position: absolute;
+ visibility: hidden;
+ color: #fff;
+ background-color: #333;
+ transform: translateX(-50%); /* Center by moving tooltip 50% of its width left */
+ left: -8px; /* Half of the width of the icon */
+ top: -35px;
+ font-size: 0.8em;
+ text-align: center;
+ border-radius: 6px;
+ padding: 5px 8px;
+ margin: 5px;
+ z-index: 1000;
+}
+.tooltipped .tooltiptext {
+ visibility: visible;
+}
+
+.chapter li.part-title {
+ color: var(--sidebar-fg);
+ margin: 5px 0px;
+ font-weight: bold;
+}
+
+.result-no-output {
+ font-style: italic;
+}
diff --git a/css/print.css b/css/print.css
new file mode 100644
index 000000000..5e690f755
--- /dev/null
+++ b/css/print.css
@@ -0,0 +1,54 @@
+
+#sidebar,
+#menu-bar,
+.nav-chapters,
+.mobile-nav-chapters {
+ display: none;
+}
+
+#page-wrapper.page-wrapper {
+ transform: none;
+ margin-left: 0px;
+ overflow-y: initial;
+}
+
+#content {
+ max-width: none;
+ margin: 0;
+ padding: 0;
+}
+
+.page {
+ overflow-y: initial;
+}
+
+code {
+ background-color: #666666;
+ border-radius: 5px;
+
+ /* Force background to be printed in Chrome */
+ -webkit-print-color-adjust: exact;
+}
+
+pre > .buttons {
+ z-index: 2;
+}
+
+a, a:visited, a:active, a:hover {
+ color: #4183c4;
+ text-decoration: none;
+}
+
+h1, h2, h3, h4, h5, h6 {
+ page-break-inside: avoid;
+ page-break-after: avoid;
+}
+
+pre, code {
+ page-break-inside: avoid;
+ white-space: pre-wrap;
+}
+
+.fa {
+ display: none !important;
+}
diff --git a/css/variables.css b/css/variables.css
new file mode 100644
index 000000000..56b634bc3
--- /dev/null
+++ b/css/variables.css
@@ -0,0 +1,253 @@
+
+/* Globals */
+
+:root {
+ --sidebar-width: 300px;
+ --page-padding: 15px;
+ --content-max-width: 750px;
+ --menu-bar-height: 50px;
+}
+
+/* Themes */
+
+.ayu {
+ --bg: hsl(210, 25%, 8%);
+ --fg: #c5c5c5;
+
+ --sidebar-bg: #14191f;
+ --sidebar-fg: #c8c9db;
+ --sidebar-non-existant: #5c6773;
+ --sidebar-active: #ffb454;
+ --sidebar-spacer: #2d334f;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #737480;
+ --icons-hover: #b7b9cc;
+
+ --links: #0096cf;
+
+ --inline-code-color: #ffb454;
+
+ --theme-popup-bg: #14191f;
+ --theme-popup-border: #5c6773;
+ --theme-hover: #191f26;
+
+ --quote-bg: hsl(226, 15%, 17%);
+ --quote-border: hsl(226, 15%, 22%);
+
+ --table-border-color: hsl(210, 25%, 13%);
+ --table-header-bg: hsl(210, 25%, 28%);
+ --table-alternate-bg: hsl(210, 25%, 11%);
+
+ --searchbar-border-color: #848484;
+ --searchbar-bg: #424242;
+ --searchbar-fg: #fff;
+ --searchbar-shadow-color: #d4c89f;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #888;
+ --searchresults-li-bg: #252932;
+ --search-mark-bg: #e3b171;
+}
+
+.coal {
+ --bg: hsl(200, 7%, 8%);
+ --fg: #98a3ad;
+
+ --sidebar-bg: #292c2f;
+ --sidebar-fg: #a1adb8;
+ --sidebar-non-existant: #505254;
+ --sidebar-active: #3473ad;
+ --sidebar-spacer: #393939;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #43484d;
+ --icons-hover: #b3c0cc;
+
+ --links: #2b79a2;
+
+ --inline-code-color: #c5c8c6;
+
+ --theme-popup-bg: #141617;
+ --theme-popup-border: #43484d;
+ --theme-hover: #1f2124;
+
+ --quote-bg: hsl(234, 21%, 18%);
+ --quote-border: hsl(234, 21%, 23%);
+
+ --table-border-color: hsl(200, 7%, 13%);
+ --table-header-bg: hsl(200, 7%, 28%);
+ --table-alternate-bg: hsl(200, 7%, 11%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #b7b7b7;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #98a3ad;
+ --searchresults-li-bg: #2b2b2f;
+ --search-mark-bg: #355c7d;
+}
+
+.light {
+ --bg: hsl(0, 0%, 100%);
+ --fg: hsl(0, 0%, 0%);
+
+ --sidebar-bg: #fafafa;
+ --sidebar-fg: hsl(0, 0%, 0%);
+ --sidebar-non-existant: #aaaaaa;
+ --sidebar-active: #1f1fff;
+ --sidebar-spacer: #f4f4f4;
+
+ --scrollbar: #8F8F8F;
+
+ --icons: #747474;
+ --icons-hover: #000000;
+
+ --links: #20609f;
+
+ --inline-code-color: #301900;
+
+ --theme-popup-bg: #fafafa;
+ --theme-popup-border: #cccccc;
+ --theme-hover: #e6e6e6;
+
+ --quote-bg: hsl(197, 37%, 96%);
+ --quote-border: hsl(197, 37%, 91%);
+
+ --table-border-color: hsl(0, 0%, 95%);
+ --table-header-bg: hsl(0, 0%, 80%);
+ --table-alternate-bg: hsl(0, 0%, 97%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #fafafa;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #888;
+ --searchresults-li-bg: #e4f2fe;
+ --search-mark-bg: #a2cff5;
+}
+
+.navy {
+ --bg: hsl(226, 23%, 11%);
+ --fg: #bcbdd0;
+
+ --sidebar-bg: #282d3f;
+ --sidebar-fg: #c8c9db;
+ --sidebar-non-existant: #505274;
+ --sidebar-active: #2b79a2;
+ --sidebar-spacer: #2d334f;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #737480;
+ --icons-hover: #b7b9cc;
+
+ --links: #2b79a2;
+
+ --inline-code-color: #c5c8c6;
+
+ --theme-popup-bg: #161923;
+ --theme-popup-border: #737480;
+ --theme-hover: #282e40;
+
+ --quote-bg: hsl(226, 15%, 17%);
+ --quote-border: hsl(226, 15%, 22%);
+
+ --table-border-color: hsl(226, 23%, 16%);
+ --table-header-bg: hsl(226, 23%, 31%);
+ --table-alternate-bg: hsl(226, 23%, 14%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #aeaec6;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #5f5f71;
+ --searchresults-border-color: #5c5c68;
+ --searchresults-li-bg: #242430;
+ --search-mark-bg: #a2cff5;
+}
+
+.rust {
+ --bg: hsl(60, 9%, 87%);
+ --fg: #262625;
+
+ --sidebar-bg: #3b2e2a;
+ --sidebar-fg: #c8c9db;
+ --sidebar-non-existant: #505254;
+ --sidebar-active: #e69f67;
+ --sidebar-spacer: #45373a;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #737480;
+ --icons-hover: #262625;
+
+ --links: #2b79a2;
+
+ --inline-code-color: #6e6b5e;
+
+ --theme-popup-bg: #e1e1db;
+ --theme-popup-border: #b38f6b;
+ --theme-hover: #99908a;
+
+ --quote-bg: hsl(60, 5%, 75%);
+ --quote-border: hsl(60, 5%, 70%);
+
+ --table-border-color: hsl(60, 9%, 82%);
+ --table-header-bg: #b3a497;
+ --table-alternate-bg: hsl(60, 9%, 84%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #fafafa;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #888;
+ --searchresults-li-bg: #dec2a2;
+ --search-mark-bg: #e69f67;
+}
+
+@media (prefers-color-scheme: dark) {
+ .light.no-js {
+ --bg: hsl(200, 7%, 8%);
+ --fg: #98a3ad;
+
+ --sidebar-bg: #292c2f;
+ --sidebar-fg: #a1adb8;
+ --sidebar-non-existant: #505254;
+ --sidebar-active: #3473ad;
+ --sidebar-spacer: #393939;
+
+ --scrollbar: var(--sidebar-fg);
+
+ --icons: #43484d;
+ --icons-hover: #b3c0cc;
+
+ --links: #2b79a2;
+
+ --inline-code-color: #c5c8c6;
+
+ --theme-popup-bg: #141617;
+ --theme-popup-border: #43484d;
+ --theme-hover: #1f2124;
+
+ --quote-bg: hsl(234, 21%, 18%);
+ --quote-border: hsl(234, 21%, 23%);
+
+ --table-border-color: hsl(200, 7%, 13%);
+ --table-header-bg: hsl(200, 7%, 28%);
+ --table-alternate-bg: hsl(200, 7%, 11%);
+
+ --searchbar-border-color: #aaa;
+ --searchbar-bg: #b7b7b7;
+ --searchbar-fg: #000;
+ --searchbar-shadow-color: #aaa;
+ --searchresults-header-fg: #666;
+ --searchresults-border-color: #98a3ad;
+ --searchresults-li-bg: #2b2b2f;
+ --search-mark-bg: #355c7d;
+ }
+}
diff --git a/debugging-support-in-rustc.html b/debugging-support-in-rustc.html
new file mode 100644
index 000000000..f49fb3629
--- /dev/null
+++ b/debugging-support-in-rustc.html
@@ -0,0 +1,532 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ crates.io Dependencies
+The Rust compiler supports building with some dependencies from crates.io.
+Examples are log and env_logger.
In general, +you should avoid adding dependencies to the compiler for several reasons:
+-
+
- The dependency may not be of high quality or well-maintained. +
- The dependency may not be using a compatible license. +
- The dependency may have transitive dependencies that have one of the above +problems. +
Note that there is no official policy for vetting new dependencies to the compiler. +Decisions are made on a case-by-case basis, during code review.
+Permitted dependencies
+The tidy tool has a list of crates that are allowed. To add a
+dependency that is not already in the compiler, you will need to add it to the list.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/diagnostics.html b/diagnostics.html
new file mode 100644
index 000000000..b072e67a7
--- /dev/null
+++ b/diagnostics.html
@@ -0,0 +1,1102 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ DWARF and
+
+
+
+
+ Debugging support in the Rust compiler
+-
+
- Preliminaries
+
-
+
- Debuggers +
- DWARF +
- CodeView/PDB +
+ - Supported debuggers
+
-
+
- GDB + + +
- LLDB + + +
- WinDbg/CDB
+
-
+
- Natvis +
+
+ - DWARF and
rustc+ +
+ - Developer notes +
- What is missing + + +
- Typical process for a Debug Info change (LLVM) + + +
- Source file checksums in debug info + + +
- Future work + + +
This document explains the state of debugging tools support in the Rust compiler (rustc). +It gives an overview of GDB, LLDB, WinDbg/CDB, +as well as infrastructure around Rust compiler to debug Rust code. +If you want to learn how to debug the Rust compiler itself, +see Debugging the Compiler.
+The material is gathered from the video, +Tom Tromey discusses debugging support in rustc.
+Preliminaries
+Debuggers
+According to Wikipedia
+++A debugger or debugging tool is a computer program that is used to test and debug +other programs (the "target" program).
+
Writing a debugger from scratch for a language requires a lot of work, especially if +debuggers have to be supported on various platforms. GDB and LLDB, however, can be +extended to support debugging a language. This is the path that Rust has chosen. +This document's main goal is to document the said debuggers support in Rust compiler.
+DWARF
+According to the DWARF standard website
+++DWARF is a debugging file format used by many compilers and debuggers to support source level +debugging. It addresses the requirements of a number of procedural languages, +such as C, C++, and Fortran, and is designed to be extensible to other languages. +DWARF is architecture independent and applicable to any processor or operating system. +It is widely used on Unix, Linux and other operating systems, +as well as in stand-alone environments.
+
DWARF reader is a program that consumes the DWARF format and creates debugger compatible output.
+This program may live in the compiler itself. DWARF uses a data structure called
+Debugging Information Entry (DIE) which stores the information as "tags" to denote functions,
+variables etc., e.g., DW_TAG_variable, DW_TAG_pointer_type, DW_TAG_subprogram etc.
+You can also invent your own tags and attributes.
CodeView/PDB
+PDB (Program Database) is a file format created by Microsoft that contains debug information. +PDBs can be consumed by debuggers such as WinDbg/CDB and other tools to display debug information. +A PDB contains multiple streams that describe debug information about a specific binary such +as types, symbols, and source files used to compile the given binary. CodeView is another +format which defines the structure of symbol records and type records that appear within +PDB streams.
+Supported debuggers
+GDB
+Rust expression parser
+To be able to show debug output, we need an expression parser. +This (GDB) expression parser is written in Bison, +and can parse only a subset of Rust expressions. +GDB parser was written from scratch and has no relation to any other parser, +including that of rustc.
+GDB has Rust-like value and type output. It can print values and types in a way +that look like Rust syntax in the output. Or when you print a type as ptype in GDB, +it also looks like Rust source code. Checkout the documentation in the manual for GDB/Rust.
+Parser extensions
+Expression parser has a couple of extensions in it to facilitate features that you cannot do +with Rust. Some limitations are listed in the manual for GDB/Rust. There is some special +code in the DWARF reader in GDB to support the extensions.
+A couple of examples of DWARF reader support needed are as follows:
+-
+
-
+
Enum: Needed for support for enum types. +The Rust compiler writes the information about enum into DWARF, +and GDB reads the DWARF to understand where is the tag field, +or if there is a tag field, +or if the tag slot is shared with non-zero optimization etc.
+
+ -
+
Dissect trait objects: DWARF extension where the trait object's description in the DWARF +also points to a stub description of the corresponding vtable which in turn points to the +concrete type for which this trait object exists. This means that you can do a
+print *object+for that trait object, and GDB will understand how to find the correct type of the payload in +the trait object.
+
TODO: Figure out if the following should be mentioned in the GDB-Rust document rather than +this guide page so there is no duplication. This is regarding the following comments:
+ +++ +gdb's Rust extensions and limitations are documented in the gdb manual: +https://sourceware.org/gdb/onlinedocs/gdb/Rust.html -- however, this neglects to mention that +gdb convenience variables and registers follow the gdb $ convention, and that the Rust parser +implements the gdb @ extension.
+
++@tromey do you think we should mention this part in the GDB-Rust document rather than this +document so there is no duplication etc.?
+
LLDB
+Rust expression parser
+This expression parser is written in C++. It is a type of Recursive Descent parser. +It implements slightly less of the Rust language than GDB. +LLDB has Rust-like value and type output.
+Developer notes
+-
+
- LLDB has a plugin architecture but that does not work for language support. +
- GDB generally works better on Linux. +
WinDbg/CDB
+Microsoft provides Windows Debugging Tools such as the Windows Debugger (WinDbg) and
+the Console Debugger (CDB) which both support debugging programs written in Rust. These
+debuggers parse the debug info for a binary from the PDB, if available, to construct a
+visualization to serve up in the debugger.
Natvis
+Both WinDbg and CDB support defining and viewing custom visualizations for any given type
+within the debugger using the Natvis framework. The Rust compiler defines a set of Natvis
+files that define custom visualizations for a subset of types in the standard libraries such
+as, std, core, and alloc. These Natvis files are embedded into PDBs generated by the
+*-pc-windows-msvc target triples to automatically enable these custom visualizations when
+debugging. This default can be overridden by setting the strip rustc flag to either debuginfo
+or symbols.
Rust has support for embedding Natvis files for crates outside of the standard libraries by
+using the #[debugger_visualizer] attribute.
+For more details on how to embed debugger visualizers,
+please refer to the section on the debugger_visualizer attribute.
DWARF and rustc
+DWARF is the standard way compilers generate debugging information that debuggers read. +It is the debugging format on macOS and Linux. +It is a multi-language and extensible format, +and is mostly good enough for Rust's purposes. +Hence, the current implementation reuses DWARF's concepts. +This is true even if some of the concepts in DWARF do not align with Rust semantically because, +generally, there can be some kind of mapping between the two.
+We have some DWARF extensions that the Rust compiler emits and the debuggers understand that +are not in the DWARF standard.
+-
+
-
+
Rust compiler will emit DWARF for a virtual table, and this
+vtableobject will have a +DW_AT_containing_typethat points to the real type. This lets debuggers dissect a trait object +pointer to correctly find the payload. E.g., here's such a DIE, from a test case in the gdb +repository:
+<1><1a9>: Abbrev Number: 3 (DW_TAG_structure_type) + <1aa> DW_AT_containing_type: <0x1b4> + <1ae> DW_AT_name : (indirect string, offset: 0x23d): vtable + <1b2> DW_AT_byte_size : 0 + <1b3> DW_AT_alignment : 8 +
+ -
+
The other extension is that the Rust compiler can emit a tagless discriminated union. +See DWARF feature request for this item.
+
+
Current limitations of DWARF
+-
+
- Traits - require a bigger change than normal to DWARF, on how to represent Traits in DWARF. +
- DWARF provides no way to differentiate between Structs and Tuples. Rust compiler emits
+fields with
__0and debuggers look for a sequence of such names to overcome this limitation. +For example, in this case the debugger would look at a field viax.__0instead ofx.0. +This is resolved via the Rust parser in the debugger so now you can dox.0.
+
DWARF relies on debuggers to know some information about platform ABI. +Rust does not do that all the time.
+Developer notes
+This section is from the talk about certain aspects of development.
+What is missing
+Code signing for LLDB debug server on macOS
+According to Wikipedia, System Integrity Protection is
+++System Integrity Protection (SIP, sometimes referred to as rootless) is a security feature +of Apple's macOS operating system introduced in OS X El Capitan. It comprises a number of +mechanisms that are enforced by the kernel. A centerpiece is the protection of system-owned +files and directories against modifications by processes without a specific "entitlement", +even when executed by the root user or a user with root privileges (sudo).
+
It prevents processes using ptrace syscall. If a process wants to use ptrace it has to be
+code signed. The certificate that signs it has to be trusted on your machine.
See Apple developer documentation for System Integrity Protection.
+We may need to sign up with Apple and get the keys to do this signing. Tom has looked into if +Mozilla cannot do this because it is at the maximum number of +keys it is allowed to sign. Tom does not know if Mozilla could get more keys.
+Alternatively, Tom suggests that maybe a Rust legal entity is needed to get the keys via Apple. +This problem is not technical in nature. If we had such a key we could sign GDB as well and +ship that.
+DWARF and Traits
+Rust traits are not emitted into DWARF at all. The impact of this is calling a method x.method()
+does not work as is. The reason being that method is implemented by a trait, as opposed
+to a type. That information is not present so finding trait methods is missing.
DWARF has a notion of interface types (possibly added for Java). Tom's idea was to use this +interface type as traits.
+DWARF only deals with concrete names, not the reference types. So, a given implementation of a
+trait for a type would be one of these interfaces (DW_tag_interface type). Also, the type for
+which it is implemented would describe all the interfaces this type implements. This requires a
+DWARF extension.
Issue on Github: https://github.com/rust-lang/rust/issues/33014
+Typical process for a Debug Info change (LLVM)
+LLVM has Debug Info (DI) builders. This is the primary thing that Rust calls into. +This is why we need to change LLVM first because that is emitted first and not DWARF directly. +This is a kind of metadata that you construct and hand-off to LLVM. For the Rustc/LLVM hand-off +some LLVM DI builder methods are called to construct representation of a type.
+The steps of this process are as follows:
+-
+
-
+
LLVM needs changing.
+LLVM does not emit Interface types at all, so this needs to be implemented in the LLVM first.
+Get sign off on LLVM maintainers that this is a good idea.
+
+ -
+
Change the DWARF extension.
+
+ -
+
Update the debuggers.
+Update DWARF readers, expression evaluators.
+
+ -
+
Update Rust compiler.
+Change it to emit this new information.
+
+
Procedural macro stepping
+A deeply profound question is that how do you actually debug a procedural macro? +What is the location you emit for a macro expansion? Consider some of the following cases -
+-
+
- You can emit location of the invocation of the macro. +
- You can emit the location of the definition of the macro. +
- You can emit locations of the content of the macro. +
RFC: https://github.com/rust-lang/rfcs/pull/2117
+Focus is to let macros decide what to do. This can be achieved by having some kind of attribute +that lets the macro tell the compiler where the line marker should be. This affects where you +set the breakpoints and what happens when you step it.
+Source file checksums in debug info
+Both DWARF and CodeView (PDB) support embedding a cryptographic hash of each source file that +contributed to the associated binary.
+The cryptographic hash can be used by a debugger to verify that the source file matches the +executable. If the source file does not match, the debugger can provide a warning to the user.
+The hash can also be used to prove that a given source file has not been modified since it was +used to compile an executable. Because MD5 and SHA1 both have demonstrated vulnerabilities, +using SHA256 is recommended for this application.
+The Rust compiler stores the hash for each source file in the corresponding SourceFile in
+the SourceMap. The hashes of input files to external crates are stored in rlib metadata.
A default hashing algorithm is set in the target specification. This allows the target to +specify the best hash available, since not all targets support all hash algorithms.
+The hashing algorithm for a target can also be overridden with the -Z source-file-checksum=
+command-line option.
DWARF 5
+DWARF version 5 supports embedding an MD5 hash to validate the source file version in use. +DWARF 5 - Section 6.2.4.1 opcode DW_LNCT_MD5
+LLVM
+LLVM IR supports MD5 and SHA1 (and SHA256 in LLVM 11+) source file checksums in the DIFile node.
+ +Microsoft Visual C++ Compiler /ZH option
+The MSVC compiler supports embedding MD5, SHA1, or SHA256 hashes in the PDB using the /ZH
+compiler option.
Clang
+Clang always embeds an MD5 checksum, though this does not appear in documentation.
+Future work
+Name mangling changes
+-
+
- New demangler in
libiberty(gcc source tree).
+ - New demangler in LLVM or LLDB. +
TODO: Check the location of the demangler source. #1157
+Reuse Rust compiler for expressions
+This is an important idea because debuggers by and large do not try to implement type +inference. You need to be much more explicit when you type into the debugger than your +actual source code. So, you cannot just copy and paste an expression from your source +code to debugger and expect the same answer but this would be nice. This can be helped +by using compiler.
+It is certainly doable but it is a large project. You certainly need a bridge to the +debugger because the debugger alone has access to the memory. Both GDB (gcc) and LLDB (clang) +have this feature. LLDB uses Clang to compile code to JIT and GDB can do the same with GCC.
+Both debuggers expression evaluation implement both a superset and a subset of Rust. +They implement just the expression language, +but they also add some extensions like GDB has convenience variables. +Therefore, if you are taking this route, +then you not only need to do this bridge, +but may have to add some mode to let the compiler understand some extensions.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/diagnostics/diagnostic-codes.html b/diagnostics/diagnostic-codes.html
new file mode 100644
index 000000000..dd75af5b0
--- /dev/null
+++ b/diagnostics/diagnostic-codes.html
@@ -0,0 +1,12 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Errors and Lints
+-
+
- Diagnostic structure + + +
- Diagnostic output style guide + + +
- Helpful tips and options + + +
Span
+- Error messages +
- Suggestions + + +
- Lints + + +
- JSON diagnostic output +
#[rustc_on_unimplemented(...)]
+
A lot of effort has been put into making rustc have great error messages.
+This chapter is about how to emit compile errors and lints from the compiler.
Diagnostic structure
+The main parts of a diagnostic error are the following:
+error[E0000]: main error message
+ --> file.rs:LL:CC
+ |
+LL | <code>
+ | -^^^^- secondary label
+ | |
+ | primary label
+ |
+ = note: note without a `Span`, created with `.note`
+note: sub-diagnostic message for `.span_note`
+ --> file.rs:LL:CC
+ |
+LL | more code
+ | ^^^^
+-
+
- Level (
error,warning, etc.). It indicates the severity of the message. +(See diagnostic levels)
+ - Code (for example, for "mismatched types", it is
E0308). It helps +users get more information about the current error through an extended +description of the problem in the error code index. Not all diagnostic have a +code. For example, diagnostics created by lints don't have one.
+ - Message. It is the main description of the problem. It should be general and +able to stand on its own, so that it can make sense even in isolation. +
- Diagnostic window. This contains several things:
+
-
+
- The path, line number and column of the beginning of the primary span. +
- The users' affected code and its surroundings. +
- Primary and secondary spans underlying the users' code. These spans can
+optionally contain one or more labels.
+
-
+
- Primary spans should have enough text to describe the problem in such a +way that if it were the only thing being displayed (for example, in an +IDE) it would still make sense. Because it is "spatially aware" (it +points at the code), it can generally be more succinct than the error +message. +
- If cluttered output can be foreseen in cases when multiple span labels
+overlap, it is a good idea to tweak the output appropriately. For
+example, the
if/else arms have incompatible typeserror uses different +spans depending on whether the arms are all in the same line, if one of +the arms is empty and if none of those cases applies.
+
+
+ - Sub-diagnostics. Any error can have multiple sub-diagnostics that look +similar to the main part of the error. These are used for cases where the +order of the explanation might not correspond with the order of the code. If +the order of the explanation can be "order free", leveraging secondary labels +in the main diagnostic is preferred, as it is typically less verbose. +
The text should be matter of fact and avoid capitalization and periods, unless +multiple sentences are needed:
+error: the fobrulator needs to be krontrificated
+When code or an identifier must appear in a message or label, it should be +surrounded with backticks:
+error: the identifier `foo.bar` is invalid
+Error codes and explanations
+Most errors have an associated error code. Error codes are linked to long-form
+explanations which contains an example of how to trigger the error and in-depth
+details about the error. They may be viewed with the --explain flag, or via
+the error index.
As a general rule, give an error a code (with an associated explanation) if the +explanation would give more information than the error itself. A lot of the time +it's better to put all the information in the emitted error itself. However, +sometimes that would make the error verbose or there are too many possible +triggers to include useful information for all cases in the error, in which case +it's a good idea to add an explanation.1 +As always, if you are not sure, just ask your reviewer!
+If you decide to add a new error with an associated error code, please read +this section for a guide and important details about the +process.
+1
+
+This rule of thumb was suggested by @estebank here.
+Lints versus fixed diagnostics
+Some messages are emitted via lints, where the user can control the +level. Most diagnostics are hard-coded such that the user cannot control the +level.
+Usually it is obvious whether a diagnostic should be "fixed" or a lint, but +there are some grey areas.
+Here are a few examples:
+-
+
- Borrow checker errors: these are fixed errors. The user cannot adjust the +level of these diagnostics to silence the borrow checker. +
- Dead code: this is a lint. While the user probably doesn't want dead code in +their crate, making this a hard error would make refactoring and development +very painful. +
- future-incompatible lints: +these are silencable lints. +It was decided that making them fixed errors would cause too much breakage, +so warnings are instead emitted, +and will eventually be turned into fixed (hard) errors. +
Hard-coded warnings (those using methods like span_warn) should be avoided
+for normal code, preferring to use lints instead. Some cases, such as warnings
+with CLI flags, will require the use of hard-coded warnings.
See the deny lint level below for guidelines when to
+use an error-level lint instead of a fixed error.
Diagnostic output style guide
+-
+
- Write in plain simple English. If your message, when shown on a – possibly +small – screen (which hasn't been cleaned for a while), cannot be understood +by a normal programmer, who just came out of bed after a night partying, +it's too complex. +
Error,Warning,Note, andHelpmessages start with a lowercase +letter and do not end with punctuation.
+- Error messages should be succinct. Users will see these error messages many
+times, and more verbose descriptions can be viewed with the
--explain+flag. That said, don't make it so terse that it's hard to understand.
+ - The word "illegal" is illegal. Prefer "invalid" or a more specific word +instead. +
- Errors should document the span of code where they occur (use
+
rustc_errors::DiagCtxt's +span_*methods or a diagnostic struct's#[primary_span]to easily do +this). Alsonoteother spans that have contributed to the error if the span +isn't too large.
+ - When emitting a message with span, try to reduce the span to the smallest +amount possible that still signifies the issue +
- Try not to emit multiple error messages for the same error. This may require +detecting duplicates. +
- When the compiler has too little information for a specific error message,
+consult with the compiler team to add new attributes for library code that
+allow adding more information. For example see
+
#[rustc_on_unimplemented]. Use these +annotations when available!
+ - Keep in mind that Rust's learning curve is rather steep, and that the +compiler messages are an important learning tool. +
- When talking about the compiler, call it
the compiler, notRustor +rustc.
+ - Use the Oxford comma when +writing lists of items. +
Lint naming
+From RFC 0344, lint names should be consistent, with the following +guidelines:
+The basic rule is: the lint name should make sense when read as "allow
+lint-name" or "allow lint-name items". For example, "allow
+deprecated items" and "allow dead_code" makes sense, while "allow
+unsafe_block" is ungrammatical (should be plural).
-
+
-
+
Lint names should state the bad thing being checked for, e.g.
+deprecated, +so that#[allow(deprecated)](items) reads correctly. Thusctypesis not +an appropriate name;improper_ctypesis.
+ -
+
Lints that apply to arbitrary items (like the stability lints) should just +mention what they check for: use
+deprecatedrather than +deprecated_items. This keeps lint names short. (Again, think "allow +lint-name items".)
+ -
+
If a lint applies to a specific grammatical class, mention that class and +use the plural form: use
+unused_variablesrather thanunused_variable. +This makes#[allow(unused_variables)]read correctly.
+ -
+
Lints that catch unnecessary, unused, or useless aspects of code should use +the term
+unused, e.g.unused_imports,unused_typecasts.
+ -
+
Use snake case in the same way you would for function names.
+
+
Diagnostic levels
+Guidelines for different diagnostic levels:
+-
+
-
+
+error: emitted when the compiler detects a problem that makes it unable to +compile the program, either because the program is invalid or the programmer +has decided to make a specificwarninginto an error.
+ -
+
+warning: emitted when the compiler detects something odd about a program. +Care should be taken when adding warnings to avoid warning fatigue, and +avoid false-positives where there really isn't a problem with the code. Some +examples of when it is appropriate to issue a warning:-
+
- A situation where the user should take action, such as swap out a
+deprecated item, or use a
Result, but otherwise doesn't prevent +compilation.
+ - Unnecessary syntax that can be removed without affecting the semantics of
+the code. For example, unused code, or unnecessary
unsafe.
+ - Code that is very likely to be incorrect, dangerous, or confusing, but the
+language technically allows, and is not ready or confident enough to make
+an error. For example
unused_comparisons(out of bounds comparisons) or +bindings_with_variant_name(the user likely did not intend to create a +binding in a pattern).
+ - Future-incompatible lints, where something was +accidentally or erroneously accepted in the past, but rejecting would +cause excessive breakage in the ecosystem. +
- Stylistic choices. For example, camel or snake case, or the
dyntrait +warning in the 2018 edition. These have a high bar to be added, and should +only be used in exceptional circumstances. Other stylistic choices should +either be allow-by-default lints, or part of other tools like Clippy or +rustfmt.
+
+ - A situation where the user should take action, such as swap out a
+deprecated item, or use a
-
+
+help: emitted following anerrororwarningto give additional +information to the user about how to solve their problem. These messages +often include a suggestion string andrustc_errors::Applicability+confidence level to guide automated source fixes by tools. See the +Suggestions section for more details.The error or warning portion should not suggest how to fix the problem, +only the "help" sub-diagnostic should.
+
+ -
+
+note: emitted to given more context and identify additional circumstances +and parts of the code that caused the warning or error. For example, the +borrow checker will note any previous conflicting borrows.
+helpvsnote:helpshould be used to show changes the user can +possibly make to fix the problem.noteshould be used for everything else, +such as other context, information and facts, online resources to read, etc.
+
Not to be confused with lint levels, whose guidelines are:
+-
+
-
+
+forbid: Lints should never default toforbid.
+ -
+
+deny: Equivalent toerrordiagnostic level. Some examples:-
+
- A future-incompatible or edition-based lint that has graduated from the +warning level. +
- Something that has an extremely high confidence that is incorrect, but +still want an escape hatch to allow it to pass. +
+ -
+
+warn: Equivalent to thewarningdiagnostic level. Seewarningabove +for guidelines.
+ -
+
+allow: Examples of the kinds of lints that should default toallow:-
+
- The lint has a too high false positive rate. +
- The lint is too opinionated. +
- The lint is experimental. +
- The lint is used for enforcing something that is not normally enforced.
+For example, the
unsafe_codelint can be used to prevent usage of unsafe +code.
+
+
More information about lint levels can be found in the rustc +book and the reference.
+Helpful tips and options
+Finding the source of errors
+There are three main ways to find where a given error is emitted:
+-
+
-
+
+grepfor either a sub-part of the error message/label or error code. This +usually works well and is straightforward, but there are some cases where +the code emitting the error is removed from the code where the error is +constructed behind a relatively deep call-stack. Even then, it is a good way +to get your bearings.
+ -
+
Invoking
+rustcwith the nightly-only flag-Z treat-err-as-bug=1+will treat the first error being emitted as an Internal Compiler Error, which +allows you to get a +stack trace at the point the error has been emitted. Change the1to +something else if you wish to trigger on a later error.There are limitations with this approach:
+-
+
- Some calls get elided from the stack trace because they get inlined in the compiled
rustc.
+ - The construction of the error is far away from where it is emitted,
+a problem similar to the one we faced with the
grepapproach. +In some cases, we buffer multiple errors in order to emit them in order.
+
+ - Some calls get elided from the stack trace because they get inlined in the compiled
-
+
Invoking
+rustcwith-Z track-diagnosticswill print error creation +locations alongside the error.
+
The regular development practices apply: judicious use of debug!() statements
+and use of a debugger to trigger break points in order to figure out in what
+order things are happening.
Span
+Span is the primary data structure in rustc used to represent a
+location in the code being compiled. Spans are attached to most constructs in
+HIR and MIR, allowing for more informative error reporting.
A Span can be looked up in a SourceMap to get a "snippet"
+useful for displaying errors with span_to_snippet and other
+similar methods on the SourceMap.
Error messages
+The rustc_errors crate defines most of the utilities used for
+reporting errors.
Diagnostics can be implemented as types which implement the Diagnostic
+trait. This is preferred for new diagnostics as it enforces a separation
+between diagnostic emitting logic and the main code paths. For less-complex
+diagnostics, the Diagnostic trait can be derived -- see Diagnostic
+structs. Within the trait implementation, the APIs
+described below can be used as normal.
DiagCtxt has methods that create and emit errors. These methods
+usually have names like span_err or struct_span_err or span_warn, etc...
+There are lots of them; they emit different types of "errors", such as
+warnings, errors, fatal errors, suggestions, etc.
In general, there are two classes of such methods: ones that emit an error
+directly and ones that allow finer control over what to emit. For example,
+span_err emits the given error message at the given Span, but
+struct_span_err instead returns a
+Diag.
Most of these methods will accept strings, but it is recommended that typed +identifiers for translatable diagnostics be used for new diagnostics (see +Translation).
+Diag allows you to add related notes and suggestions to an error
+before emitting it by calling the emit method. (Failing to either
+emit or cancel a Diag will result in an ICE.) See the
+docs for more info on what you can do.
// Get a `Diag`. This does _not_ emit an error yet.
+let mut err = sess.dcx.struct_span_err(sp, fluent::example::example_error);
+
+// In some cases, you might need to check if `sp` is generated by a macro to
+// avoid printing weird errors about macro-generated code.
+
+if let Ok(snippet) = sess.source_map().span_to_snippet(sp) {
+ // Use the snippet to generate a suggested fix
+ err.span_suggestion(suggestion_sp, fluent::example::try_qux_suggestion, format!("qux {}", snippet));
+} else {
+ // If we weren't able to generate a snippet, then emit a "help" message
+ // instead of a concrete "suggestion". In practice this is unlikely to be
+ // reached.
+ err.span_help(suggestion_sp, fluent::example::qux_suggestion);
+}
+
+// emit the error
+err.emit();
+example-example-error = oh no! this is an error!
+ .try-qux-suggestion = try using a qux here
+ .qux-suggestion = you could use a qux here instead
+Suggestions
+In addition to telling the user exactly why their code is wrong, it's
+oftentimes furthermore possible to tell them how to fix it. To this end,
+Diag offers a structured suggestions API, which formats code
+suggestions pleasingly in the terminal, or (when the --error-format json flag
+is passed) as JSON for consumption by tools like rustfix.
Not all suggestions should be applied mechanically, they have a degree of
+confidence in the suggested code, from high
+(Applicability::MachineApplicable) to low (Applicability::MaybeIncorrect).
+Be conservative when choosing the level. Use the
+span_suggestion method of Diag to
+make a suggestion. The last argument provides a hint to tools whether
+the suggestion is mechanically applicable or not.
Suggestions point to one or more spans with corresponding code that will +replace their current content.
+The message that accompanies them should be understandable in the following +contexts:
+-
+
- shown as an independent sub-diagnostic (this is the default output) +
- shown as a label pointing at the affected span (this is done automatically if +some heuristics for verbosity are met) +
- shown as a
helpsub-diagnostic with no content (used for cases where the +suggestion is obvious from the text, but we still want to let tools to apply +them))
+ - not shown (used for very obvious cases, but we still want to allow tools to +apply them) +
For example, to make our qux suggestion machine-applicable, we would do:
let mut err = sess.dcx.struct_span_err(sp, fluent::example::message);
+
+if let Ok(snippet) = sess.source_map().span_to_snippet(sp) {
+ err.span_suggestion(
+ suggestion_sp,
+ fluent::example::try_qux_suggestion,
+ format!("qux {}", snippet),
+ Applicability::MachineApplicable,
+ );
+} else {
+ err.span_help(suggestion_sp, fluent::example::qux_suggestion);
+}
+
+err.emit();
+This might emit an error like
+$ rustc mycode.rs
+error[E0999]: oh no! this is an error!
+ --> mycode.rs:3:5
+ |
+3 | sad()
+ | ^ help: try using a qux here: `qux sad()`
+
+error: aborting due to previous error
+
+For more information about this error, try `rustc --explain E0999`.
+In some cases, like when the suggestion spans multiple lines or when there are +multiple suggestions, the suggestions are displayed on their own:
+error[E0999]: oh no! this is an error!
+ --> mycode.rs:3:5
+ |
+3 | sad()
+ | ^
+help: try using a qux here:
+ |
+3 | qux sad()
+ | ^^^
+
+error: aborting due to previous error
+
+For more information about this error, try `rustc --explain E0999`.
+The possible values of Applicability are:
-
+
MachineApplicable: Can be applied mechanically.
+HasPlaceholders: Cannot be applied mechanically because it has placeholder +text in the suggestions. For example:try adding a type: `let x: <type>`.
+MaybeIncorrect: Cannot be applied mechanically because the suggestion may +or may not be a good one.
+Unspecified: Cannot be applied mechanically because we don't know which +of the above cases it falls into.
+
Suggestion Style Guide
+-
+
-
+
Suggestions should not be a question. In particular, language like "did you +mean" should be avoided. Sometimes, it's unclear why a particular suggestion +is being made. In these cases, it's better to be upfront about what the +suggestion is.
+Compare "did you mean:
+Foo" vs. "there is a struct with a similar name:Foo".
+ -
+
The message should not contain any phrases like "the following", "as shown", +etc. Use the span to convey what is being talked about.
+
+ -
+
The message may contain further instruction such as "to do xyz, use" or "to do +xyz, use abc".
+
+ -
+
The message may contain a name of a function, variable, or type, but avoid +whole expressions.
+
+
Lints
+The compiler linting infrastructure is defined in the rustc_middle::lint
+module.
When do lints run?
+Different lints will run at different times based on what information the lint +needs to do its job. Some lints get grouped into passes where the lints +within a pass are processed together via a single visitor. Some of the passes +are:
+-
+
-
+
Pre-expansion pass: Works on AST nodes before macro expansion. This +should generally be avoided.
+-
+
- Example:
keyword_identschecks for identifiers that will become +keywords in future editions, but is sensitive to identifiers used in +macros.
+
+ - Example:
-
+
Early lint pass: Works on AST nodes after macro expansion and name +resolution, just before AST lowering. These lints are for purely +syntactical lints.
+-
+
- Example: The
unused_parenslint checks for parenthesized-expressions +in situations where they are not needed, like anifcondition.
+
+ - Example: The
-
+
Late lint pass: Works on HIR nodes, towards the end of analysis (after +borrow checking, etc.). These lints have full type information available. +Most lints are late.
+-
+
- Example: The
invalid_valuelint (which checks for obviously invalid +uninitialized values) is a late lint because it needs type information to +figure out whether a type allows being left uninitialized.
+
+ - Example: The
-
+
MIR pass: Works on MIR nodes. This isn't quite the same as other passes; +lints that work on MIR nodes have their own methods for running.
+-
+
- Example: The
arithmetic_overflowlint is emitted when it detects a +constant value that may overflow.
+
+ - Example: The
Most lints work well via the pass systems, and they have a fairly
+straightforward interface and easy way to integrate (mostly just implementing
+a specific check function). However, some lints are easier to write when
+they live on a specific code path anywhere in the compiler. For example, the
+unused_mut lint is implemented in the borrow checker as it requires some
+information and state in the borrow checker.
Some of these inline lints fire before the linting system is ready. Those +lints will be buffered where they are held until later phases of the +compiler when the linting system is ready. See Linting early in the +compiler.
+Lint definition terms
+Lints are managed via the LintStore and get registered in
+various ways. The following terms refer to the different classes of lints
+generally based on how they are registered.
-
+
- Built-in lints are defined inside the compiler source. +
- Driver-registered lints are registered when the compiler driver is created +by an external driver. This is the mechanism used by Clippy, for example. +
- Tool lints are lints with a path prefix like
clippy::orrustdoc::.
+ - Internal lints are the
rustc::scoped tool lints that only run on the +rustc source tree itself and are defined in the compiler source like a +regular built-in lint.
+
More information about lint registration can be found in the LintStore +chapter.
+Declaring a lint
+The built-in compiler lints are defined in the rustc_lint
+crate. Lints that need to be implemented in other crates are defined in
+rustc_lint_defs. You should prefer to place lints in rustc_lint if
+possible. One benefit is that it is close to the dependency root, so it can be
+much faster to work on.
Every lint is implemented via a struct that implements the LintPass trait
+(you can also implement one of the more specific lint pass traits, either
+EarlyLintPass or LateLintPass depending on when is best for your lint to run).
+The trait implementation allows you to check certain syntactic constructs
+as the linter walks the AST. You can then choose to emit lints in a
+very similar way to compile errors.
You also declare the metadata of a particular lint via the declare_lint!
+macro. This includes the name, the default level, a short description, and some
+more details.
Note that the lint and the lint pass must be registered with the compiler.
+For example, the following lint checks for uses
+of while true { ... } and suggests using loop { ... } instead.
// Declare a lint called `WHILE_TRUE`
+declare_lint! {
+ WHILE_TRUE,
+
+ // warn-by-default
+ Warn,
+
+ // This string is the lint description
+ "suggest using `loop { }` instead of `while true { }`"
+}
+
+// This declares a struct and a lint pass, providing a list of associated lints. The
+// compiler currently doesn't use the associated lints directly (e.g., to not
+// run the pass or otherwise check that the pass emits the appropriate set of
+// lints). However, it's good to be accurate here as it's possible that we're
+// going to register the lints via the get_lints method on our lint pass (that
+// this macro generates).
+declare_lint_pass!(WhileTrue => [WHILE_TRUE]);
+
+// Helper function for `WhileTrue` lint.
+// Traverse through any amount of parenthesis and return the first non-parens expression.
+fn pierce_parens(mut expr: &ast::Expr) -> &ast::Expr {
+ while let ast::ExprKind::Paren(sub) = &expr.kind {
+ expr = sub;
+ }
+ expr
+}
+
+// `EarlyLintPass` has lots of methods. We only override the definition of
+// `check_expr` for this lint because that's all we need, but you could
+// override other methods for your own lint. See the rustc docs for a full
+// list of methods.
+impl EarlyLintPass for WhileTrue {
+ fn check_expr(&mut self, cx: &EarlyContext<'_>, e: &ast::Expr) {
+ if let ast::ExprKind::While(cond, ..) = &e.kind
+ && let ast::ExprKind::Lit(ref lit) = pierce_parens(cond).kind
+ && let ast::LitKind::Bool(true) = lit.kind
+ && !lit.span.from_expansion()
+ {
+ let condition_span = cx.sess.source_map().guess_head_span(e.span);
+ cx.struct_span_lint(WHILE_TRUE, condition_span, |lint| {
+ lint.build(fluent::example::use_loop)
+ .span_suggestion_short(
+ condition_span,
+ fluent::example::suggestion,
+ "loop".to_owned(),
+ Applicability::MachineApplicable,
+ )
+ .emit();
+ })
+ }
+ }
+}
+example-use-loop = denote infinite loops with `loop {"{"} ... {"}"}`
+ .suggestion = use `loop`
+Edition-gated lints
+Sometimes we want to change the behavior of a lint in a new edition. To do this,
+we just add the transition to our invocation of declare_lint!:
declare_lint! {
+ pub ANONYMOUS_PARAMETERS,
+ Allow,
+ "detects anonymous parameters",
+ Edition::Edition2018 => Warn,
+}
+This makes the ANONYMOUS_PARAMETERS lint allow-by-default in the 2015 edition
+but warn-by-default in the 2018 edition.
See Edition-specific lints for more information.
+Feature-gated lints
+Lints belonging to a feature should only be usable if the feature is enabled in the +crate. To support this, lint declarations can contain a feature gate like so:
+declare_lint! {
+ pub SOME_LINT_NAME,
+ Warn,
+ "a new and useful, but feature gated lint",
+ @feature_gate = sym::feature_name;
+}
+Future-incompatible lints
+The use of the term future-incompatible within the compiler has a slightly
+broader meaning than what rustc exposes to users of the compiler.
Inside rustc, future-incompatible lints are for signalling to the user that code they have +written may not compile in the future. In general, future-incompatible code +exists for two reasons:
+-
+
- The user has written unsound code that the compiler mistakenly accepted. While +it is within Rust's backwards compatibility guarantees to fix the soundness hole +(breaking the user's code), the lint is there to warn the user that this will happen +in some upcoming version of rustc regardless of which edition the code uses. This is the +meaning that rustc exclusively exposes to users as "future incompatible". +
- The user has written code that will either no longer compiler or will change
+meaning in an upcoming edition. These are often called "edition lints" and can be
+typically seen in the various "edition compatibility" lint groups (e.g.,
rust_2021_compatibility) +that are used to lint against code that will break if the user updates the crate's edition. +See migration lints for more details.
+
A future-incompatible lint should be declared with the @future_incompatible
+additional "field":
declare_lint! {
+ pub ANONYMOUS_PARAMETERS,
+ Allow,
+ "detects anonymous parameters",
+ @future_incompatible = FutureIncompatibleInfo {
+ reference: "issue #41686 <https://github.com/rust-lang/rust/issues/41686>",
+ reason: FutureIncompatibilityReason::EditionError(Edition::Edition2018),
+ };
+}
+Notice the reason field which describes why the future incompatible change is happening.
+This will change the diagnostic message the user receives as well as determine which
+lint groups the lint is added to. In the example above, the lint is an "edition lint"
+(since its "reason" is EditionError), signifying to the user that the use of anonymous
+parameters will no longer compile in Rust 2018 and beyond.
Inside LintStore::register_lints, lints with future_incompatible
+fields get placed into either edition-based lint groups (if their reason is tied to
+an edition) or into the future_incompatibility lint group.
If you need a combination of options that's not supported by the
+declare_lint! macro, you can always change the declare_lint! macro
+to support this.
Renaming or removing a lint
+If it is determined that a lint is either improperly named or no longer needed,
+the lint must be registered for renaming or removal, which will trigger a warning if a user tries
+to use the old lint name. To declare a rename/remove, add a line with
+store.register_renamed or store.register_removed to the code of the
+rustc_lint::register_builtins function.
store.register_renamed("single_use_lifetime", "single_use_lifetimes");
+Lint Groups
+Lints can be turned on in groups. These groups are declared in the
+register_builtins function in rustc_lint::lib. The
+add_lint_group! macro is used to declare a new group.
For example,
+add_lint_group!(sess,
+ "nonstandard_style",
+ NON_CAMEL_CASE_TYPES,
+ NON_SNAKE_CASE,
+ NON_UPPER_CASE_GLOBALS);
+This defines the nonstandard_style group which turns on the listed lints. A
+user can turn on these lints with a !#[warn(nonstandard_style)] attribute in
+the source code, or by passing -W nonstandard-style on the command line.
Some lint groups are created automatically in LintStore::register_lints. For instance,
+any lint declared with FutureIncompatibleInfo where the reason is
+FutureIncompatibilityReason::FutureReleaseError (the default when
+@future_incompatible is used in declare_lint!), will be added to
+the future_incompatible lint group. Editions also have their own lint groups
+(e.g., rust_2021_compatibility) automatically generated for any lints signaling
+future-incompatible code that will break in the specified edition.
Linting early in the compiler
+On occasion, you may need to define a lint that runs before the linting system +has been initialized (e.g. during parsing or macro expansion). This is +problematic because we need to have computed lint levels to know whether we +should emit a warning or an error or nothing at all.
+To solve this problem, we buffer the lints until the linting system is
+processed. Session and ParseSess both have
+buffer_lint methods that allow you to buffer a lint for later. The linting
+system automatically takes care of handling buffered lints later.
Thus, to define a lint that runs early in the compilation, one defines a lint
+like normal but invokes the lint with buffer_lint.
Linting even earlier in the compiler
+The parser (rustc_ast) is interesting in that it cannot have dependencies on
+any of the other rustc* crates. In particular, it cannot depend on
+rustc_middle::lint or rustc_lint, where all of the compiler linting
+infrastructure is defined. That's troublesome!
To solve this, rustc_ast defines its own buffered lint type, which
+ParseSess::buffer_lint uses. After macro expansion, these buffered lints are
+then dumped into the Session::buffered_lints used by the rest of the compiler.
JSON diagnostic output
+The compiler accepts an --error-format json flag to output
+diagnostics as JSON objects (for the benefit of tools such as cargo fix). It looks like this:
$ rustc json_error_demo.rs --error-format json
+{"message":"cannot add `&str` to `{integer}`","code":{"code":"E0277","explanation":"\nYou tried to use a type which doesn't implement some trait in a place which\nexpected that trait. Erroneous code example:\n\n```compile_fail,E0277\n// here we declare the Foo trait with a bar method\ntrait Foo {\n fn bar(&self);\n}\n\n// we now declare a function which takes an object implementing the Foo trait\nfn some_func<T: Foo>(foo: T) {\n foo.bar();\n}\n\nfn main() {\n // we now call the method with the i32 type, which doesn't implement\n // the Foo trait\n some_func(5i32); // error: the trait bound `i32 : Foo` is not satisfied\n}\n```\n\nIn order to fix this error, verify that the type you're using does implement\nthe trait. Example:\n\n```\ntrait Foo {\n fn bar(&self);\n}\n\nfn some_func<T: Foo>(foo: T) {\n foo.bar(); // we can now use this method since i32 implements the\n // Foo trait\n}\n\n// we implement the trait on the i32 type\nimpl Foo for i32 {\n fn bar(&self) {}\n}\n\nfn main() {\n some_func(5i32); // ok!\n}\n```\n\nOr in a generic context, an erroneous code example would look like:\n\n```compile_fail,E0277\nfn some_func<T>(foo: T) {\n println!(\"{:?}\", foo); // error: the trait `core::fmt::Debug` is not\n // implemented for the type `T`\n}\n\nfn main() {\n // We now call the method with the i32 type,\n // which *does* implement the Debug trait.\n some_func(5i32);\n}\n```\n\nNote that the error here is in the definition of the generic function: Although\nwe only call it with a parameter that does implement `Debug`, the compiler\nstill rejects the function: It must work with all possible input types. In\norder to make this example compile, we need to restrict the generic type we're\naccepting:\n\n```\nuse std::fmt;\n\n// Restrict the input type to types that implement Debug.\nfn some_func<T: fmt::Debug>(foo: T) {\n println!(\"{:?}\", foo);\n}\n\nfn main() {\n // Calling the method is still fine, as i32 implements Debug.\n some_func(5i32);\n\n // This would fail to compile now:\n // struct WithoutDebug;\n // some_func(WithoutDebug);\n}\n```\n\nRust only looks at the signature of the called function, as such it must\nalready specify all requirements that will be used for every type parameter.\n"},"level":"error","spans":[{"file_name":"json_error_demo.rs","byte_start":50,"byte_end":51,"line_start":4,"line_end":4,"column_start":7,"column_end":8,"is_primary":true,"text":[{"text":" a + b","highlight_start":7,"highlight_end":8}],"label":"no implementation for `{integer} + &str`","suggested_replacement":null,"suggestion_applicability":null,"expansion":null}],"children":[{"message":"the trait `std::ops::Add<&str>` is not implemented for `{integer}`","code":null,"level":"help","spans":[],"children":[],"rendered":null}],"rendered":"error[E0277]: cannot add `&str` to `{integer}`\n --> json_error_demo.rs:4:7\n |\n4 | a + b\n | ^ no implementation for `{integer} + &str`\n |\n = help: the trait `std::ops::Add<&str>` is not implemented for `{integer}`\n\n"}
+{"message":"aborting due to previous error","code":null,"level":"error","spans":[],"children":[],"rendered":"error: aborting due to previous error\n\n"}
+{"message":"For more information about this error, try `rustc --explain E0277`.","code":null,"level":"","spans":[],"children":[],"rendered":"For more information about this error, try `rustc --explain E0277`.\n"}
+Note that the output is a series of lines, each of which is a JSON
+object, but the series of lines taken together is, unfortunately, not
+valid JSON, thwarting tools and tricks (such as piping to python3 -m json.tool)
+that require such. (One speculates that this was intentional for LSP
+performance purposes, so that each line/object can be sent as
+it is flushed?)
Also note the "rendered" field, which contains the "human" output as a +string; this was introduced so that UI tests could both make use of +the structured JSON and see the "human" output (well, sans colors) +without having to compile everything twice.
+The "human" readable and the json format emitter can be found under
+rustc_errors, both were moved from the rustc_ast crate to the
+rustc_errors crate.
The JSON emitter defines its own Diagnostic
+struct
+(and sub-structs) for the JSON serialization. Don't confuse this with
+errors::Diag!
#[rustc_on_unimplemented(...)]
+The #[rustc_on_unimplemented] attribute allows trait definitions to add specialized
+notes to error messages when an implementation was expected but not found.
+You can refer to the trait's generic arguments by name and to the resolved type using Self.
For example:
+#![feature(rustc_attrs)]
+
+#[rustc_on_unimplemented="an iterator over elements of type `{A}` \
+ cannot be built from a collection of type `{Self}`"]
+trait MyIterator<A> {
+ fn next(&mut self) -> A;
+}
+
+fn iterate_chars<I: MyIterator<char>>(i: I) {
+ // ...
+}
+
+fn main() {
+ iterate_chars(&[1, 2, 3][..]);
+}
+When the user compiles this, they will see the following;
+error[E0277]: the trait bound `&[{integer}]: MyIterator<char>` is not satisfied
+ --> <anon>:14:5
+ |
+14 | iterate_chars(&[1, 2, 3][..]);
+ | ^^^^^^^^^^^^^ an iterator over elements of type `char` cannot be built from a collection of type `&[{integer}]`
+ |
+ = help: the trait `MyIterator<char>` is not implemented for `&[{integer}]`
+ = note: required by `iterate_chars`
+rustc_on_unimplemented also supports advanced filtering for better targeting
+of messages, as well as modifying specific parts of the error message. You
+target the text of:
-
+
- the main error message (
message)
+ - the label (
label)
+ - an extra note (
note)
+
For example, the following attribute
+#[rustc_on_unimplemented(
+ message="message",
+ label="label",
+ note="note"
+)]
+trait MyIterator<A> {
+ fn next(&mut self) -> A;
+}
+Would generate the following output:
+error[E0277]: message
+ --> <anon>:14:5
+ |
+14 | iterate_chars(&[1, 2, 3][..]);
+ | ^^^^^^^^^^^^^ label
+ |
+ = note: note
+ = help: the trait `MyIterator<char>` is not implemented for `&[{integer}]`
+ = note: required by `iterate_chars`
+To allow more targeted error messages, it is possible to filter the
+application of these fields based on a variety of attributes when using
+on:
-
+
crate_local: whether the code causing the trait bound to not be +fulfilled is part of the user's crate. This is used to avoid suggesting +code changes that would require modifying a dependency.
+- Any of the generic arguments that can be substituted in the text can be
+referred by name as well for filtering, like
Rhs="i32", except for +Self.
+ _Self: to filter only on a particular calculated trait resolution, like +Self="std::iter::Iterator<char>". This is needed becauseSelfis a +keyword which cannot appear in attributes.
+direct: user-specified rather than derived obligation.
+from_method: usable both as boolean (whether the flag is present, like +crate_local) or matching against a particular method. Currently used +fortry.
+from_desugaring: usable both as boolean (whether the flag is present) +or matching against a particular desugaring. The desugaring is identified +with its variant name in theDesugaringKindenum.
+
For example, the Iterator trait can be annotated in the following way:
#[rustc_on_unimplemented(
+ on(
+ _Self="&str",
+ note="call `.chars()` or `.as_bytes()` on `{Self}`"
+ ),
+ message="`{Self}` is not an iterator",
+ label="`{Self}` is not an iterator",
+ note="maybe try calling `.iter()` or a similar method"
+)]
+pub trait Iterator {}
+Which would produce the following outputs:
+error[E0277]: `Foo` is not an iterator
+ --> src/main.rs:4:16
+ |
+4 | for foo in Foo {}
+ | ^^^ `Foo` is not an iterator
+ |
+ = note: maybe try calling `.iter()` or a similar method
+ = help: the trait `std::iter::Iterator` is not implemented for `Foo`
+ = note: required by `std::iter::IntoIterator::into_iter`
+
+error[E0277]: `&str` is not an iterator
+ --> src/main.rs:5:16
+ |
+5 | for foo in "" {}
+ | ^^ `&str` is not an iterator
+ |
+ = note: call `.chars()` or `.bytes() on `&str`
+ = help: the trait `std::iter::Iterator` is not implemented for `&str`
+ = note: required by `std::iter::IntoIterator::into_iter`
+If you need to filter on multiple attributes, you can use all, any or
+not in the following way:
#[rustc_on_unimplemented(
+ on(
+ all(_Self="&str", T="std::string::String"),
+ note="you can coerce a `{T}` into a `{Self}` by writing `&*variable`"
+ )
+)]
+pub trait From<T>: Sized { /* ... */ }
+Redirecting to... error-codes.html.
+ + diff --git a/diagnostics/diagnostic-items.html b/diagnostics/diagnostic-items.html new file mode 100644 index 000000000..4a3d71f5f --- /dev/null +++ b/diagnostics/diagnostic-items.html @@ -0,0 +1,340 @@ + + + + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/diagnostics/diagnostic-structs.html b/diagnostics/diagnostic-structs.html
new file mode 100644
index 000000000..3fdf023e0
--- /dev/null
+++ b/diagnostics/diagnostic-structs.html
@@ -0,0 +1,655 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Diagnostic Items
+While writing lints it's common to check for specific types, traits and
+functions. This raises the question on how to check for these. Types can be
+checked by their complete type path. However, this requires hard coding paths
+and can lead to misclassifications in some edge cases. To counteract this,
+rustc has introduced diagnostic items that are used to identify types via
+Symbols.
Finding diagnostic items
+Diagnostic items are added to items inside rustc/std/core/alloc with the
+rustc_diagnostic_item attribute. The item for a specific type can be found by
+opening the source code in the documentation and looking for this attribute.
+Note that it's often added with the cfg_attr attribute to avoid compilation
+errors during tests. A definition often looks like this:
// This is the diagnostic item for this type vvvvvvv
+#[cfg_attr(not(test), rustc_diagnostic_item = "Penguin")]
+struct Penguin;
+Diagnostic items are usually only added to traits, +types, +and standalone functions. +If the goal is to check for an associated type or method, +please use the diagnostic item of the item and reference +Using Diagnostic Items.
+Adding diagnostic items
+A new diagnostic item can be added with these two steps:
+-
+
-
+
Find the target item inside the Rust repo. Now add the diagnostic item as a +string via the
+rustc_diagnostic_itemattribute. This can sometimes cause +compilation errors while running tests. These errors can be avoided by using +thecfg_attrattribute with thenot(test)condition (it's fine adding +then for allrustc_diagnostic_itemattributes as a preventive manner). At +the end, it should look like this:
+// This will be the new diagnostic item vvv +#[cfg_attr(not(test), rustc_diagnostic_item = "Cat")] +struct Cat; +For the naming conventions of diagnostic items, please refer to +Naming Conventions.
+
+ -
+
Diagnostic items in code are accessed via symbols in +
+rustc_span::symbol::sym. +To add your newly-created diagnostic item, +simply open the module file, +and add the name (In this caseCat) at the correct point in the list.
+
Now you can create a pull request with your changes. :tada:
+++NOTE: +When using diagnostic items in other projects like Clippy, +it might take some time until the repos get synchronized.
+
Naming conventions
+Diagnostic items don't have a naming convention yet. +Following are some guidelines that should be used in future, +but might differ from existing names:
+-
+
- Types, traits, and enums are named using UpperCamelCase
+(Examples:
IteratorandHashMap)
+ - For type names that are used multiple times,
+like
Writer, +it's good to choose a more precise name, +maybe by adding the module to it +(Example:IoWriter)
+ - Associated items should not get their own diagnostic items, +but instead be accessed indirectly by the diagnostic item +of the type they're originating from. +
- Freestanding functions like
std::mem::swap()should be named using +snake_casewith one important (export) module as a prefix +(Examples:mem_swapandcmp_max)
+ - Modules should usually not have a diagnostic item attached to them. +Diagnostic items were added to avoid the usage of paths, +and using them on modules would therefore most likely be counterproductive. +
Using diagnostic items
+In rustc, diagnostic items are looked up via Symbols from inside the
+rustc_span::symbol::sym module. These can then be mapped to DefIds
+using TyCtxt::get_diagnostic_item() or checked if they match a DefId
+using TyCtxt::is_diagnostic_item(). When mapping from a diagnostic item to
+a DefId, the method will return a Option<DefId>. This can be None if
+either the symbol isn't a diagnostic item or the type is not registered, for
+instance when compiling with #[no_std].
+All the following examples are based on DefIds and their usage.
Example: Checking for a type
++#![allow(unused)] +fn main() { +use rustc_span::symbol::sym; + +/// This example checks if the given type (`ty`) has the type `HashMap` using +/// `TyCtxt::is_diagnostic_item()` +fn example_1(cx: &LateContext<'_>, ty: Ty<'_>) -> bool { + match ty.kind() { + ty::Adt(adt, _) => cx.tcx.is_diagnostic_item(sym::HashMap, adt.did()), + _ => false, + } +} +} +
Example: Checking for a trait implementation
++#![allow(unused)] +fn main() { +/// This example checks if a given [`DefId`] from a method is part of a trait +/// implementation defined by a diagnostic item. +fn is_diag_trait_item( + cx: &LateContext<'_>, + def_id: DefId, + diag_item: Symbol +) -> bool { + if let Some(trait_did) = cx.tcx.trait_of_item(def_id) { + return cx.tcx.is_diagnostic_item(diag_item, trait_did); + } + false +} +} +
Associated Types
+Associated types of diagnostic items can be accessed indirectly by first
+getting the DefId of the trait and then calling
+TyCtxt::associated_items(). This returns an AssocItems object which can
+be used for further checks. Checkout
+clippy_utils::ty::get_iterator_item_ty() for an example usage of this.
Usage in Clippy
+Clippy tries to use diagnostic items where possible and has developed some +wrapper and utility functions. Please also refer to its documentation when +using diagnostic items in Clippy. (See Common tools for writing +lints.)
+Related issues
+These are probably only interesting to people +who really want to take a deep dive into the topic :)
+-
+
- rust#60966: The Rust PR that introduced diagnostic items +
- rust-clippy#5393: Clippy's tracking issue for moving away from hard coded paths to +diagnostic item +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/diagnostics/error-codes.html b/diagnostics/error-codes.html
new file mode 100644
index 000000000..10ad4ce55
--- /dev/null
+++ b/diagnostics/error-codes.html
@@ -0,0 +1,284 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Diagnostic and subdiagnostic structs
+rustc has three diagnostic traits that can be used to create diagnostics:
+Diagnostic, LintDiagnostic, and Subdiagnostic. For simple diagnostics,
+instead of using the Diag API to create and emit diagnostics,
+derived impls can be used. They are only suitable for simple diagnostics that
+don't require much logic in deciding whether or not to add additional
+subdiagnostics.
Such diagnostic can be translated into +different languages and each has a slug that uniquely identifies the +diagnostic.
+#[derive(Diagnostic)] and #[derive(LintDiagnostic)]
+Consider the definition of the "field already declared" diagnostic +shown below:
+#[derive(Diagnostic)]
+#[diag(hir_analysis_field_already_declared, code = E0124)]
+pub struct FieldAlreadyDeclared {
+ pub field_name: Ident,
+ #[primary_span]
+ #[label]
+ pub span: Span,
+ #[label(previous_decl_label)]
+ pub prev_span: Span,
+}
+Diagnostic can only be derived on structs and enums.
+Attributes that are placed on the type for structs are placed on each
+variants for enums (or vice versa). Each Diagnostic has to have one
+attribute, #[diag(...)], applied to the struct or each enum variant.
If an error has an error code (e.g. "E0624"), then that can be specified using
+the code sub-attribute. Specifying a code isn't mandatory, but if you are
+porting a diagnostic that uses Diag to use Diagnostic
+then you should keep the code if there was one.
#[diag(..)] must provide a slug as the first positional argument (a path to an
+item in rustc_errors::fluent::*). A slug uniquely identifies the diagnostic
+and is also how the compiler knows what error message to emit (in the default
+locale of the compiler, or in the locale requested by the user). See
+translation documentation to learn more about how
+translatable error messages are written and how slug items are generated.
In our example, the Fluent message for the "field already declared" diagnostic +looks like this:
+hir_analysis_field_already_declared =
+ field `{$field_name}` is already declared
+ .label = field already declared
+ .previous_decl_label = `{$field_name}` first declared here
+hir_analysis_field_already_declared is the slug from our example and is followed
+by the diagnostic message.
Every field of the Diagnostic which does not have an annotation is
+available in Fluent messages as a variable, like field_name in the example
+above. Fields can be annotated #[skip_arg] if this is undesired.
Using the #[primary_span] attribute on a field (that has type Span)
+indicates the primary span of the diagnostic which will have the main message
+of the diagnostic.
Diagnostics are more than just their primary message, they often include
+labels, notes, help messages and suggestions, all of which can also be
+specified on a Diagnostic.
#[label], #[help], #[warning] and #[note] can all be applied to fields which have the
+type Span. Applying any of these attributes will create the corresponding
+subdiagnostic with that Span. These attributes will look for their
+diagnostic message in a Fluent attribute attached to the primary Fluent
+message. In our example, #[label] will look for
+hir_analysis_field_already_declared.label (which has the message "field already
+declared"). If there is more than one subdiagnostic of the same type, then
+these attributes can also take a value that is the attribute name to look for
+(e.g. previous_decl_label in our example).
Other types have special behavior when used in a Diagnostic derive:
-
+
- Any attribute applied to an
Option<T>will only emit a +subdiagnostic if the option isSome(..).
+ - Any attribute applied to a
Vec<T>will be repeated for each element of the +vector.
+
#[help], #[warning] and #[note] can also be applied to the struct itself, in which case
+they work exactly like when applied to fields except the subdiagnostic won't
+have a Span. These attributes can also be applied to fields of type () for
+the same effect, which when combined with the Option type can be used to
+represent optional #[note]/#[help]/#[warning] subdiagnostics.
Suggestions can be emitted using one of four field attributes:
+-
+
#[suggestion(slug, code = "...", applicability = "...")]
+#[suggestion_hidden(slug, code = "...", applicability = "...")]
+#[suggestion_short(slug, code = "...", applicability = "...")]
+#[suggestion_verbose(slug, code = "...", applicability = "...")]
+
Suggestions must be applied on either a Span field or a (Span, MachineApplicability) field. Similarly to other field attributes, the slug
+specifies the Fluent attribute with the message and defaults to the equivalent
+of .suggestion. code specifies the code that should be suggested as a
+replacement and is a format string (e.g. {field_name} would be replaced by
+the value of the field_name field of the struct), not a Fluent identifier.
+applicability can be used to specify the applicability in the attribute, it
+cannot be used when the field's type contains an Applicability.
In the end, the Diagnostic derive will generate an implementation of
+Diagnostic that looks like the following:
impl<'a, G: EmissionGuarantee> Diagnostic<'a> for FieldAlreadyDeclared {
+ fn into_diag(self, dcx: &'a DiagCtxt, level: Level) -> Diag<'a, G> {
+ let mut diag = Diag::new(dcx, level, fluent::hir_analysis_field_already_declared);
+ diag.set_span(self.span);
+ diag.span_label(
+ self.span,
+ fluent::hir_analysis_label
+ );
+ diag.span_label(
+ self.prev_span,
+ fluent::hir_analysis_previous_decl_label
+ );
+ diag
+ }
+}
+Now that we've defined our diagnostic, how do we use it? It's quite
+straightforward, just create an instance of the struct and pass it to
+emit_err (or emit_warning):
tcx.dcx().emit_err(FieldAlreadyDeclared {
+ field_name: f.ident,
+ span: f.span,
+ prev_span,
+});
+Reference
+#[derive(Diagnostic)] and #[derive(LintDiagnostic)] support the
+following attributes:
-
+
#[diag(slug, code = "...")]+-
+
- Applied to struct or enum variant. +
- Mandatory +
- Defines the text and error code to be associated with the diagnostic. +
- Slug (Mandatory)
+
-
+
- Uniquely identifies the diagnostic and corresponds to its Fluent message, +mandatory. +
- A path to an item in
rustc_errors::fluent, e.g. +rustc_errors::fluent::hir_analysis_field_already_declared+(rustc_errors::fluentis implicit in the attribute, so just +hir_analysis_field_already_declared).
+ - See translation documentation. +
+ code = "..."(Optional) +-
+
- Specifies the error code. +
+
+#[note]or#[note(slug)](Optional) +-
+
- Applied to struct or struct fields of type
Span,Option<()>or().
+ - Adds a note subdiagnostic. +
- Value is a path to an item in
rustc_errors::fluentfor the note's +message. +-
+
- Defaults to equivalent of
.note.
+
+ - Defaults to equivalent of
- If applied to a
Spanfield, creates a spanned note.
+
+- Applied to struct or struct fields of type
#[help]or#[help(slug)](Optional) +-
+
- Applied to struct or struct fields of type
Span,Option<()>or().
+ - Adds a help subdiagnostic. +
- Value is a path to an item in
rustc_errors::fluentfor the note's +message. +-
+
- Defaults to equivalent of
.help.
+
+ - Defaults to equivalent of
- If applied to a
Spanfield, creates a spanned help.
+
+- Applied to struct or struct fields of type
#[label]or#[label(slug)](Optional) +-
+
- Applied to
Spanfields.
+ - Adds a label subdiagnostic. +
- Value is a path to an item in
rustc_errors::fluentfor the note's +message. +-
+
- Defaults to equivalent of
.label.
+
+ - Defaults to equivalent of
+- Applied to
#[warning]or#[warning(slug)](Optional) +-
+
- Applied to struct or struct fields of type
Span,Option<()>or().
+ - Adds a warning subdiagnostic. +
- Value is a path to an item in
rustc_errors::fluentfor the note's +message. +-
+
- Defaults to equivalent of
.warn.
+
+ - Defaults to equivalent of
+- Applied to struct or struct fields of type
#[suggestion{,_hidden,_short,_verbose}(slug, code = "...", applicability = "...")]+(Optional) +-
+
- Applied to
(Span, MachineApplicability)orSpanfields.
+ - Adds a suggestion subdiagnostic. +
- Slug (Mandatory)
+
-
+
- A path to an item in
rustc_errors::fluent, e.g. +rustc_errors::fluent::hir_analysis_field_already_declared+(rustc_errors::fluentis implicit in the attribute, so just +hir_analysis_field_already_declared). Fluent attributes for all messages +exist as top-level items in that module (sohir_analysis_message.attris just +attr).
+ - See translation documentation. +
- Defaults to
rustc_errors::fluent::_subdiag::suggestion(or
+ .suggestionin Fluent).
+
+ - A path to an item in
code = "..."/code("...", ...)(Mandatory) +-
+
- One or multiple format strings indicating the code to be suggested as a +replacement. Multiple values signify multiple possible replacements. +
+applicability = "..."(Optional) +-
+
- String which must be one of
machine-applicable,maybe-incorrect, +has-placeholdersorunspecified.
+
+- String which must be one of
+- Applied to
#[subdiagnostic]+-
+
- Applied to a type that implements
Subdiagnostic(from +#[derive(Subdiagnostic)]).
+ - Adds the subdiagnostic represented by the subdiagnostic struct. +
+- Applied to a type that implements
#[primary_span](Optional) +-
+
- Applied to
Spanfields onSubdiagnostics. Not used forLintDiagnostics.
+ - Indicates the primary span of the diagnostic. +
+- Applied to
#[skip_arg](Optional) +-
+
- Applied to any field. +
- Prevents the field from being provided as a diagnostic argument. +
+
#[derive(Subdiagnostic)]
+It is common in the compiler to write a function that conditionally adds a
+specific subdiagnostic to an error if it is applicable. Oftentimes these
+subdiagnostics could be represented using a diagnostic struct even if the
+overall diagnostic could not. In this circumstance, the Subdiagnostic
+derive can be used to represent a partial diagnostic (e.g a note, label, help or
+suggestion) as a struct.
Consider the definition of the "expected return type" label +shown below:
++#![allow(unused)] +fn main() { +#[derive(Subdiagnostic)] +pub enum ExpectedReturnTypeLabel<'tcx> { + #[label(hir_analysis_expected_default_return_type)] + Unit { + #[primary_span] + span: Span, + }, + #[label(hir_analysis_expected_return_type)] + Other { + #[primary_span] + span: Span, + expected: Ty<'tcx>, + }, +} +} +
Like Diagnostic, Subdiagnostic can be derived for structs or
+enums. Attributes that are placed on the type for structs are placed on each
+variants for enums (or vice versa). Each Subdiagnostic should have one
+attribute applied to the struct or each variant, one of:
-
+
#[label(..)]for defining a label
+#[note(..)]for defining a note
+#[help(..)]for defining a help
+#[warning(..)]for defining a warning
+#[suggestion{,_hidden,_short,_verbose}(..)]for defining a suggestion
+
All of the above must provide a slug as the first positional argument (a path
+to an item in rustc_errors::fluent::*). A slug uniquely identifies the
+diagnostic and is also how the compiler knows what error message to emit (in
+the default locale of the compiler, or in the locale requested by the user).
+See translation documentation to learn more about how
+translatable error messages are written and how slug items are generated.
In our example, the Fluent message for the "expected return type" label +looks like this:
+hir_analysis_expected_default_return_type = expected `()` because of default return type
+
+hir_analysis_expected_return_type = expected `{$expected}` because of return type
+Using the #[primary_span] attribute on a field (with type Span) will denote
+the primary span of the subdiagnostic. A primary span is only necessary for a
+label or suggestion, which can not be spanless.
Every field of the type/variant which does not have an annotation is available
+in Fluent messages as a variable. Fields can be annotated #[skip_arg] if this
+is undesired.
Like Diagnostic, Subdiagnostic supports Option<T> and
+Vec<T> fields.
Suggestions can be emitted using one of four attributes on the type/variant:
+-
+
#[suggestion(..., code = "...", applicability = "...")]
+#[suggestion_hidden(..., code = "...", applicability = "...")]
+#[suggestion_short(..., code = "...", applicability = "...")]
+#[suggestion_verbose(..., code = "...", applicability = "...")]
+
Suggestions require #[primary_span] be set on a field and can have the
+following sub-attributes:
-
+
- The first positional argument specifies the path to a item in
+
rustc_errors::fluentcorresponding to the Fluent attribute with the message +and defaults to the equivalent of.suggestion.
+ codespecifies the code that should be suggested as a replacement and is a +format string (e.g.{field_name}would be replaced by the value of the +field_namefield of the struct), not a Fluent identifier.
+applicabilitycan be used to specify the applicability in the attribute, it +cannot be used when the field's type contains anApplicability.
+
Applicabilities can also be specified as a field (of type Applicability)
+using the #[applicability] attribute.
In the end, the Subdiagnostic derive will generate an implementation
+of Subdiagnostic that looks like the following:
+#![allow(unused)] +fn main() { +impl<'tcx> Subdiagnostic for ExpectedReturnTypeLabel<'tcx> { + fn add_to_diag(self, diag: &mut rustc_errors::Diagnostic) { + use rustc_errors::{Applicability, IntoDiagArg}; + match self { + ExpectedReturnTypeLabel::Unit { span } => { + diag.span_label(span, rustc_errors::fluent::hir_analysis_expected_default_return_type) + } + ExpectedReturnTypeLabel::Other { span, expected } => { + diag.set_arg("expected", expected); + diag.span_label(span, rustc_errors::fluent::hir_analysis_expected_return_type) + } + } + } +} +} +
Once defined, a subdiagnostic can be used by passing it to the subdiagnostic
+function (example and example) on a
+diagnostic or by assigning it to a #[subdiagnostic]-annotated field of a
+diagnostic struct.
Reference
+#[derive(Subdiagnostic)] supports the following attributes:
-
+
#[label(slug)],#[help(slug)],#[warning(slug)]or#[note(slug)]+-
+
- Applied to struct or enum variant. Mutually exclusive with struct/enum variant attributes. +
- Mandatory +
- Defines the type to be representing a label, help or note. +
- Slug (Mandatory)
+
-
+
- Uniquely identifies the diagnostic and corresponds to its Fluent message, +mandatory. +
- A path to an item in
rustc_errors::fluent, e.g. +rustc_errors::fluent::hir_analysis_field_already_declared+(rustc_errors::fluentis implicit in the attribute, so just +hir_analysis_field_already_declared).
+ - See translation documentation. +
+
+#[suggestion{,_hidden,_short,_verbose}(slug, code = "...", applicability = "...")]+-
+
- Applied to struct or enum variant. Mutually exclusive with struct/enum variant attributes. +
- Mandatory +
- Defines the type to be representing a suggestion. +
- Slug (Mandatory)
+
-
+
- A path to an item in
rustc_errors::fluent, e.g. +rustc_errors::fluent::hir_analysis_field_already_declared+(rustc_errors::fluentis implicit in the attribute, so just +hir_analysis::field_already_declared). Fluent attributes for all messages +exist as top-level items in that module (sohir_analysis_message.attris just +hir_analysis::attr).
+ - See translation documentation. +
- Defaults to
rustc_errors::fluent::_subdiag::suggestion(or
+ .suggestionin Fluent).
+
+ - A path to an item in
code = "..."/code("...", ...)(Mandatory) +-
+
- One or multiple format strings indicating the code to be suggested as a +replacement. Multiple values signify multiple possible replacements. +
+applicability = "..."(Optional) +-
+
- Mutually exclusive with
#[applicability]on a field.
+ - Value is the applicability of the suggestion. +
- String which must be one of:
+
-
+
machine-applicable
+maybe-incorrect
+has-placeholders
+unspecified
+
+
+- Mutually exclusive with
+#[multipart_suggestion{,_hidden,_short,_verbose}(slug, applicability = "...")]+-
+
- Applied to struct or enum variant. Mutually exclusive with struct/enum variant attributes. +
- Mandatory +
- Defines the type to be representing a multipart suggestion. +
- Slug (Mandatory): see
#[suggestion]
+ applicability = "..."(Optional): see#[suggestion]
+
+#[primary_span](Mandatory for labels and suggestions; optional otherwise; not applicable +to multipart suggestions) +-
+
- Applied to
Spanfields.
+ - Indicates the primary span of the subdiagnostic. +
+- Applied to
#[suggestion_part(code = "...")](Mandatory; only applicable to multipart suggestions) +-
+
- Applied to
Spanfields.
+ - Indicates the span to be one part of the multipart suggestion. +
code = "..."(Mandatory) +-
+
- Value is a format string indicating the code to be suggested as a +replacement. +
+
+- Applied to
#[applicability](Optional; only applicable to (simple and multipart) suggestions) +-
+
- Applied to
Applicabilityfields.
+ - Indicates the applicability of the suggestion. +
+- Applied to
#[skip_arg](Optional) +-
+
- Applied to any field. +
- Prevents the field from being provided as a diagnostic argument. +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/diagnostics/error-guaranteed.html b/diagnostics/error-guaranteed.html
new file mode 100644
index 000000000..830d4b426
--- /dev/null
+++ b/diagnostics/error-guaranteed.html
@@ -0,0 +1,230 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Error codes
+We generally try to assign each error message a unique code like E0123. These
+codes are defined in the compiler in the diagnostics.rs files found in each
+crate, which basically consist of macros. All error codes have an associated
+explanation: new error codes must include them. Note that not all historical
+(no longer emitted) error codes have explanations.
Error explanations
+The explanations are written in Markdown (see the CommonMark Spec for
+specifics around syntax), and all of them are linked in the rustc_error_codes
+crate. Please read RFC 1567 for details on how to format and write long error
+codes. As of February 2023, there is an
+effort1 to replace this largely outdated RFC with a new more
+flexible standard.
Error explanations should expand on the error message and provide details about +why the error occurs. It is not helpful for users to copy-paste a quick fix; +explanations should help users understand why their code cannot be accepted by +the compiler. Rust prides itself on helpful error messages and long-form +explanations are no exception. However, before error explanations are +overhauled1 it is a bit open as to how exactly they should be +written, as always: ask your reviewer or ask around on the Rust Discord or Zulip.
+1
+
+See the draft RFC here.
+Allocating a fresh code
+Error codes are stored in compiler/rustc_error_codes.
To create a new error, you first need to find the next available
+code. You can find it with tidy:
./x test tidy
+This will invoke the tidy script, which generally checks that your code obeys
+our coding conventions. Some of these jobs check error codes and ensure that
+there aren't duplicates, etc (the tidy check is defined in
+src/tools/tidy/src/error_codes.rs). Once it is finished with that, tidy will
+print out the highest used error code:
...
+tidy check
+Found 505 error codes
+Highest error code: `E0591`
+...
+Here we see the highest error code in use is E0591, so we probably want
+E0592. To be sure, run rg E0592 and check, you should see no references.
You will have to write an extended description for your error,
+which will go in rustc_error_codes/src/error_codes/E0592.md.
+To register the error, open rustc_error_codes/src/error_codes.rs and add the
+code (in its proper numerical order) into register_diagnostics! macro, like
+this:
+#![allow(unused)] +fn main() { +register_diagnostics! { + ... + E0592: include_str!("./error_codes/E0592.md"), +} +} +
To actually issue the error, you can use the struct_span_code_err! macro:
+#![allow(unused)] +fn main() { +struct_span_code_err!(self.dcx(), // some path to the `DiagCtxt` here + span, // whatever span in the source you want + E0592, // your new error code + fluent::example::an_error_message) + .emit() // actually issue the error +} +
If you want to add notes or other snippets, you can invoke methods before you
+call .emit():
+#![allow(unused)] +fn main() { +struct_span_code_err!(...) + .span_label(another_span, fluent::example::example_label) + .span_note(another_span, fluent::example::separate_note) + .emit() +} +
For an example of a PR adding an error code, see #76143.
+Running error code doctests
+To test the examples added in rustc_error_codes/src/error_codes, run the
+error index generator using:
./x test ./src/tools/error_index_generator
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/diagnostics/lintstore.html b/diagnostics/lintstore.html
new file mode 100644
index 000000000..904ae4ba7
--- /dev/null
+++ b/diagnostics/lintstore.html
@@ -0,0 +1,288 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ ErrorGuaranteed
+The previous sections have been about the error message that a user of the
+compiler sees. But emitting an error can also have a second important side
+effect within the compiler source code: it generates an
+ErrorGuaranteed.
ErrorGuaranteed is a zero-sized type that is unconstructable outside of the
+rustc_errors crate. It is generated whenever an error is reported
+to the user, so that if your compiler code ever encounters a value of type
+ErrorGuaranteed, the compilation is statically guaranteed to fail. This is
+useful for avoiding unsoundness bugs because you can statically check that an
+error code path leads to a failure.
There are some important considerations about the usage of ErrorGuaranteed:
-
+
- It does not convey information about the kind of error. For example, the
+error may be due (indirectly) to a delayed bug or other compiler error.
+Thus, you should not rely on
+
ErrorGuaranteedwhen deciding whether to emit an error, or what kind of error +to emit.
+ ErrorGuaranteedshould not be used to indicate that a compilation will +emit an error in the future. It should be used to indicate that an error +has already been emitted -- that is, theemit()function has +already been called. For example, if we detect that a future part of the +compiler will error, we cannot useErrorGuaranteedunless we first emit +an error or delayed bug ourselves.
+
Thankfully, in most cases, it should be statically impossible to abuse
+ErrorGuaranteed.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/diagnostics/sessiondiagnostic.html b/diagnostics/sessiondiagnostic.html
new file mode 100644
index 000000000..eba8876f1
--- /dev/null
+++ b/diagnostics/sessiondiagnostic.html
@@ -0,0 +1,12 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Lints
+This page documents some of the machinery around lint registration and how we +run lints in the compiler.
+The LintStore is the central piece of infrastructure, around which
+everything rotates. The LintStore is held as part of the Session, and it
+gets populated with the list of lints shortly after the Session is created.
Lints vs. lint passes
+There are two parts to the linting mechanism within the compiler: lints and +lint passes. Unfortunately, a lot of the documentation we have refers to both +of these as just "lints."
+First, we have the lint declarations themselves,
+and this is where the name and default lint level and other metadata come from.
+These are normally defined by way of the declare_lint! macro,
+which boils down to a static with type &rustc_lint_defs::Lint
+(although this may change in the future,
+as the macro is somewhat unwieldy to add new fields to,
+like all macros).
As of Aug 2022, +we lint against direct declarations without the use of the macro.
+Lint declarations don't carry any "state" - they are merely global identifiers +and descriptions of lints. We assert at runtime that they are not registered +twice (by lint name).
+Lint passes are the meat of any lint. Notably, there is not a one-to-one +relationship between lints and lint passes; a lint might not have any lint pass +that emits it, it could have many, or just one -- the compiler doesn't track +whether a pass is in any way associated with a particular lint, and frequently +lints are emitted as part of other work (e.g., type checking, etc.).
+Registration
+High-level overview
+In rustc_interface::run_compiler,
+the LintStore is created,
+and all lints are registered.
There are three 'sources' of lints:
+-
+
- internal lints: lints only used by the rustc codebase +
- builtin lints: lints built into the compiler and not provided by some outside +source +
rustc_interface::Configregister_lints: lints passed into the compiler +during construction
+
Lints are registered via the LintStore::register_lint function. This should
+happen just once for any lint, or an ICE will occur.
Once the registration is complete, we "freeze" the lint store by placing it in
+an Lrc.
Lint passes are registered separately into one of the categories
+(pre-expansion, early, late, late module). Passes are registered as a closure
+-- i.e., impl Fn() -> Box<dyn X>, where dyn X is either an early or late
+lint pass trait object. When we run the lint passes, we run the closure and
+then invoke the lint pass methods. The lint pass methods take &mut self so
+they can keep track of state internally.
Internal lints
+These are lints used just by the compiler or drivers like clippy. They can be
+found in rustc_lint::internal.
An example of such a lint is the check that lint passes are implemented using
+the declare_lint_pass! macro and not by hand. This is accomplished with the
+LINT_PASS_IMPL_WITHOUT_MACRO lint.
Registration of these lints happens in the rustc_lint::register_internals
+function which is called when constructing a new lint store inside
+rustc_lint::new_lint_store.
Builtin Lints
+These are primarily described in two places,
+rustc_lint_defs::builtin and rustc_lint::builtin.
+Often the first provides the definitions for the lints themselves,
+and the latter provides the lint pass definitions (and implementations),
+but this is not always true.
The builtin lint registration happens in
+the rustc_lint::register_builtins function.
+Just like with internal lints,
+this happens inside of rustc_lint::new_lint_store.
Driver lints
+These are the lints provided by drivers via the rustc_interface::Config
+register_lints field, which is a callback. Drivers should, if finding it
+already set, call the function currently set within the callback they add. The
+best way for drivers to get access to this is by overriding the
+Callbacks::config function which gives them direct access to the Config
+structure.
Compiler lint passes are combined into one pass
+Within the compiler, for performance reasons, we usually do not register dozens
+of lint passes. Instead, we have a single lint pass of each variety (e.g.,
+BuiltinCombinedModuleLateLintPass) which will internally call all of the
+individual lint passes; this is because then we get the benefits of static over
+dynamic dispatch for each of the (often empty) trait methods.
Ideally, we'd not have to do this, since it adds to the complexity of +understanding the code. However, with the current type-erased lint store +approach, it is beneficial to do so for performance reasons.
+ +Redirecting to... diagnostic-structs.html.
+ + diff --git a/diagnostics/translation.html b/diagnostics/translation.html new file mode 100644 index 000000000..ed8d359a7 --- /dev/null +++ b/diagnostics/translation.html @@ -0,0 +1,376 @@ + + + + + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/early-late-bound-params/early-late-bound-implementation-nuances.html b/early-late-bound-params/early-late-bound-implementation-nuances.html
new file mode 100644
index 000000000..0d9c712ad
--- /dev/null
+++ b/early-late-bound-params/early-late-bound-implementation-nuances.html
@@ -0,0 +1,376 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Translation
+
+rustc's current diagnostics translation infrastructure (as of
+ October 2024
+) unfortunately causes some friction for compiler contributors, and the current
+infrastructure is mostly pending a redesign that better addresses needs of both
+compiler contributors and translation teams. Note that there is no current
+active redesign proposals (as of
+ October 2024
+)!
+
+Please see the tracking issue https://github.com/rust-lang/rust/issues/132181 +for status updates.
+We have downgraded the internal lints untranslatable_diagnostic and
+diagnostic_outside_of_impl. Those internal lints previously required new code
+to use the current translation infrastructure. However, because the translation
+infra is waiting for a yet-to-be-proposed redesign and thus rework, we are not
+mandating usage of current translation infra. Use the infra if you want to or
+otherwise makes the code cleaner, but otherwise sidestep the translation infra
+if you need more flexibility.
rustc's diagnostic infrastructure supports translatable diagnostics using +Fluent.
+Writing translatable diagnostics
+There are two ways of writing translatable diagnostics:
+-
+
- For simple diagnostics, using a diagnostic (or subdiagnostic) derive. +("Simple" diagnostics being those that don't require a lot of logic in +deciding to emit subdiagnostics and can therefore be represented as +diagnostic structs). See the diagnostic and subdiagnostic structs +documentation. +
- Using typed identifiers with
DiagAPIs (in +DiagnosticorSubdiagnosticorLintDiagnosticimplementations).
+
When adding or changing a translatable diagnostic,
+you don't need to worry about the translations.
+Only updating the original English message is required.
+Currently,
+each crate which defines translatable diagnostics has its own Fluent resource,
+which is a file named messages.ftl,
+located in the root of the crate
+(such ascompiler/rustc_expand/messages.ftl).
Fluent
+Fluent is built around the idea of "asymmetric localization", which aims to +decouple the expressiveness of translations from the grammar of the source +language (English in rustc's case). Prior to translation, rustc's diagnostics +relied heavily on interpolation to build the messages shown to the users. +Interpolated strings are hard to translate because writing a natural-sounding +translation might require more, less, or just different interpolation than the +English string, all of which would require changes to the compiler's source +code to support.
+Diagnostic messages are defined in Fluent resources. A combined set of Fluent
+resources for a given locale (e.g. en-US) is known as Fluent bundle.
typeck_address_of_temporary_taken = cannot take address of a temporary
+In the above example, typeck_address_of_temporary_taken is the identifier for
+a Fluent message and corresponds to the diagnostic message in English. Other
+Fluent resources can be written which would correspond to a message in another
+language. Each diagnostic therefore has at least one Fluent message.
typeck_address_of_temporary_taken = cannot take address of a temporary
+ .label = temporary value
+By convention, diagnostic messages for subdiagnostics are specified as
+"attributes" on Fluent messages (additional related messages, denoted by the
+.<attribute-name> syntax). In the above example, label is an attribute of
+typeck_address_of_temporary_taken which corresponds to the message for the
+label added to this diagnostic.
Diagnostic messages often interpolate additional context into the message shown +to the user, such as the name of a type or of a variable. Additional context to +Fluent messages is provided as an "argument" to the diagnostic.
+typeck_struct_expr_non_exhaustive =
+ cannot create non-exhaustive {$what} using struct expression
+In the above example, the Fluent message refers to an argument named what
+which is expected to exist (how arguments are provided to diagnostics is
+discussed in detail later).
You can consult the Fluent documentation for other usage examples of Fluent +and its syntax.
+Guideline for message naming
+Usually, fluent uses - for separating words inside a message name. However,
+_ is accepted by fluent as well. As _ fits Rust's use cases better, due to
+the identifiers on the Rust side using _ as well, inside rustc, - is not
+allowed for separating words, and instead _ is recommended. The only exception
+is for leading -s, for message names like -passes_see_issue.
Guidelines for writing translatable messages
+For a message to be translatable into different languages, all of the +information required by any language must be provided to the diagnostic as an +argument (not just the information required in the English message).
+As the compiler team gain more experience writing diagnostics that have all of +the information necessary to be translated into different languages, this page +will be updated with more guidance. For now, the Fluent documentation has +excellent examples of translating messages into different locales and the +information that needs to be provided by the code to do so.
+Compile-time validation and typed identifiers
+rustc's fluent_messages macro performs compile-time validation of Fluent
+resources and generates code to make it easier to refer to Fluent messages in
+diagnostics.
Compile-time validation of Fluent resources will emit any parsing errors +from Fluent resources while building the compiler, preventing invalid Fluent +resources from causing panics in the compiler. Compile-time validation also +emits an error if multiple Fluent messages have the same identifier.
+Internals
+Various parts of rustc's diagnostic internals are modified in order to support +translation.
+Messages
+All of rustc's traditional diagnostic APIs (e.g. struct_span_err or note)
+take any message that can be converted into a DiagMessage (or
+SubdiagMessage).
rustc_error_messages::DiagMessage can represent legacy non-translatable
+diagnostic messages and translatable messages. Non-translatable messages are
+just Strings. Translatable messages are just a &'static str with the
+identifier of the Fluent message (sometimes with an additional &'static str
+with an attribute).
DiagMessage never needs to be interacted with directly:
+DiagMessage constants are created for each diagnostic message in a
+Fluent resource (described in more detail below), or DiagMessages will
+either be created in the macro-generated code of a diagnostic derive.
rustc_error_messages::SubdiagMessage is similar, it can correspond to a
+legacy non-translatable diagnostic message or the name of an attribute to a
+Fluent message. Translatable SubdiagMessages must be combined with a
+DiagMessage (using DiagMessage::with_subdiagnostic_message) to
+be emitted (an attribute name on its own is meaningless without a corresponding
+message identifier, which is what DiagMessage provides).
Both DiagMessage and SubdiagMessage implement Into for any
+type that can be converted into a string, and converts these into
+non-translatable diagnostics - this keeps all existing diagnostic calls
+working.
Arguments
+Additional context for Fluent messages which are interpolated into message +contents needs to be provided to translatable diagnostics.
+Diagnostics have a set_arg function that can be used to provide this
+additional context to a diagnostic.
Arguments have both a name (e.g. "what" in the earlier example) and a value.
+Argument values are represented using the DiagArgValue type, which is
+just a string or a number. rustc types can implement IntoDiagArg with
+conversion into a string or a number, and common types like Ty<'tcx> already
+have such implementations.
set_arg calls are handled transparently by diagnostic derives but need to be
+added manually when using diagnostic builder APIs.
Loading
+rustc makes a distinction between the "fallback bundle" for en-US that is used
+by default and when another locale is missing a message; and the primary fluent
+bundle which is requested by the user.
Diagnostic emitters implement the Emitter trait which has two functions for
+accessing the fallback and primary fluent bundles (fallback_fluent_bundle and
+fluent_bundle respectively).
Emitter also has member functions with default implementations for performing
+translation of a DiagMessage using the results of
+fallback_fluent_bundle and fluent_bundle.
All of the emitters in rustc load the fallback Fluent bundle lazily, only
+reading Fluent resources and parsing them when an error message is first being
+translated (for performance reasons - it doesn't make sense to do this if no
+error is being emitted). rustc_error_messages::fallback_fluent_bundle returns
+a std::lazy::Lazy<FluentBundle> which is provided to emitters and evaluated
+in the first call to Emitter::fallback_fluent_bundle.
The primary Fluent bundle (for the user's desired locale) is expected to be
+returned by Emitter::fluent_bundle. This bundle is used preferentially when
+translating messages, the fallback bundle is only used if the primary bundle is
+missing a message or not provided.
There are no locale bundles distributed with the compiler, +but mechanisms are implemented for loading them.
+-
+
-Ztranslate-additional-ftlcan be used to load a specific resource as the +primary bundle for testing purposes.
+-Ztranslate-langcan be provided a language identifier (something like +en-US) and will load any Fluent resources found in +$sysroot/share/locale/$locale/directory (both the user provided +sysroot and any sysroot candidates).
+
Primary bundles are not currently loaded lazily and if requested will be loaded +at the start of compilation regardless of whether an error occurs. Lazily +loading primary bundles is possible if it can be assumed that loading a bundle +won't fail. Bundle loading can fail if a requested locale is missing, Fluent +files are malformed, or a message is duplicated in multiple resources.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/early-late-bound-params/turbofishing-and-early-late-bound.html b/early-late-bound-params/turbofishing-and-early-late-bound.html
new file mode 100644
index 000000000..8c7526380
--- /dev/null
+++ b/early-late-bound-params/turbofishing-and-early-late-bound.html
@@ -0,0 +1,312 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Early and Late Bound Parameter Implementation Nuances
+++Note: this chapter makes reference to information discussed later on in the representing types chapter. Specifically, it uses concise notation to represent some more complex kinds of types that have not yet been discussed, such as inference variables.
+
Understanding this page likely requires a rudimentary understanding of higher ranked
+trait bounds/for<'a>and also what types such as dyn for<'a> Trait<'a> and
+for<'a> fn(&'a u32) mean. Reading the nomincon chapter
+on HRTB may be useful for understanding this syntax. The meaning of for<'a> fn(&'a u32)
+is incredibly similar to the meaning of T: for<'a> Trait<'a>.
What does it mean for parameters to be early or late bound
+All function definitions conceptually have a ZST (this is represented by TyKind::FnDef in rustc).
+The only generics on this ZST are the early bound parameters of the function definition. e.g.
+fn foo<'a>(_: &'a u32) {} + +fn main() { + let b = foo; + // ^ `b` has type `FnDef(foo, [])` (no args because `'a` is late bound) + assert!(std::mem::size_of_val(&b) == 0); +} +
In order to call b the late bound parameters do need to be provided, these are inferred at the
+call site instead of when we refer to foo.
+fn main() { + let b = foo; + let a: &'static u32 = &10; + foo(a); + // the lifetime argument for `'a` on `foo` is inferred at the callsite + // the generic parameter `'a` on `foo` is inferred to `'static` here +} +
Because late bound parameters are not part of the FnDef's args this allows us to prove trait
+bounds such as F: for<'a> Fn(&'a u32) where F is foo's FnDef. e.g.
+fn foo_early<'a, T: Trait<'a>>(_: &'a u32, _: T) {} +fn foo_late<'a, T>(_: &'a u32, _: T) {} + +fn accepts_hr_func<F: for<'a> Fn(&'a u32, u32)>(_: F) {} + +fn main() { + // doesn't work, the instantiated bound is `for<'a> FnDef<'?0>: Fn(&'a u32, u32)` + // `foo_early` only implements `for<'a> FnDef<'a>: Fn(&'a u32, u32)`- the lifetime + // of the borrow in the function argument must be the same as the lifetime + // on the `FnDef`. + accepts_hr_func(foo_early); + + // works, the instantiated bound is `for<'a> FnDef: Fn(&'a u32, u32)` + accepts_hr_func(foo_late); +} + +// the builtin `Fn` impls for `foo_early` and `foo_late` look something like: +// `foo_early` +impl<'a, T: Trait<'a>> Fn(&'a u32, T) for FooEarlyFnDef<'a, T> { ... } +// `foo_late` +impl<'a, T> Fn(&'a u32, T) for FooLateFnDef<T> { ... } + +
Early bound parameters are present on the FnDef. Late bound generic parameters are not present
+on the FnDef but are instead constrained by the builtin Fn* impl.
The same distinction applies to closures. Instead of FnDef we are talking about the anonymous
+closure type. Closures are currently unsound in
+ways that are closely related to the distinction between early/late bound
+parameters (more on this later)
The early/late boundness of generic parameters is only relevant for the desugaring of
+functions/closures into types with builtin Fn* impls. It does not make sense to talk about
+in other contexts.
The generics_of query in rustc only contains early bound parameters. In this way it acts more
+like generics_of(my_func) is the generics for the FnDef than the generics provided to the function
+body although it's not clear to the author of this section if this was the actual justification for
+making generics_of behave this way.
What parameters are currently late bound
+Below are the current requirements for determining if a generic parameter is late bound. It is worth +keeping in mind that these are not necessarily set in stone and it is almost certainly possible to +be more flexible.
+Must be a lifetime parameter
+Rust can't support types such as for<T> dyn Trait<T> or for<T> fn(T), this is a
+fundamental limitation of the language as we are required to monomorphize type/const
+parameters and cannot do so behind dynamic dispatch. (technically we could probably
+support for<T> dyn MarkerTrait<T> as there is nothing to monomorphize)
Not being able to support for<T> dyn Trait<T> resulted in making all type and const
+parameters early bound. Only lifetime parameters can be late bound.
Must not appear in the where clauses
+In order for a generic parameter to be late bound it must not appear in any where clauses. +This is currently an incredibly simplistic check that causes lifetimes to be early bound even +if the where clause they appear in are always true, or implied by well formedness of function +arguments. e.g.
++#![allow(unused)] +fn main() { +fn foo1<'a: 'a>(_: &'a u32) {} +// ^^ early bound parameter because it's in a `'a: 'a` clause +// even though the bound obviously holds all the time +fn foo2<'a, T: Trait<'a>(a: T, b: &'a u32) {} +// ^^ early bound parameter because it's used in the `T: Trait<'a>` clause +fn foo3<'a, T: 'a>(_: &'a T) {} +// ^^ early bound parameter because it's used in the `T: 'a` clause +// even though that bound is implied by wellformedness of `&'a T` +fn foo4<'a, 'b: 'a>(_: Inv<&'a ()>, _: Inv<&'b ()>) {} +// ^^ ^^ ^^^ note: +// ^^ ^^ `Inv` stands for `Invariant` and is used to +// ^^ ^^ make the type parameter invariant. This +// ^^ ^^ is necessary for demonstration purposes as +// ^^ ^^ `for<'a, 'b> fn(&'a (), &'b ())` and +// ^^ ^^ `for<'a> fn(&'a u32, &'a u32)` are subtypes- +// ^^ ^^ of each other which makes the bound trivially +// ^^ ^^ satisfiable when making the fnptr. `Inv` +// ^^ ^^ disables this subtyping. +// ^^ ^^ +// ^^^^^^ both early bound parameters because they are present in the +// `'b: 'a` clause +} +
The reason for this requirement is that we cannot represent the T: Trait<'a> or 'a: 'b clauses
+on a function pointer. for<'a, 'b> fn(Inv<&'a ()>, Inv<&'b ()>) is not a valid function pointer to
+representfoo4 as it would allow calling the function without 'b: 'a holding.
Must be constrained by where clauses or function argument types
+The builtin impls of the Fn* traits for closures and FnDefs cannot not have any unconstrained
+parameters. For example the following impl is illegal:
+#![allow(unused)] +fn main() { +impl<'a> Trait for u32 { type Assoc = &'a u32; } +} +
We must not end up with a similar impl for the Fn* traits e.g.
+#![allow(unused)] +fn main() { +impl<'a> Fn<()> for FnDef { type Assoc = &'a u32 } +} +
Violating this rule can trivially lead to unsoundness as seen in #84366. +Additionally if we ever support late bound type params then an impl like:
++#![allow(unused)] +fn main() { +impl<T> Fn<()> for FnDef { type Assoc = T; } +} +
would break the compiler in various ways.
+In order to ensure that everything functions correctly, we do not allow generic parameters to +be late bound if it would result in a builtin impl that does not constrain all of the generic +parameters on the builtin impl. Making a generic parameter be early bound trivially makes it be +constrained by the builtin impl as it ends up on the self type.
+Because of the requirement that late bound parameters must not appear in where clauses, checking +this is simpler than the rules for checking impl headers constrain all the parameters on the impl. +We only have to ensure that all late bound parameters appear at least once in the function argument +types outside of an alias (e.g. an associated type).
+The requirement that they not indirectly be in the args of an alias for it to count is the +same as why the follow code is forbidden:
++#![allow(unused)] +fn main() { +impl<T: Trait> OtherTrait for <T as Trait>::Assoc { type Assoc = T } +} +
There is no guarantee that <T as Trait>::Assoc will normalize to different types for every
+instantiation of T. If we were to allow this impl we could get overlapping impls and the
+same is true of the builtin Fn* impls.
Making more generic parameters late bound
+It is generally considered desirable for more parameters to be late bound as it makes
+the builtin Fn* impls more flexible. Right now many of the requirements for making
+a parameter late bound are overly restrictive as they are tied to what we can currently
+(or can ever) do with fn ptrs.
It would be theoretically possible to support late bound params in where-clauses in the
+language by introducing implication types which would allow us to express types such as:
+for<'a, 'b: 'a> fn(Inv<&'a u32>, Inv<&'b u32>) which would ensure 'b: 'a is upheld when
+calling the function pointer.
It would also be theoretically possible to support it by making the coercion to a fn ptr
+instantiate the parameter with an infer var while still allowing the FnDef to not have the
+generic parameter present as trait impls are perfectly capable of representing the where clauses
+on the function on the impl itself. This would also allow us to support late bound type/const
+vars allowing bounds like F: for<T> Fn(T) to hold.
It is almost somewhat unclear if we can change the Fn traits to be structured differently
+so that we never have to make a parameter early bound just to make the builtin impl have all
+generics be constrained. Of all the possible causes of a generic parameter being early bound
+this seems the most difficult to remove.
Whether these would be good ideas to implement is a separate question- they are only brought +up to illustrate that the current rules are not necessarily set in stone and a result of +"its the only way of doing this".
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/effects.html b/effects.html
new file mode 100644
index 000000000..17e782547
--- /dev/null
+++ b/effects.html
@@ -0,0 +1,256 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Turbofishing's interactions with early/late bound parameters
+++Note: this chapter makes reference to information discussed later on in the representing types chapter. Specifically, it uses concise notation to represent some more complex kinds of types that have not yet been discussed, such as inference variables.
+
The early/late bound parameter distinction on functions introduces some complications +when providing generic arguments to functions. This document discusses what those are +and how they might interact with future changes to make more things late bound.
+Can't turbofish generic arguments on functions sometimes
+When a function has any late bound lifetime parameters (be they explicitly defined or
+implicitly introduced via lifetime elision) we disallow specifying any lifetime arguments
+on the function. Sometimes this is a hard error other times it is a future compat lint
+(late_bound_lifetime_arguments).
+fn early<'a: 'a>(a: &'a ()) -> &'a () { a } +fn late<'a>(a: &'a ()) -> &'a () { a } + +fn mixed<'a, 'b: 'b>(a: &'a (), b: &'b ()) -> &'a () { a } + +struct Foo; +impl Foo { + fn late<'a>(self, a: &'a ()) -> &'a () { a } +} + +fn main() { + // fine + let f = early::<'static>; + + // some variation of hard errors and future compat lints + Foo.late::<'static>(&()); + let f = late::<'static>; + let f = mixed::<'static, 'static>; + let f = mixed::<'static>; + late::<'static>(&()); +} +
The justification for this is that late bound parameters are not present on the
+FnDef so the arguments to late bound parameters can't be present in the generic arguments
+for the type. i.e. the late function in the above code snippet would not have
+any generic parameters on the FnDef zst:
+#![allow(unused)] +fn main() { +// example desugaring of the `late` function and its zst + builtin Fn impl +struct LateFnDef; +impl<'a> Fn<(&'a ())> for LateFnDef { + type Output = &'a (); + ... +} +} +
The cause for some situations giving future compat lints and others giving hard errors +is a little arbitrary but explainable:
+-
+
- It's always a hard error for method calls +
- It's only a hard error on paths to free functions if there is no unambiguous way to +create the generic arguments for the fndef from the lifetime arguments. (i.e. the amount of +lifetimes provided must be exactly equal to the amount of early bound lifetimes or +else it's a hard error) +
Back compat issues from turning early bound to late bound
+Because of the previously mentioned restriction on turbofishing generic arguments, it +is a breaking change to upgrade a lifetime from early bound to late bound as it can cause +existing turbofishies to become hard errors/future compat lints.
+Many t-types members have expressed interest in wanting more parameters to be late bound. +We cannot do so if making something late bound is going to break code that many would +expect to work (judging by the future compat lint issue many people do expect to be able +to turbofish late bound parameters).
+Interactions with late bound type/const parameters
+If we were to make some type/const parameters late bound we would definitely not want +to disallow turbofishing them as it presumably(?) would break a Tonne of code.
+While lifetimes do differ from type/consts in some ways I(BoxyUwU) do not believe there +is any justification for why it would make sense to allow turbofishing late bound +type/const parameters but not late bound lifetimes.
+Removing the hard error/fcw
+From reasons above it seems reasonable that we may want to remove the hard error and fcw +(removing the errors/fcw is definitely a blocker for making more things late bound).
+example behaviour:
++fn late<'a>(a: &'a ()) -> &'a () { a } + +fn accepts_fn(_: impl for<'a> Fn(&'a ()) -> &'a ()) {} +fn accepts_fn_2(_: impl Fn(&'static ()) -> &'static ()) {} + +fn main() { + let f = late::<'static>; + + accepts_fn(f); //~ error: `f` doesn't implement `for<'a> Fn(&'a ()) -> &'a ()` + accepts_fn_2(f) // works + + accepts_fn(late) // works +} +
one potential complication is that we would want a way to specify a generic argument +to a function without having to specify arguments for all previous parameters. i.e. +ideally you could write the following code somehow.
++fn late<'a, 'b>(_: &'a (), _: &'b ()) {} + +fn accepts_fn(_: impl for<'a> Fn(&'a (), &'static ())) {} + +fn main() { + // a naive implementation would have an inference variable as + // the argument to the `'a` parameter no longer allowing the `FnDef` + // to satisfy the bound `for<'a> Fn(&'a ())` + let f = late::<'_, 'static>; + accepts_fn(f); +} +
Maybe we can just special case HIR ty lowering for _/'_ arguments for late bound
+parameters somehow and have it not mean the same thing as _ for early bound parameters.
+Regardless I think we would need a solution that would allow writing the above code even
+if it was done by some new syntax such as having to write late::<k#no_argument, 'static>
+(naturally k#no_argument would only make sense as an argument to late bound parameters).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/elasticlunr.min.js b/elasticlunr.min.js
new file mode 100644
index 000000000..94b20dd2e
--- /dev/null
+++ b/elasticlunr.min.js
@@ -0,0 +1,10 @@
+/**
+ * elasticlunr - http://weixsong.github.io
+ * Lightweight full-text search engine in Javascript for browser search and offline search. - 0.9.5
+ *
+ * Copyright (C) 2017 Oliver Nightingale
+ * Copyright (C) 2017 Wei Song
+ * MIT Licensed
+ * @license
+ */
+!function(){function e(e){if(null===e||"object"!=typeof e)return e;var t=e.constructor();for(var n in e)e.hasOwnProperty(n)&&(t[n]=e[n]);return t}var t=function(e){var n=new t.Index;return n.pipeline.add(t.trimmer,t.stopWordFilter,t.stemmer),e&&e.call(n,n),n};t.version="0.9.5",lunr=t,t.utils={},t.utils.warn=function(e){return function(t){e.console&&console.warn&&console.warn(t)}}(this),t.utils.toString=function(e){return void 0===e||null===e?"":e.toString()},t.EventEmitter=function(){this.events={}},t.EventEmitter.prototype.addListener=function(){var e=Array.prototype.slice.call(arguments),t=e.pop(),n=e;if("function"!=typeof t)throw new TypeError("last argument must be a function");n.forEach(function(e){this.hasHandler(e)||(this.events[e]=[]),this.events[e].push(t)},this)},t.EventEmitter.prototype.removeListener=function(e,t){if(this.hasHandler(e)){var n=this.events[e].indexOf(t);-1!==n&&(this.events[e].splice(n,1),0==this.events[e].length&&delete this.events[e])}},t.EventEmitter.prototype.emit=function(e){if(this.hasHandler(e)){var t=Array.prototype.slice.call(arguments,1);this.events[e].forEach(function(e){e.apply(void 0,t)},this)}},t.EventEmitter.prototype.hasHandler=function(e){return e in this.events},t.tokenizer=function(e){if(!arguments.length||null===e||void 0===e)return[];if(Array.isArray(e)){var n=e.filter(function(e){return null===e||void 0===e?!1:!0});n=n.map(function(e){return t.utils.toString(e).toLowerCase()});var i=[];return n.forEach(function(e){var n=e.split(t.tokenizer.seperator);i=i.concat(n)},this),i}return e.toString().trim().toLowerCase().split(t.tokenizer.seperator)},t.tokenizer.defaultSeperator=/[\s\-]+/,t.tokenizer.seperator=t.tokenizer.defaultSeperator,t.tokenizer.setSeperator=function(e){null!==e&&void 0!==e&&"object"==typeof e&&(t.tokenizer.seperator=e)},t.tokenizer.resetSeperator=function(){t.tokenizer.seperator=t.tokenizer.defaultSeperator},t.tokenizer.getSeperator=function(){return t.tokenizer.seperator},t.Pipeline=function(){this._queue=[]},t.Pipeline.registeredFunctions={},t.Pipeline.registerFunction=function(e,n){n in t.Pipeline.registeredFunctions&&t.utils.warn("Overwriting existing registered function: "+n),e.label=n,t.Pipeline.registeredFunctions[n]=e},t.Pipeline.getRegisteredFunction=function(e){return e in t.Pipeline.registeredFunctions!=!0?null:t.Pipeline.registeredFunctions[e]},t.Pipeline.warnIfFunctionNotRegistered=function(e){var n=e.label&&e.label in this.registeredFunctions;n||t.utils.warn("Function is not registered with pipeline. This may cause problems when serialising the index.\n",e)},t.Pipeline.load=function(e){var n=new t.Pipeline;return e.forEach(function(e){var i=t.Pipeline.getRegisteredFunction(e);if(!i)throw new Error("Cannot load un-registered function: "+e);n.add(i)}),n},t.Pipeline.prototype.add=function(){var e=Array.prototype.slice.call(arguments);e.forEach(function(e){t.Pipeline.warnIfFunctionNotRegistered(e),this._queue.push(e)},this)},t.Pipeline.prototype.after=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._queue.indexOf(e);if(-1===i)throw new Error("Cannot find existingFn");this._queue.splice(i+1,0,n)},t.Pipeline.prototype.before=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._queue.indexOf(e);if(-1===i)throw new Error("Cannot find existingFn");this._queue.splice(i,0,n)},t.Pipeline.prototype.remove=function(e){var t=this._queue.indexOf(e);-1!==t&&this._queue.splice(t,1)},t.Pipeline.prototype.run=function(e){for(var t=[],n=e.length,i=this._queue.length,o=0;n>o;o++){for(var r=e[o],s=0;i>s&&(r=this._queue[s](r,o,e),void 0!==r&&null!==r);s++);void 0!==r&&null!==r&&t.push(r)}return t},t.Pipeline.prototype.reset=function(){this._queue=[]},t.Pipeline.prototype.get=function(){return this._queue},t.Pipeline.prototype.toJSON=function(){return this._queue.map(function(e){return t.Pipeline.warnIfFunctionNotRegistered(e),e.label})},t.Index=function(){this._fields=[],this._ref="id",this.pipeline=new t.Pipeline,this.documentStore=new t.DocumentStore,this.index={},this.eventEmitter=new t.EventEmitter,this._idfCache={},this.on("add","remove","update",function(){this._idfCache={}}.bind(this))},t.Index.prototype.on=function(){var e=Array.prototype.slice.call(arguments);return this.eventEmitter.addListener.apply(this.eventEmitter,e)},t.Index.prototype.off=function(e,t){return this.eventEmitter.removeListener(e,t)},t.Index.load=function(e){e.version!==t.version&&t.utils.warn("version mismatch: current "+t.version+" importing "+e.version);var n=new this;n._fields=e.fields,n._ref=e.ref,n.documentStore=t.DocumentStore.load(e.documentStore),n.pipeline=t.Pipeline.load(e.pipeline),n.index={};for(var i in e.index)n.index[i]=t.InvertedIndex.load(e.index[i]);return n},t.Index.prototype.addField=function(e){return this._fields.push(e),this.index[e]=new t.InvertedIndex,this},t.Index.prototype.setRef=function(e){return this._ref=e,this},t.Index.prototype.saveDocument=function(e){return this.documentStore=new t.DocumentStore(e),this},t.Index.prototype.addDoc=function(e,n){if(e){var n=void 0===n?!0:n,i=e[this._ref];this.documentStore.addDoc(i,e),this._fields.forEach(function(n){var o=this.pipeline.run(t.tokenizer(e[n]));this.documentStore.addFieldLength(i,n,o.length);var r={};o.forEach(function(e){e in r?r[e]+=1:r[e]=1},this);for(var s in r){var u=r[s];u=Math.sqrt(u),this.index[n].addToken(s,{ref:i,tf:u})}},this),n&&this.eventEmitter.emit("add",e,this)}},t.Index.prototype.removeDocByRef=function(e){if(e&&this.documentStore.isDocStored()!==!1&&this.documentStore.hasDoc(e)){var t=this.documentStore.getDoc(e);this.removeDoc(t,!1)}},t.Index.prototype.removeDoc=function(e,n){if(e){var n=void 0===n?!0:n,i=e[this._ref];this.documentStore.hasDoc(i)&&(this.documentStore.removeDoc(i),this._fields.forEach(function(n){var o=this.pipeline.run(t.tokenizer(e[n]));o.forEach(function(e){this.index[n].removeToken(e,i)},this)},this),n&&this.eventEmitter.emit("remove",e,this))}},t.Index.prototype.updateDoc=function(e,t){var t=void 0===t?!0:t;this.removeDocByRef(e[this._ref],!1),this.addDoc(e,!1),t&&this.eventEmitter.emit("update",e,this)},t.Index.prototype.idf=function(e,t){var n="@"+t+"/"+e;if(Object.prototype.hasOwnProperty.call(this._idfCache,n))return this._idfCache[n];var i=this.index[t].getDocFreq(e),o=1+Math.log(this.documentStore.length/(i+1));return this._idfCache[n]=o,o},t.Index.prototype.getFields=function(){return this._fields.slice()},t.Index.prototype.search=function(e,n){if(!e)return[];e="string"==typeof e?{any:e}:JSON.parse(JSON.stringify(e));var i=null;null!=n&&(i=JSON.stringify(n));for(var o=new t.Configuration(i,this.getFields()).get(),r={},s=Object.keys(e),u=0;u
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Effects and effect checking
+Note: all of this describes the implementation of the unstable effects and
+const_trait_impl features. None of this implementation is usable or visible from
+stable Rust.
The implementation of const traits and ~const bounds is a limited effect system.
+It is used to allow trait bounds on const fn to be used within the const fn for
+method calls. Within the function, in order to know whether a method on a trait
+bound is const, we need to know whether there is a ~const bound for the trait.
+In order to know whether we can instantiate a ~const bound on a const fn, we
+need to know whether there is a const_trait impl for the type and trait being
+used (or whether the const fn is used at runtime, then any type implementing the
+trait is ok, just like with other bounds).
We perform these checks via a const generic boolean that gets attached to all
+const fn and const trait. The following sections will explain the desugarings
+and the way we perform the checks at call sites.
The const generic boolean is inverted to the meaning of const. In the compiler
+it is called host, because it enables "host APIs" like static items, network
+access, disk access, random numbers and everything else that isn't available in
+const contexts. So false means "const", true means "not const" and if it's
+a generic parameter, it means "maybe const" (meaning we're in a const fn or const
+trait).
const fn
+All const fn have a #[rustc_host] const host: bool generic parameter that is
+hidden from users. Any ~const Trait bounds in the generics list or where bounds
+of a const fn get converted to Trait<host> + Trait<true> bounds. The Trait<true>
+exists so that associated types of the generic param can be used from projections
+like <T as Trait>::Assoc, because there are no <T as ~const Trait> projections for now.
#[const_trait] traits
+The #[const_trait] attribute gives the marked trait a #[rustc_host] const host: bool
+generic parameter. All functions of the trait "inherit" this generic parameter, just like
+they have all the regular generic parameters of the trait. Any ~const Trait super-trait
+bounds get desugared to Trait<host> + Trait<true> in order to allow using associated
+types and consts of the super traits in the trait declaration. This is necessary, because
+<Self as SuperTrait>::Assoc is always <Self as SuperTrait<true>>::Assoc as there is
+no <Self as ~const SuperTrait> syntax.
typeck performing method and function call checks.
+When generic parameters are instantiated for any items, the host generic parameter
+is always instantiated as an inference variable. This is a special kind of inference var
+that is not part of the type or const inference variables, similar to how we have
+special inference variables for type variables that we know to be an integer, but not
+yet which one. These separate inference variables fall back to true at
+the end of typeck (in fallback_effects) to ensure that let _ = some_fn_item_name;
+will keep compiling.
All actually used (in function calls, casts, or anywhere else) function items, will
+have the enforce_context_effects method invoked.
+It trivially returns if the function being called has no host generic parameter.
In order to error if a non-const function is called in a const context, we have not
+yet disabled the const-check logic that happens on MIR, because
+enforce_context_effects does not yet perform this check.
The function call's host parameter is then equated to the context's host value,
+which almost always trivially succeeds, as it was an inference var. If the inference
+var has already been bound (since the function item is invoked twice), the second
+invocation checks it against the first.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/favicon.png b/favicon.png
new file mode 100644
index 000000000..a5b1aa16c
Binary files /dev/null and b/favicon.png differ
diff --git a/favicon.svg b/favicon.svg
new file mode 100644
index 000000000..90e0ea58b
--- /dev/null
+++ b/favicon.svg
@@ -0,0 +1,22 @@
+
+
diff --git a/feature-gate-ck.html b/feature-gate-ck.html
new file mode 100644
index 000000000..fdffb0bc0
--- /dev/null
+++ b/feature-gate-ck.html
@@ -0,0 +1,205 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Using External Repositories
+The rust-lang/rust git repository depends on several other repos in the rust-lang organization.
+There are three main ways we use dependencies:
-
+
- As a Cargo dependency through crates.io (e.g.
rustc-rayon)
+ - As a git subtree (e.g.
clippy)
+ - As a git submodule (e.g.
cargo)
+
As a general rule, use crates.io for libraries that could be useful for others in the ecosystem; use +subtrees for tools that depend on compiler internals and need to be updated if there are breaking +changes; and use submodules for tools that are independent of the compiler.
+External Dependencies (subtree)
+As a developer to this repository, you don't have to treat the following external projects +differently from other crates that are directly in this repo:
+-
+
- Clippy +
- Miri +
- rustfmt +
- rust-analyzer +
In contrast to submodule dependencies
+(see below for those), the subtree dependencies are just regular files and directories which can
+be updated in tree. However, if possible, enhancements, bug fixes, etc. specific
+to these tools should be filed against the tools directly in their respective
+upstream repositories. The exception is that when rustc changes are required to
+implement a new tool feature or test, that should happen in one collective rustc PR.
Synchronizing a subtree
+Periodically the changes made to subtree based dependencies need to be synchronized between this +repository and the upstream tool repositories.
+Subtree synchronizations are typically handled by the respective tool maintainers. Other users +are welcome to submit synchronization PRs, however, in order to do so you will need to modify +your local git installation and follow a very precise set of instructions. +These instructions are documented, along with several useful tips and tricks, in the +syncing subtree changes section in Clippy's Contributing guide. +The instructions are applicable for use with any subtree based tool, just be sure to +use the correct corresponding subtree directory and remote repository.
+The synchronization process goes in two directions: subtree push and subtree pull.
A subtree push takes all the changes that happened to the copy in this repo and creates commits
+on the remote repo that match the local changes. Every local
+commit that touched the subtree causes a commit on the remote repo, but
+is modified to move the files from the specified directory to the tool repo root.
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.
+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
+rebase the result of a git subtree pull, rebasing merge commits is a bad idea in general.
You always need to specify the -P prefix to the subtree directory and the corresponding remote
+repository. If you specify the wrong directory or repository
+you'll get very fun merges that try to push the wrong directory to the wrong remote repository.
+Luckily you can just abort this without any consequences by throwing away either the pulled commits
+in rustc or the pushed branch on the remote and try again. It is usually fairly obvious
+that this is happening because you suddenly get thousands of commits that want to be synchronized.
Creating a new subtree dependency
+If you want to create a new subtree dependency from an existing repository, call (from this +repository's root directory!)
+git subtree add -P src/tools/clippy https://github.com/rust-lang/rust-clippy.git master
+This will create a new commit, which you may not rebase under any circumstances! Delete the commit +and redo the operation if you need to rebase.
+Now you're done, the src/tools/clippy directory behaves as if Clippy were
+part of the rustc monorepo, so no one but you (or others that synchronize
+subtrees) actually needs to use git subtree.
External Dependencies (submodules)
+Building Rust will also use external git repositories tracked using git
+submodules. The complete list may be found in the .gitmodules file. Some
+of these projects are required (like stdarch for the standard library) and
+some of them are optional (like src/doc/book).
Usage of submodules is discussed more in the Using Git chapter.
+Some of the submodules are allowed to be in a "broken" state where they +either don't build or their tests don't pass, e.g. the documentation books +like The Rust Reference. Maintainers of these projects will be notified +when the project is in a broken state, and they should fix them as soon +as possible. The current status is tracked on the toolstate website. +More information may be found on the Forge Toolstate chapter. +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 +the week leading up to the beta cut.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/feature-gates.html b/feature-gates.html
new file mode 100644
index 000000000..b1f6c5033
--- /dev/null
+++ b/feature-gates.html
@@ -0,0 +1,262 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Feature Gate Checking
+TODO: this chapter #1158
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/fonts/OPEN-SANS-LICENSE.txt b/fonts/OPEN-SANS-LICENSE.txt
new file mode 100644
index 000000000..d64569567
--- /dev/null
+++ b/fonts/OPEN-SANS-LICENSE.txt
@@ -0,0 +1,202 @@
+
+ Apache License
+ Version 2.0, January 2004
+ http://www.apache.org/licenses/
+
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+ 1. Definitions.
+
+ "License" shall mean the terms and conditions for use, reproduction,
+ and distribution as defined by Sections 1 through 9 of this document.
+
+ "Licensor" shall mean the copyright owner or entity authorized by
+ the copyright owner that is granting the License.
+
+ "Legal Entity" shall mean the union of the acting entity and all
+ other entities that control, are controlled by, or are under common
+ control with that entity. For the purposes of this definition,
+ "control" means (i) the power, direct or indirect, to cause the
+ direction or management of such entity, whether by contract or
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
+ outstanding shares, or (iii) beneficial ownership of such entity.
+
+ "You" (or "Your") shall mean an individual or Legal Entity
+ exercising permissions granted by this License.
+
+ "Source" form shall mean the preferred form for making modifications,
+ including but not limited to software source code, documentation
+ source, and configuration files.
+
+ "Object" form shall mean any form resulting from mechanical
+ transformation or translation of a Source form, including but
+ not limited to compiled object code, generated documentation,
+ and conversions to other media types.
+
+ "Work" shall mean the work of authorship, whether in Source or
+ Object form, made available under the License, as indicated by a
+ copyright notice that is included in or attached to the work
+ (an example is provided in the Appendix below).
+
+ "Derivative Works" shall mean any work, whether in Source or Object
+ form, that is based on (or derived from) the Work and for which the
+ editorial revisions, annotations, elaborations, or other modifications
+ represent, as a whole, an original work of authorship. For the purposes
+ of this License, Derivative Works shall not include works that remain
+ separable from, or merely link (or bind by name) to the interfaces of,
+ the Work and Derivative Works thereof.
+
+ "Contribution" shall mean any work of authorship, including
+ the original version of the Work and any modifications or additions
+ to that Work or Derivative Works thereof, that is intentionally
+ submitted to Licensor for inclusion in the Work by the copyright owner
+ or by an individual or Legal Entity authorized to submit on behalf of
+ the copyright owner. For the purposes of this definition, "submitted"
+ means any form of electronic, verbal, or written communication sent
+ to the Licensor or its representatives, including but not limited to
+ communication on electronic mailing lists, source code control systems,
+ and issue tracking systems that are managed by, or on behalf of, the
+ Licensor for the purpose of discussing and improving the Work, but
+ excluding communication that is conspicuously marked or otherwise
+ designated in writing by the copyright owner as "Not a Contribution."
+
+ "Contributor" shall mean Licensor and any individual or Legal Entity
+ on behalf of whom a Contribution has been received by Licensor and
+ subsequently incorporated within the Work.
+
+ 2. Grant of Copyright License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ copyright license to reproduce, prepare Derivative Works of,
+ publicly display, publicly perform, sublicense, and distribute the
+ Work and such Derivative Works in Source or Object form.
+
+ 3. Grant of Patent License. Subject to the terms and conditions of
+ this License, each Contributor hereby grants to You a perpetual,
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+ (except as stated in this section) patent license to make, have made,
+ use, offer to sell, sell, import, and otherwise transfer the Work,
+ where such license applies only to those patent claims licensable
+ by such Contributor that are necessarily infringed by their
+ Contribution(s) alone or by combination of their Contribution(s)
+ with the Work to which such Contribution(s) was submitted. If You
+ institute patent litigation against any entity (including a
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
+ or a Contribution incorporated within the Work constitutes direct
+ or contributory patent infringement, then any patent licenses
+ granted to You under this License for that Work shall terminate
+ as of the date such litigation is filed.
+
+ 4. Redistribution. You may reproduce and distribute copies of the
+ Work or Derivative Works thereof in any medium, with or without
+ modifications, and in Source or Object form, provided that You
+ meet the following conditions:
+
+ (a) You must give any other recipients of the Work or
+ Derivative Works a copy of this License; and
+
+ (b) You must cause any modified files to carry prominent notices
+ stating that You changed the files; and
+
+ (c) You must retain, in the Source form of any Derivative Works
+ that You distribute, all copyright, patent, trademark, and
+ attribution notices from the Source form of the Work,
+ excluding those notices that do not pertain to any part of
+ the Derivative Works; and
+
+ (d) If the Work includes a "NOTICE" text file as part of its
+ distribution, then any Derivative Works that You distribute must
+ include a readable copy of the attribution notices contained
+ within such NOTICE file, excluding those notices that do not
+ pertain to any part of the Derivative Works, in at least one
+ of the following places: within a NOTICE text file distributed
+ as part of the Derivative Works; within the Source form or
+ documentation, if provided along with the Derivative Works; or,
+ within a display generated by the Derivative Works, if and
+ wherever such third-party notices normally appear. The contents
+ of the NOTICE file are for informational purposes only and
+ do not modify the License. You may add Your own attribution
+ notices within Derivative Works that You distribute, alongside
+ or as an addendum to the NOTICE text from the Work, provided
+ that such additional attribution notices cannot be construed
+ as modifying the License.
+
+ You may add Your own copyright statement to Your modifications and
+ may provide additional or different license terms and conditions
+ for use, reproduction, or distribution of Your modifications, or
+ for any such Derivative Works as a whole, provided Your use,
+ reproduction, and distribution of the Work otherwise complies with
+ the conditions stated in this License.
+
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
+ any Contribution intentionally submitted for inclusion in the Work
+ by You to the Licensor shall be under the terms and conditions of
+ this License, without any additional terms or conditions.
+ Notwithstanding the above, nothing herein shall supersede or modify
+ the terms of any separate license agreement you may have executed
+ with Licensor regarding such Contributions.
+
+ 6. Trademarks. This License does not grant permission to use the trade
+ names, trademarks, service marks, or product names of the Licensor,
+ except as required for reasonable and customary use in describing the
+ origin of the Work and reproducing the content of the NOTICE file.
+
+ 7. Disclaimer of Warranty. Unless required by applicable law or
+ agreed to in writing, Licensor provides the Work (and each
+ Contributor provides its Contributions) on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+ implied, including, without limitation, any warranties or conditions
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+ PARTICULAR PURPOSE. You are solely responsible for determining the
+ appropriateness of using or redistributing the Work and assume any
+ risks associated with Your exercise of permissions under this License.
+
+ 8. Limitation of Liability. In no event and under no legal theory,
+ whether in tort (including negligence), contract, or otherwise,
+ unless required by applicable law (such as deliberate and grossly
+ negligent acts) or agreed to in writing, shall any Contributor be
+ liable to You for damages, including any direct, indirect, special,
+ incidental, or consequential damages of any character arising as a
+ result of this License or out of the use or inability to use the
+ Work (including but not limited to damages for loss of goodwill,
+ work stoppage, computer failure or malfunction, or any and all
+ other commercial damages or losses), even if such Contributor
+ has been advised of the possibility of such damages.
+
+ 9. Accepting Warranty or Additional Liability. While redistributing
+ the Work or Derivative Works thereof, You may choose to offer,
+ and charge a fee for, acceptance of support, warranty, indemnity,
+ or other liability obligations and/or rights consistent with this
+ License. However, in accepting such obligations, You may act only
+ on Your own behalf and on Your sole responsibility, not on behalf
+ of any other Contributor, and only if You agree to indemnify,
+ defend, and hold each Contributor harmless for any liability
+ incurred by, or claims asserted against, such Contributor by reason
+ of your accepting any such warranty or additional liability.
+
+ END OF TERMS AND CONDITIONS
+
+ APPENDIX: How to apply the Apache License to your work.
+
+ To apply the Apache License to your work, attach the following
+ boilerplate notice, with the fields enclosed by brackets "[]"
+ replaced with your own identifying information. (Don't include
+ the brackets!) The text should be enclosed in the appropriate
+ comment syntax for the file format. We also recommend that a
+ file or class name and description of purpose be included on the
+ same "printed page" as the copyright notice for easier
+ identification within third-party archives.
+
+ Copyright [yyyy] [name of copyright owner]
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
diff --git a/fonts/SOURCE-CODE-PRO-LICENSE.txt b/fonts/SOURCE-CODE-PRO-LICENSE.txt
new file mode 100644
index 000000000..366206f54
--- /dev/null
+++ b/fonts/SOURCE-CODE-PRO-LICENSE.txt
@@ -0,0 +1,93 @@
+Copyright 2010, 2012 Adobe Systems Incorporated (http://www.adobe.com/), with Reserved Font Name 'Source'. All Rights Reserved. Source is a trademark of Adobe Systems Incorporated in the United States and/or other countries.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.
diff --git a/fonts/fonts.css b/fonts/fonts.css
new file mode 100644
index 000000000..858efa598
--- /dev/null
+++ b/fonts/fonts.css
@@ -0,0 +1,100 @@
+/* Open Sans is licensed under the Apache License, Version 2.0. See http://www.apache.org/licenses/LICENSE-2.0 */
+/* Source Code Pro is under the Open Font License. See https://scripts.sil.org/cms/scripts/page.php?site_id=nrsi&id=OFL */
+
+/* open-sans-300 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: normal;
+ font-weight: 300;
+ src: local('Open Sans Light'), local('OpenSans-Light'),
+ url('open-sans-v17-all-charsets-300.woff2') format('woff2');
+}
+
+/* open-sans-300italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: italic;
+ font-weight: 300;
+ src: local('Open Sans Light Italic'), local('OpenSans-LightItalic'),
+ url('open-sans-v17-all-charsets-300italic.woff2') format('woff2');
+}
+
+/* open-sans-regular - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: normal;
+ font-weight: 400;
+ src: local('Open Sans Regular'), local('OpenSans-Regular'),
+ url('open-sans-v17-all-charsets-regular.woff2') format('woff2');
+}
+
+/* open-sans-italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: italic;
+ font-weight: 400;
+ src: local('Open Sans Italic'), local('OpenSans-Italic'),
+ url('open-sans-v17-all-charsets-italic.woff2') format('woff2');
+}
+
+/* open-sans-600 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: normal;
+ font-weight: 600;
+ src: local('Open Sans SemiBold'), local('OpenSans-SemiBold'),
+ url('open-sans-v17-all-charsets-600.woff2') format('woff2');
+}
+
+/* open-sans-600italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: italic;
+ font-weight: 600;
+ src: local('Open Sans SemiBold Italic'), local('OpenSans-SemiBoldItalic'),
+ url('open-sans-v17-all-charsets-600italic.woff2') format('woff2');
+}
+
+/* open-sans-700 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: normal;
+ font-weight: 700;
+ src: local('Open Sans Bold'), local('OpenSans-Bold'),
+ url('open-sans-v17-all-charsets-700.woff2') format('woff2');
+}
+
+/* open-sans-700italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: italic;
+ font-weight: 700;
+ src: local('Open Sans Bold Italic'), local('OpenSans-BoldItalic'),
+ url('open-sans-v17-all-charsets-700italic.woff2') format('woff2');
+}
+
+/* open-sans-800 - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: normal;
+ font-weight: 800;
+ src: local('Open Sans ExtraBold'), local('OpenSans-ExtraBold'),
+ url('open-sans-v17-all-charsets-800.woff2') format('woff2');
+}
+
+/* open-sans-800italic - latin_vietnamese_latin-ext_greek-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Open Sans';
+ font-style: italic;
+ font-weight: 800;
+ src: local('Open Sans ExtraBold Italic'), local('OpenSans-ExtraBoldItalic'),
+ url('open-sans-v17-all-charsets-800italic.woff2') format('woff2');
+}
+
+/* source-code-pro-500 - latin_vietnamese_latin-ext_greek_cyrillic-ext_cyrillic */
+@font-face {
+ font-family: 'Source Code Pro';
+ font-style: normal;
+ font-weight: 500;
+ src: url('source-code-pro-v11-all-charsets-500.woff2') format('woff2');
+}
diff --git a/fonts/open-sans-v17-all-charsets-300.woff2 b/fonts/open-sans-v17-all-charsets-300.woff2
new file mode 100644
index 000000000..9f51be370
Binary files /dev/null and b/fonts/open-sans-v17-all-charsets-300.woff2 differ
diff --git a/fonts/open-sans-v17-all-charsets-300italic.woff2 b/fonts/open-sans-v17-all-charsets-300italic.woff2
new file mode 100644
index 000000000..2f5454484
Binary files /dev/null and b/fonts/open-sans-v17-all-charsets-300italic.woff2 differ
diff --git a/fonts/open-sans-v17-all-charsets-600.woff2 b/fonts/open-sans-v17-all-charsets-600.woff2
new file mode 100644
index 000000000..f503d558d
Binary files /dev/null and b/fonts/open-sans-v17-all-charsets-600.woff2 differ
diff --git a/fonts/open-sans-v17-all-charsets-600italic.woff2 b/fonts/open-sans-v17-all-charsets-600italic.woff2
new file mode 100644
index 000000000..c99aabe80
Binary files /dev/null and b/fonts/open-sans-v17-all-charsets-600italic.woff2 differ
diff --git a/fonts/open-sans-v17-all-charsets-700.woff2 b/fonts/open-sans-v17-all-charsets-700.woff2
new file mode 100644
index 000000000..421a1ab25
Binary files /dev/null and b/fonts/open-sans-v17-all-charsets-700.woff2 differ
diff --git a/fonts/open-sans-v17-all-charsets-700italic.woff2 b/fonts/open-sans-v17-all-charsets-700italic.woff2
new file mode 100644
index 000000000..12ce3d20d
Binary files /dev/null and b/fonts/open-sans-v17-all-charsets-700italic.woff2 differ
diff --git a/fonts/open-sans-v17-all-charsets-800.woff2 b/fonts/open-sans-v17-all-charsets-800.woff2
new file mode 100644
index 000000000..c94a223b0
Binary files /dev/null and b/fonts/open-sans-v17-all-charsets-800.woff2 differ
diff --git a/fonts/open-sans-v17-all-charsets-800italic.woff2 b/fonts/open-sans-v17-all-charsets-800italic.woff2
new file mode 100644
index 000000000..eed7d3c63
Binary files /dev/null and b/fonts/open-sans-v17-all-charsets-800italic.woff2 differ
diff --git a/fonts/open-sans-v17-all-charsets-italic.woff2 b/fonts/open-sans-v17-all-charsets-italic.woff2
new file mode 100644
index 000000000..398b68a08
Binary files /dev/null and b/fonts/open-sans-v17-all-charsets-italic.woff2 differ
diff --git a/fonts/open-sans-v17-all-charsets-regular.woff2 b/fonts/open-sans-v17-all-charsets-regular.woff2
new file mode 100644
index 000000000..8383e94c6
Binary files /dev/null and b/fonts/open-sans-v17-all-charsets-regular.woff2 differ
diff --git a/fonts/source-code-pro-v11-all-charsets-500.woff2 b/fonts/source-code-pro-v11-all-charsets-500.woff2
new file mode 100644
index 000000000..722245682
Binary files /dev/null and b/fonts/source-code-pro-v11-all-charsets-500.woff2 differ
diff --git a/fuzzing.html b/fuzzing.html
new file mode 100644
index 000000000..4efdfeac3
--- /dev/null
+++ b/fuzzing.html
@@ -0,0 +1,310 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Feature Gates
+This chapter is intended to provide basic help for adding, removing, and +modifying feature gates.
+Note that this is specific to language feature gates; library feature gates use a different +mechanism.
+Adding a feature gate
+See "Stability in code" in the "Implementing new features" section for instructions.
+Removing a feature gate
+To remove a feature gate, follow these steps:
+-
+
-
+
Remove the feature gate declaration in
+rustc_feature/src/unstable.rs. +It will look like this:
+/// description of feature +(unstable, $feature_name, "$version", Some($tracking_issue_number)) +
+ -
+
Add a modified version of the feature gate declaration that you just +removed to
+rustc_feature/src/removed.rs:
+/// description of feature +(removed, $old_feature_name, "$version", Some($tracking_issue_number), + Some("$why_it_was_removed")) +
+
Renaming a feature gate
+To rename a feature gate, follow these steps (the first two are the same steps +to follow when removing a feature gate):
+-
+
-
+
Remove the old feature gate declaration in
+rustc_feature/src/unstable.rs. +It will look like this:
+/// description of feature +(unstable, $old_feature_name, "$version", Some($tracking_issue_number)) +
+ -
+
Add a modified version of the old feature gate declaration that you just +removed to
+rustc_feature/src/removed.rs:
+/// description of feature +/// Renamed to `$new_feature_name` +(removed, $old_feature_name, "$version", Some($tracking_issue_number), + Some("renamed to `$new_feature_name`")) +
+ -
+
Add a feature gate declaration with the new name to +
+rustc_feature/src/unstable.rs. It should look very similar to the old +declaration:
+/// description of feature +(unstable, $new_feature_name, "$version", Some($tracking_issue_number)) +
+
Stabilizing a feature
+See "Updating the feature-gate listing" in the "Stabilizing Features" chapter +for instructions. There are additional steps you will need to take beyond just +updating the declaration!
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/generic_parameters_summary.html b/generic_parameters_summary.html
new file mode 100644
index 000000000..2b1b166e7
--- /dev/null
+++ b/generic_parameters_summary.html
@@ -0,0 +1,243 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Fuzzing
+ +For the purposes of this guide, fuzzing is any testing methodology that +involves compiling a wide variety of programs in an attempt to uncover bugs in +rustc. Fuzzing is often used to find internal compiler errors (ICEs). Fuzzing +can be beneficial, because it can find bugs before users run into them and +provide small, self-contained programs that make the bug easier to track down. +However, some common mistakes can reduce the helpfulness of fuzzing and end up +making contributors' lives harder. To maximize your positive impact on the Rust +project, please read this guide before reporting fuzzer-generated bugs!
+Guidelines
+In a nutshell
+Please do:
+-
+
- Ensure the bug is still present on the latest nightly rustc +
- Include a reasonably minimal, standalone example along with any bug report +
- Include all of the information requested in the bug report template +
- Search for existing reports with the same message and query stack +
- Format the test case with
rustfmt, if it maintains the bug
+ - Indicate that the bug was found by fuzzing +
Please don't:
+-
+
- Don't report lots of bugs that use internal features, including but not
+limited to
custom_mir,lang_items,no_core, andrustc_attrs.
+ - Don't seed your fuzzer with inputs that are known to crash rustc (details +below). +
Discussion
+If you're not sure whether or not an ICE is a duplicate of one that's already +been reported, please go ahead and report it and link to issues you think might +be related. In general, ICEs on the same line but with different query stacks +are usually distinct bugs. For example, #109020 and #109129 +had similar error messages:
+error: internal compiler error: compiler/rustc_middle/src/ty/normalize_erasing_regions.rs:195:90: Failed to normalize <[closure@src/main.rs:36:25: 36:28] as std::ops::FnOnce<(Emplacable<()>,)>>::Output, maybe try to call `try_normalize_erasing_regions` instead
+error: internal compiler error: compiler/rustc_middle/src/ty/normalize_erasing_regions.rs:195:90: Failed to normalize <() as Project>::Assoc, maybe try to call `try_normalize_erasing_regions` instead
+but different query stacks:
+query stack during panic:
+#0 [fn_abi_of_instance] computing call ABI of `<[closure@src/main.rs:36:25: 36:28] as core::ops::function::FnOnce<(Emplacable<()>,)>>::call_once - shim(vtable)`
+end of query stack
+query stack during panic:
+#0 [check_mod_attrs] checking attributes in top-level module
+#1 [analysis] running analysis passes on this crate
+end of query stack
+Building a corpus
+When building a corpus, be sure to avoid collecting tests that are already +known to crash rustc. A fuzzer that is seeded with such tests is more likely to +generate bugs with the same root cause, wasting everyone's time. The simplest +way to avoid this is to loop over each file in the corpus, see if it causes an +ICE, and remove it if so.
+To build a corpus, you may want to use:
+-
+
- The rustc/rust-analyzer/clippy test suites (or even source code) --- though avoid
+tests that are already known to cause failures, which often begin with comments
+like
// failure-status: 101or// known-bug: #NNN.
+ - The already-fixed ICEs in Glacier --- though avoid the unfixed
+ones in
ices/!
+
Extra credit
+Here are a few things you can do to help the Rust project after filing an ICE.
+-
+
- Bisect the bug to figure out when it was introduced +
- Fix "distractions": problems with the test case that don't contribute to +triggering the ICE, such as syntax errors or borrow-checking errors +
- Minimize the test case (see below) +
- Add the minimal test case to Glacier +
Minimization
+It is helpful to carefully minimize the fuzzer-generated input. When +minimizing, be careful to preserve the original error, and avoid introducing +distracting problems such as syntax, type-checking, or borrow-checking errors.
+There are some tools that can help with minimization. If you're not sure how
+to avoid introducing syntax, type-, and borrow-checking errors while using
+these tools, post both the complete and minimized test cases. Generally,
+syntax-aware tools give the best results in the least amount of time.
+treereduce-rust and picireny are syntax-aware.
+halfempty is not, but is generally a high-quality tool.
Effective fuzzing
+When fuzzing rustc, you may want to avoid generating machine code, since this
+is mostly done by LLVM. Try --emit=mir instead.
A variety of compiler flags can uncover different issues. -Zmir-opt-level=4
+will turn on MIR optimization passes that are not run by default, potentially
+uncovering interesting bugs. -Zvalidate-mir can help uncover such bugs.
If you're fuzzing a compiler you built, you may want to build it with -C target-cpu=native or even PGO/BOLT to squeeze out a few more executions per
+second. Of course, it's best to try multiple build configurations and see
+what actually results in superior throughput.
You may want to build rustc from source with debug assertions to find
+additional bugs, though this is a trade-off: it can slow down fuzzing by
+requiring extra work for every execution. To enable debug assertions, add this
+to config.toml when compiling rustc:
[rust]
+debug-assertions = true
+ICEs that require debug assertions to reproduce should be tagged
+requires-debug-assertions.
Existing projects
+-
+
- fuzz-rustc demonstrates how to fuzz rustc with libfuzzer +
- icemaker runs rustc and other tools on a large number of source +files with a variety of flags to catch ICEs +
- tree-splicer generates new source files by combining existing +ones while maintaining correct syntax +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/getting-started.html b/getting-started.html
new file mode 100644
index 000000000..25d3d06c1
--- /dev/null
+++ b/getting-started.html
@@ -0,0 +1,339 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Generic parameter definitions
+This chapter will discuss how rustc tracks what generic parameters are introduced. For example given some struct Foo<T> how does rustc track that Foo defines some type parameter T (and no other generic parameters).
This will not cover how we track generic parameters introduced via for<'a> syntax (e.g. in where clauses or fn types), which is covered elsewhere in the chapter on Binders .
ty::Generics
+The generic parameters introduced by an item are tracked by the ty::Generics struct. Sometimes items allow usage of generics defined on parent items, this is accomplished via the ty::Generics struct having an optional field to specify a parent item to inherit generic parameters of. For example given the following code:
trait Trait<T> {
+ fn foo<U>(&self);
+}
+The ty::Generics used for foo would contain [U] and a parent of Some(Trait). Trait would have a ty::Generics containing [Self, T] with a parent of None.
The GenericParamDef struct is used to represent each individual generic parameter in a ty::Generics listing. The GenericParamDef struct contains information about the generic parameter, for example its name, defid, what kind of parameter it is (i.e. type, const, lifetime).
GenericParamDef also contains a u32 index representing what position the parameter is (starting from the outermost parent), this is the value used to represent usages of generic parameters (more on this in the chapter on representing types).
Interestingly, ty::Generics does not currently contain every generic parameter defined on an item. In the case of functions it only contains the early bound parameters.
Early vs Late bound parameters
++#![allow(unused)] +fn main() { +fn foo<'a, T>(b: &'a T) -> &'a T { b } +// ^^ ^early bound +// ^^ +// ^^late bound +} +
Generally when referring to an item with generic parameters you must specify a list of generic arguments corresponding to the item's generic parameters. In some cases it is permitted to elide these arguments but still, implicitly, a set of arguments are provided (e.g. Vec::default() desugars to Vec::<_>::default()).
For functions this is not necessarily the case, for example if we take the function foo from the example above and write the following code:
+fn main() { + let f = foo::<_>; + + let b = String::new(); + let c = String::new(); + + f(&b); + drop(b); + f(&c); +} +
This code compiles perfectly fine even though there is no single lifetime that could possibly be specified in foo::<_> that would allow for both
+the &b and &c borrows to be used as arguments (note: the drop(b) line forces the &b borrow to be shorter than the &c borrow). This works because the 'a lifetime is late bound.
A generic parameter being late bound means that when we write foo::<_> we do not actually provide an argument for that parameter, instead we wait until calling the function to provide the generic argument. In the above example this means that we are doing something like f::<'_>(&b); and f::<'_>(&c); (although in practice we do not actually support turbofishing late bound parameters in this manner)
It may be helpful to think of "early bound parameter" or "late bound parameter" as meaning "early provided parameter" and "late provided parameter", i.e. we provide the argument to the parameter either early (when naming the function) or late (when calling it).
+Late bound parameters on functions are tracked with a Binder when accessing the signature of the function, this can be done with the fn_sig query. For more information of binders see the chapter on Binders .
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/git.html b/git.html
new file mode 100644
index 000000000..4fedd2f9b
--- /dev/null
+++ b/git.html
@@ -0,0 +1,699 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Getting Started
+Thank you for your interest in contributing to Rust! There are many ways to +contribute, and we appreciate all of them.
+-
+
- Asking Questions + + +
- What should I work on? + + +
- Cloning and Building +
- Contributor Procedures +
- Other Resources +
If this is your first time contributing, the walkthrough chapter can give you a good example of +how a typical contribution would go.
+This documentation is not intended to be comprehensive; it is meant to be a +quick guide for the most useful things. For more information, see this +chapter on how to build and run the compiler.
+Asking Questions
+If you have questions, please make a post on the Rust Zulip server or
+internals.rust-lang.org. If you are contributing to Rustup, be aware they are not on
+Zulip - you can ask questions in #wg-rustup on Discord.
+See the list of teams and working groups and the Community page on the
+official website for more resources.
As a reminder, all contributors are expected to follow our Code of Conduct.
+The compiler team (or t-compiler) usually hangs out in Zulip in this
+"stream"; it will be easiest to get questions answered there.
Please ask questions! A lot of people report feeling that they are "wasting
+expert time", but nobody on t-compiler feels this way. Contributors are
+important to us.
Also, if you feel comfortable, prefer public topics, as this means others can +see the questions and answers, and perhaps even integrate them back into this +guide :)
+Experts
+Not all t-compiler members are experts on all parts of rustc; it's a
+pretty large project. To find out who could have some expertise on
+different parts of the compiler, consult triagebot assign groups.
+The sections that start with [assign* in triagebot.toml file.
+But also, feel free to ask questions even if you can't figure out who to ping.
Another way to find experts for a given part of the compiler is to see who has made recent commits.
+For example, to find people who have recently worked on name resolution since the 1.68.2 release,
+you could run git shortlog -n 1.68.2.. compiler/rustc_resolve/. Ignore any commits starting with
+"Rollup merge" or commits by @bors (see CI contribution procedures for
+more information about these commits).
Etiquette
+We do ask that you be mindful to include as much useful information as you can +in your question, but we recognize this can be hard if you are unfamiliar with +contributing to Rust.
+Just pinging someone without providing any context can be a bit annoying and
+just create noise, so we ask that you be mindful of the fact that the
+t-compiler folks get a lot of pings in a day.
What should I work on?
+The Rust project is quite large and it can be difficult to know which parts of the project need +help, or are a good starting place for beginners. Here are some suggested starting places.
+Easy or mentored issues
+If you're looking for somewhere to start, check out the following issue +search. See the Triage for an explanation of these labels. You can also try +filtering the search to areas you're interested in. For example:
+-
+
repo:rust-lang/rust-clippywill only show clippy issues
+label:T-compilerwill only show issues related to the compiler
+label:A-diagnosticswill only show diagnostic issues
+
Not all important or beginner work has issue labels. +See below for how to find work that isn't labelled.
+Recurring work
+Some work is too large to be done by a single person. In this case, it's common to have "Tracking +issues" to co-ordinate the work between contributors. Here are some example tracking issues where +it's easy to pick up work without a large time commitment:
+-
+
- Rustdoc Askama Migration +
- Diagnostic Translation +
- Move UI tests to subdirectories +
- Port run-make tests from Make to Rust +
If you find more recurring work, please feel free to add it here!
+Clippy issues
+The Clippy project has spent a long time making its contribution process as friendly to newcomers +as possible. Consider working on it first to get familiar with the process and the compiler +internals.
+See the Clippy contribution guide for instructions on getting started.
+Diagnostic issues
+Many diagnostic issues are self-contained and don't need detailed background knowledge of the +compiler. You can see a list of diagnostic issues here.
+Picking up abandoned pull requests
+Sometimes, contributors send a pull request, but later find out that they don't have enough
+time to work on it, or they simply are not interested in it anymore. Such PRs are often
+eventually closed and they receive the S-inactive label. You could try to examine some of
+these PRs and pick up the work. You can find the list of such PRs here.
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
+pull request, continuing the work on the feature.
Contributing to std (standard library)
+See std-dev-guide.
+Contributing code to other Rust projects
+There are a bunch of other projects that you can contribute to outside of the
+rust-lang/rust repo, including cargo, miri, rustup, and many others.
These repos might have their own contributing guidelines and procedures. Many +of them are owned by working groups. For more info, see the documentation in those repos' READMEs.
+Other ways to contribute
+There are a bunch of other ways you can contribute, especially if you don't
+feel comfortable jumping straight into the large rust-lang/rust codebase.
The following tasks are doable without much background knowledge but are +incredibly helpful:
+-
+
- Cleanup crew: find minimal reproductions of ICEs, bisect +regressions, etc. This is a way of helping that saves a ton of time for +others to fix an error later. +
- Writing documentation: if you are feeling a bit more intrepid, you could try +to read a part of the code and write doc comments for it. This will help you +to learn some part of the compiler while also producing a useful artifact! +
- Triaging issues: categorizing, replicating, and minimizing issues is very helpful to the Rust maintainers. +
- Working groups: there are a bunch of working groups on a wide variety +of rust-related things. +
- Answer questions in the Get Help! channels on the Rust Discord +server, on users.rust-lang.org, or on +StackOverflow. +
- Participate in the RFC process. +
- Find a requested community library, build it, and publish +it to Crates.io. Easier said than done, but very, very +valuable! +
Cloning and Building
+See "How to build and run the compiler".
+Contributor Procedures
+This section has moved to the "Contribution Procedures" chapter.
+Other Resources
+This section has moved to the "About this guide" chapter.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/guides/editions.html b/guides/editions.html
new file mode 100644
index 000000000..47db605e9
--- /dev/null
+++ b/guides/editions.html
@@ -0,0 +1,476 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ I see
+
+
+Overcoming
+Ignoring commits during
+
+
+
+
+ Using Git
+-
+
- Prerequisites +
- Standard Process +
- Troubleshooting git issues
+
-
+
- I made a merge commit by accident. +
- I deleted my fork on GitHub! +
- I changed a submodule by accident +
- I see "error: cannot rebase" when I try to rebase +
- I see 'Untracked Files: src/stdarch'? +
- I see
<<< HEAD?
+ - failed to push some refs +
- Git is trying to rebase commits I didn't write? +
- Quick note about submodules +
+ - Rebasing and Conflicts + + +
- Advanced Rebasing + + +
- No-Merge Policy +
- Tips for reviewing + + +
- Git submodules + + +
- Ignoring commits during
git blame
+
The Rust project uses Git to manage its source code. In order to +contribute, you'll need some familiarity with its features so that your changes +can be incorporated into the compiler.
+The goal of this page is to cover some of the more common questions and +problems new contributors face. Although some Git basics will be covered here, +if you find that this is still a little too fast for you, it might make sense +to first read some introductions to Git, such as the Beginner and Getting +started sections of this tutorial from Atlassian. GitHub also +provides documentation and guides for beginners, or you can consult the +more in depth book from Git.
+This guide is incomplete. If you run into trouble with git that this page doesn't help with, +please open an issue so we can document how to fix it.
+Prerequisites
+We'll assume that you've installed Git, forked rust-lang/rust, and cloned the +forked repo to your PC. We'll use the command line interface to interact +with Git; there are also a number of GUIs and IDE integrations that can +generally do the same things.
+If you've cloned your fork, then you will be able to reference it with origin
+in your local repo. It may be helpful to also set up a remote for the official
+rust-lang/rust repo via
git remote add upstream https://github.com/rust-lang/rust.git
+if you're using HTTPS, or
+git remote add upstream git@github.com:rust-lang/rust.git
+if you're using SSH.
+NOTE: This page is dedicated to workflows for rust-lang/rust, but will likely be
+useful when contributing to other repositories in the Rust project.
Standard Process
+Below is the normal procedure that you're likely to use for most minor changes +and PRs:
+-
+
- Ensure that you're making your changes on top of master:
+
git checkout master.
+ - Get the latest changes from the Rust repo:
git pull upstream master --ff-only. +(see No-Merge Policy for more info about this).
+ - Make a new branch for your change:
git checkout -b issue-12345-fix.
+ - Make some changes to the repo and test them. +
- Stage your changes via
git add src/changed/file.rs src/another/change.rs+and then commit them withgit commit. Of course, making intermediate commits +may be a good idea as well. Avoidgit add ., as it makes it too easy to +unintentionally commit changes that should not be committed, such as submodule +updates. You can usegit statusto check if there are any files you forgot +to stage.
+ - Push your changes to your fork:
git push --set-upstream origin issue-12345-fix+(After adding commits, you can usegit pushand after rebasing or +pulling-and-rebasing, you can usegit push --force-with-lease).
+ - Open a PR from your fork to
rust-lang/rust's master branch.
+
If you end up needing to rebase and are hitting conflicts, see Rebasing. +If you want to track upstream while working on long-running feature/issue, see +Keeping things up to date.
+If your reviewer requests changes, the procedure for those changes looks much +the same, with some steps skipped:
+-
+
- Ensure that you're making changes to the most recent version of your code:
+
git checkout issue-12345-fix.
+ - Make, stage, and commit your additional changes just like before. +
- Push those changes to your fork:
git push.
+
Troubleshooting git issues
+You don't need to clone rust-lang/rust from scratch if it's out of date!
+Even if you think you've messed it up beyond repair, there are ways to fix
+the git state that don't require downloading the whole repository again.
+Here are some common issues you might run into:
I made a merge commit by accident.
+Git has two ways to update your branch with the newest changes: merging and rebasing.
+Rust uses rebasing. If you make a merge commit, it's not too hard to fix:
+git rebase -i upstream/master.
See Rebasing for more about rebasing.
+I deleted my fork on GitHub!
+This is not a problem from git's perspective. If you run git remote -v,
+it will say something like this:
$ git remote -v
+origin git@github.com:jyn514/rust.git (fetch)
+origin git@github.com:jyn514/rust.git (push)
+upstream https://github.com/rust-lang/rust (fetch)
+upstream https://github.com/rust-lang/rust (fetch)
+If you renamed your fork, you can change the URL like this:
+git remote set-url origin <URL>
+where the <URL> is your new fork.
I changed a submodule by accident
+Usually people notice this when rustbot posts a comment on github that cargo has been modified:
You might also notice conflicts in the web UI:
+
The most common cause is that you rebased after a change and ran git add . without first running
+x to update the submodules. Alternatively, you might have run cargo fmt instead of x fmt
+and modified files in a submodule, then committed the changes.
To fix it, do the following things:
+-
+
- See which commit has the accidental changes:
git log --stat -n1 src/tools/cargo
+ - Revert the changes to that commit:
git checkout <my-commit>~ src/tools/cargo. Type~+literally but replace<my-commit>with the output from step 1.
+ - Tell git to commit the changes:
git commit --fixup <my-commit>
+ - Repeat steps 1-3 for all the submodules you modified.
+
-
+
- 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 logcommand shows a commit +that's not authored by you.
+
+ - 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
- Squash your changes into the existing commits:
git rebase --autosquash -i upstream/master
+ - Push your changes. +
I see "error: cannot rebase" when I try to rebase
+These are two common errors to see when rebasing:
+error: cannot rebase: Your index contains uncommitted changes.
+error: Please commit or stash them.
+error: cannot rebase: You have unstaged changes.
+error: Please commit or stash them.
+(See https://git-scm.com/book/en/v2/Getting-Started-What-is-Git%3F#_the_three_states for the difference between the two.)
+This means you have made changes since the last time you made a commit. To be able to rebase, either +commit your changes, or make a temporary commit called a "stash" to have them still not be committed +when you finish rebasing. You may want to configure git to make this "stash" automatically, which +will prevent the "cannot rebase" error in nearly all cases:
+git config --global rebase.autostash true
+See https://git-scm.com/book/en/v2/Git-Tools-Stashing-and-Cleaning for more info about stashing.
+I see 'Untracked Files: src/stdarch'?
+This is left over from the move to the library/ directory.
+Unfortunately, git rebase does not follow renames for submodules, so you
+have to delete the directory yourself:
rm -r src/stdarch
+I see <<< HEAD?
+You were probably in the middle of a rebase or merge conflict. See
+Conflicts for how to fix the conflict. If you don't care about the changes
+and just want to get a clean copy of the repository back, you can use git reset:
# WARNING: this throws out any local changes you've made! Consider resolving the conflicts instead.
+git reset --hard master
+failed to push some refs
+git push will not work properly and say something like this:
! [rejected] issue-xxxxx -> issue-xxxxx (non-fast-forward)
+error: failed to push some refs to 'https://github.com/username/rust.git'
+hint: Updates were rejected because the tip of your current branch is behind
+hint: its remote counterpart. Integrate the remote changes (e.g.
+hint: 'git pull ...') before pushing again.
+hint: See the 'Note about fast-forwards' in 'git push --help' for details.
+The advice this gives is incorrect! Because of Rust's
+"no-merge" policy the merge commit created by git pull
+will not be allowed in the final PR, in addition to defeating the point of the
+rebase! Use git push --force-with-lease instead.
Git is trying to rebase commits I didn't write?
+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:
git rebase --abort
+git rebase -i upstream/master
+Click here to see an example of rebasing over the wrong branch
+
Quick note about submodules
+When updating your local repository with git pull, you may notice that sometimes
+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):
On branch master
+Your branch is up to date with 'origin/master'.
+
+Changes not staged for commit:
+ (use "git add <file>..." to update what will be committed)
+ (use "git restore <file>..." to discard changes in working directory)
+ modified: src/llvm-project (new commits)
+ modified: src/tools/cargo (new commits)
+
+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). To get rid of those, run ./x --help, which will automatically update
+the submodules.
Some submodules are not actually needed; for example, src/llvm-project doesn't need to be checked
+out if you're using download-ci-llvm. To avoid having to keep fetching its history, you can use
+git submodule deinit -f src/llvm-project, which will also avoid it showing as modified again.
Rebasing and Conflicts
+When you edit your code locally, you are making changes to the version of +rust-lang/rust that existed when you created your feature branch. As such, when +you submit your PR it is possible that some of the changes that have been made +to rust-lang/rust since then are in conflict with the changes you've made. +When this happens, you need to resolve the conflicts before your changes can be +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 +of rust-lang/rust, checkout your branch, and then run this command:
+git pull --rebase https://github.com/rust-lang/rust.git master
+++If you are met with the following error:
++error: cannot pull with rebase: Your index contains uncommitted changes. +error: please commit or stash them. +it means that you have some uncommitted work in your working tree. In that +case, run
+git stashbefore rebasing, and thengit stash popafter 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 +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 +lines in the output that look like
+CONFLICT (content): Merge conflict in file.rs
+When you open these files, you'll see sections of the form
+<<<<<<< HEAD
+Original code
+=======
+Your code
+>>>>>>> 8fbf656... Commit fixes 12345
+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
+decide how to deal with the conflict. You may want to keep your changes,
+keep the changes on master, 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
+<<<<<<<, ======= and >>>>>>> lines in the process. Second, check the
+surrounding code. If there was a conflict, its likely there are some logical
+errors lying around too! It's a good idea to run x check here to make sure
+there are no glaring errors.
Once you're all done fixing the conflicts, you need to stage the files that had
+conflicts in them via git add. Afterwards, run git rebase --continue to let
+Git know that you've resolved the conflicts and it should finish the rebase.
Once the rebase has succeeded, you'll want to update the associated branch on
+your fork with git push --force-with-lease.
Keeping things up to date
+The above section on Rebasing is a specific +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
+will keep it up-to-date. You will also want to rebase your feature branches
+up-to-date as well. After pulling, you can checkout the feature branches
+and rebase them:
git checkout master
+git pull upstream master --ff-only # to make certain there are no merge commits
+git rebase master feature_branch
+git push --force-with-lease # (set origin to be the same as local)
+To avoid merges as per the No-Merge Policy, you may want to use
+git config pull.ff only (this will apply the config only to the local repo)
+to ensure that Git doesn't create merge commits when git pulling, without
+needing to pass --ff-only or --rebase every time.
You can also git push --force-with-lease from master to keep your fork's master in sync with
+upstream.
Advanced Rebasing
+Squash your commits
+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
+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.
Alternatively, you can sacrifice the commit history like this:
+# squash all the changes into one commit so you only have to worry about conflicts once
+git rebase -i $(git merge-base master HEAD) # and squash all changes along the way
+git rebase master
+# fix all merge conflicts
+git rebase --continue
+"Squashing" commits into each other causes them to be merged into a single +commit. Both the upside and downside of this is that it simplifies the history. +On the one hand, you lose track of the steps in which changes were made, but +the history becomes easier to work with.
+You also may want to squash just the last few commits together, possibly
+because they only represent "fixups" and not real changes. For example,
+git rebase --interactive HEAD~2 will allow you to edit the two commits only.
git range-diff
+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.
The first argument to range-diff, master 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
+request. Finally, the third argument to range-diff is the new version of
+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.
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
+old branch and the new branch, and the marker on the right indicates a change
+you've committed. So, you can think of a range-diff as a "diff of diffs" since
+it shows you the differences between your old diff and your new diff.
Here's an example of git range-diff output (taken from Git's
+docs):
-: ------- > 1: 0ddba11 Prepare for the inevitable!
+1: c0debee = 2: cab005e Add a helpful message at the start
+2: f00dbal ! 3: decafe1 Describe a bug
+ @@ -1,3 +1,3 @@
+ Author: A U Thor <author@example.com>
+
+ -TODO: Describe a bug
+ +Describe a bug
+ @@ -324,5 +324,6
+ This is expected.
+
+ -+What is unexpected is that it will also crash.
+ ++Unexpectedly, it also crashes. This is a bug, and the jury is
+ ++still out there how to fix it best. See ticket #314 for details.
+
+ Contact
+3: bedead < -: ------- TO-UNDO
+(Note that git range-diff output in your terminal will probably be easier to
+read than in this example because it will have colors.)
Another feature of git range-diff is that, unlike git diff, it will also
+diff commit messages. This feature can be useful when amending several commit
+messages so you can make sure you changed the right parts.
git range-diff is a very useful command, but note that it can take some time
+to get used to its output format. You may also find Git's documentation on the
+command useful, especially their "Examples" section.
No-Merge Policy
+The rust-lang/rust repo uses what is known as a "rebase workflow." This means
+that merge commits in PRs are not accepted. As a result, if you are running
+git merge locally, chances are good that you should be rebasing instead. Of
+course, this is not always true; if your merge will just be a fast-forward,
+like the merges that git pull usually performs, then no merge commit is
+created and you have nothing to worry about. Running git config merge.ff only
+(this will apply the config to the local repo)
+once will ensure that all the merges you perform are of this type, so that you
+cannot make a mistake.
There are a number of reasons for this decision and like all others, it is a +tradeoff. The main advantage is the generally linear commit history. This +greatly simplifies bisecting and makes the history and commit log much easier +to follow and understand.
+Tips for reviewing
+NOTE: This section is for reviewing PRs, not authoring them.
+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.
Fetching PRs
+To checkout PRs locally, you can use git fetch upstream pull/NNNNN/head && git checkout FETCH_HEAD.
You can also use github's cli tool. Github shows a button on PRs where you can copy-paste the +command to check it out locally. See https://cli.github.com/ for more info.
+
Moving large sections of code
+Git and Github's default diff view for large moves within a file is quite poor; it will show each +line as deleted and each line as added, forcing you to compare each line yourself. Git has an option +to show moved lines in a different color:
+git log -p --color-moved=dimmed-zebra --color-moved-ws=allow-indentation-change
+See the docs for --color-moved for more info.
range-diff
+See the relevant section for PR authors. This can be useful for comparing code +that was force-pushed to make sure there are no unexpected changes.
+Ignoring changes to specific files
+Many large files in the repo are autogenerated. To view a diff that ignores changes to those files, +you can use the following syntax (e.g. Cargo.lock):
+git log -p ':!Cargo.lock'
+Arbitrary patterns are supported (e.g. :!compiler/*). Patterns use the same syntax as
+.gitignore, with : prepended to indicate a pattern.
Git submodules
+NOTE: submodules are a nice thing to know about, but it isn't an absolute
+prerequisite to contribute to rustc. If you are using Git for the first time,
+you might want to get used to the main concepts of Git before reading this section.
The rust-lang/rust repository uses Git submodules as a way to use other
+Rust projects from within the rust repo. Examples include Rust's fork of
+llvm-project, cargo and libraries like stdarch and backtrace.
Those projects are developed and maintained in an separate Git (and GitHub)
+repository, and they have their own Git history/commits, issue tracker and PRs.
+Submodules allow us to create some sort of embedded sub-repository inside the
+rust repository and use them like they were directories in the rust repository.
Take llvm-project for example. llvm-project is maintained in the rust-lang/llvm-project
+repository, but it is used in rust-lang/rust by the compiler for code generation and
+optimization. We bring it in rust as a submodule, in the src/llvm-project folder.
The contents of submodules are ignored by Git: submodules are in some sense isolated
+from the rest of the repository. However, if you try to cd src/llvm-project and then
+run git status:
HEAD detached at 9567f08afc943
+nothing to commit, working tree clean
+As far as git is concerned, you are no longer in the rust repo, but in the llvm-project repo.
+You will notice that we are in "detached HEAD" state, i.e. not on a branch but on a
+particular commit.
This is because, like any dependency, we want to be able to control which version to use.
+Submodules allow us to do just that: every submodule is "pinned" to a certain
+commit, which doesn't change unless modified manually. If you use git checkout <commit>
+in the llvm-project directory and go back to the rust directory, you can stage this
+change like any other, e.g. by running git add src/llvm-project. (Note that if
+you don't stage the change to commit, then you run the risk that running
+x will just undo your change by switching back to the previous commit when
+it automatically "updates" the submodules.)
This version selection is usually done by the maintainers of the project, and +looks like this.
+Git submodules take some time to get used to, so don't worry if it isn't perfectly +clear yet. You will rarely have to use them directly and, again, you don't need +to know everything about submodules to contribute to Rust. Just know that they +exist and that they correspond to some sort of embedded subrepository dependency +that Git can nicely and fairly conveniently handle for us.
+Hard-resetting submodules
+Sometimes you might run into (when you run git status)
Changes not staged for commit:
+ (use "git add <file>..." to update what will be committed)
+ (use "git restore <file>..." to discard changes in working directory)
+ (commit or discard the untracked or modified content in submodules)
+ modified: src/llvm-project (new commits, modified content)
+and when you try to run git submodule update it breaks horribly with errors like
error: RPC failed; curl 92 HTTP/2 stream 7 was not closed cleanly: CANCEL (err 8)
+error: 2782 bytes of body are still expected
+fetch-pack: unexpected disconnect while reading sideband packet
+fatal: early EOF
+fatal: fetch-pack: invalid index-pack output
+fatal: Fetched in submodule path 'src/llvm-project', but it did not contain 5a5152f653959d14d68613a3a8a033fb65eec021. Direct fetching of that commit failed.
+If you see (new commits, modified content) you can run
$ git submodule foreach git reset --hard
+and then try git submodule update again.
Deinit git submodules
+If that doesn't work, you can try to deinit all git submodules...
+git submodule deinit -f --all
+Unfortunately sometimes your local git submodules configuration can become +completely messed up for some reason.
+Overcoming fatal: not a git repository: <submodule>/../../.git/modules/<submodule>
+Sometimes, for some forsaken reason, you might run into
+fatal: not a git repository: src/gcc/../../.git/modules/src/gcc
+In this situation, for the given submodule path, i.e. <submodule_path> = src/gcc in this example, you need to:
-
+
rm -rf <submodule_path>/.git
+rm -rf .git/modules/<submodule_path>/config
+rm -rf .gitconfig.lockif somehow the.gitconfiglock is orphaned.
+
Then do something like ./x fmt to have bootstrap manage the submodule
+checkouts for you.
Ignoring commits during git blame
+Some commits contain large reformatting changes that don't otherwise change functionality. They can
+be instructed to be ignored by git blame through
+.git-blame-ignore-revs:
-
+
- Configure
git blameto use.git-blame-ignore-revsas the list of commits to ignore:git config blame.ignorerevsfile .git-blame-ignore-revs
+ - Add suitable commits that you wish to be ignored by
git blame.
+
Please include a comment for the commit that you add to .git-blame-ignore-revs so people can
+easily figure out why a commit is ignored.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/highlight.css b/highlight.css
new file mode 100644
index 000000000..ba57b82b2
--- /dev/null
+++ b/highlight.css
@@ -0,0 +1,82 @@
+/*
+ * An increased contrast highlighting scheme loosely based on the
+ * "Base16 Atelier Dune Light" theme by Bram de Haan
+ * (http://atelierbram.github.io/syntax-highlighting/atelier-schemes/dune)
+ * Original Base16 color scheme by Chris Kempson
+ * (https://github.com/chriskempson/base16)
+ */
+
+/* Comment */
+.hljs-comment,
+.hljs-quote {
+ color: #575757;
+}
+
+/* Red */
+.hljs-variable,
+.hljs-template-variable,
+.hljs-attribute,
+.hljs-tag,
+.hljs-name,
+.hljs-regexp,
+.hljs-link,
+.hljs-name,
+.hljs-selector-id,
+.hljs-selector-class {
+ color: #d70025;
+}
+
+/* Orange */
+.hljs-number,
+.hljs-meta,
+.hljs-built_in,
+.hljs-builtin-name,
+.hljs-literal,
+.hljs-type,
+.hljs-params {
+ color: #b21e00;
+}
+
+/* Green */
+.hljs-string,
+.hljs-symbol,
+.hljs-bullet {
+ color: #008200;
+}
+
+/* Blue */
+.hljs-title,
+.hljs-section {
+ color: #0030f2;
+}
+
+/* Purple */
+.hljs-keyword,
+.hljs-selector-tag {
+ color: #9d00ec;
+}
+
+.hljs {
+ display: block;
+ overflow-x: auto;
+ background: #f6f7f6;
+ color: #000;
+}
+
+.hljs-emphasis {
+ font-style: italic;
+}
+
+.hljs-strong {
+ font-weight: bold;
+}
+
+.hljs-addition {
+ color: #22863a;
+ background-color: #f0fff4;
+}
+
+.hljs-deletion {
+ color: #b31d28;
+ background-color: #ffeef0;
+}
diff --git a/highlight.js b/highlight.js
new file mode 100644
index 000000000..180385b70
--- /dev/null
+++ b/highlight.js
@@ -0,0 +1,6 @@
+/*
+ Highlight.js 10.1.1 (93fd0d73)
+ License: BSD-3-Clause
+ Copyright (c) 2006-2020, Ivan Sagalaev
+*/
+var hljs=function(){"use strict";function e(n){Object.freeze(n);var t="function"==typeof n;return Object.getOwnPropertyNames(n).forEach((function(r){!Object.hasOwnProperty.call(n,r)||null===n[r]||"object"!=typeof n[r]&&"function"!=typeof n[r]||t&&("caller"===r||"callee"===r||"arguments"===r)||Object.isFrozen(n[r])||e(n[r])})),n}class n{constructor(e){void 0===e.data&&(e.data={}),this.data=e.data}ignoreMatch(){this.ignore=!0}}function t(e){return e.replace(/&/g,"&").replace(//g,">").replace(/"/g,""").replace(/'/g,"'")}function r(e,...n){var t={};for(const n in e)t[n]=e[n];return n.forEach((function(e){for(const n in e)t[n]=e[n]})),t}function a(e){return e.nodeName.toLowerCase()}var i=Object.freeze({__proto__:null,escapeHTML:t,inherit:r,nodeStream:function(e){var n=[];return function e(t,r){for(var i=t.firstChild;i;i=i.nextSibling)3===i.nodeType?r+=i.nodeValue.length:1===i.nodeType&&(n.push({event:"start",offset:r,node:i}),r=e(i,r),a(i).match(/br|hr|img|input/)||n.push({event:"stop",offset:r,node:i}));return r}(e,0),n},mergeStreams:function(e,n,r){var i=0,s="",o=[];function l(){return e.length&&n.length?e[0].offset!==n[0].offset?e[0].offset
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Editions
+-
+
- Edition definition + + +
- Edition parsing + + +
- Lints + + +
- Standard library changes + + +
This chapter gives an overview of how Edition support works in rustc. +This assumes that you are familiar with what Editions are (see the Edition Guide).
+Edition definition
+The --edition CLI flag specifies the edition to use for a crate.
+This can be accessed from Session::edition.
+There are convenience functions like Session::at_least_rust_2021 for checking the crate's
+edition, though you should be careful about whether you check the global session or the span, see
+Edition hygiene below.
As an alternative to the at_least_rust_20xx convenience methods, the Edition type also
+supports comparisons for doing range checks, such as span.edition() >= Edition::Edition2021.
Adding a new edition
+Adding a new edition mainly involves adding a variant to the Edition enum and then fixing
+everything that is broken. See #94461 for an
+example.
Features and Edition stability
+The Edition enum defines whether or not an edition is stable.
+If it is not stable, then the -Zunstable-options CLI option must be passed to enable it.
When adding a new feature, there are two options you can choose for how to handle stability with a +future edition:
+-
+
- Just check the edition of the span like
span.at_least_rust_20xx()(see Edition hygiene) or the +Session::edition. This will implicitly depend on the stability of the edition itself to +indicate that your feature is available.
+ - Place your new behavior behind a feature gate. +
It may be sufficient to only check the current edition for relatively simple changes. +However, for larger language changes, you should consider creating a feature gate. +There are several benefits to using a feature gate:
+-
+
- A feature gate makes it easier to work on and experiment with a new feature. +
- It makes the intent clear when the
#![feature(…)]attribute is used that your new feature is +being enabled.
+ - It makes testing of editions easier so that features that are not yet complete do not interfere +with testing of edition-specific features that are complete and ready. +
- It decouples the feature from an edition, which makes it easier for the team to make a deliberate +decision of whether or not a feature should be added to the next edition when the feature is +ready. +
When a feature is complete and ready, the feature gate can be removed (and the code should just
+check the span or Session edition to determine if it is enabled).
There are a few different options for doing feature checks:
+-
+
-
+
For highly experimental features, that may or may not be involved in an edition, they can +implement regular feature gates like
+tcx.features().my_feature, and ignore editions for the time +being.
+ -
+
For experimental features that might be involved in an edition, they should implement gates with +
+tcx.features().my_feature && span.at_least_rust_20xx(). +This requires the user to still specify#![feature(my_feature)], to avoid disrupting testing of +other edition features which are ready and have been accepted within the edition.
+ -
+
For experimental features that have graduated to definitely be part of an edition, +they should implement gates with
+tcx.features().my_feature || span.at_least_rust_20xx(), +or just remove the feature check altogether and just checkspan.at_least_rust_20xx().
+
If you need to do the feature gating in multiple places, consider placing the check in a single +function so that there will only be a single place to update. For example:
+// An example from Edition 2021 disjoint closure captures.
+
+fn enable_precise_capture(tcx: TyCtxt<'_>, span: Span) -> bool {
+ tcx.features().capture_disjoint_fields || span.rust_2021()
+}
+See Lints and stability below for more information about how lints handle +stability.
+Edition parsing
+For the most part, the lexer is edition-agnostic.
+Within StringReader, tokens can be modified based on edition-specific behavior.
+For example, C-String literals like c"foo" are split into multiple tokens in editions before 2021.
+This is also where things like reserved prefixes are handled for the 2021 edition.
Edition-specific parsing is relatively rare. One example is async fn which checks the span of the
+token to determine if it is the 2015 edition, and emits an error in that case.
+This can only be done if the syntax was already invalid.
If you need to do edition checking in the parser, you will normally want to look at the edition of
+the token, see Edition hygiene.
+In some rare cases you may instead need to check the global edition from ParseSess::edition.
Most edition-specific parsing behavior is handled with migration lints instead of in the parser.
+This is appropriate when there is a change in syntax (as opposed to new syntax).
+This allows the old syntax to continue to work on previous editions.
+The lint then checks for the change in behavior.
+On older editions, the lint pass should emit the migration lint to help with migrating to new
+editions.
+On newer editions, your code should emit a hard error with emit_err instead.
+For example, the deprecated start...end pattern syntax emits the
+ellipsis_inclusive_range_patterns lint on editions before 2021, and in 2021 is an hard error via
+the emit_err method.
Keywords
+New keywords can be introduced across an edition boundary.
+This is implemented by functions like Symbol::is_used_keyword_conditional, which rely on the
+ordering of how the keywords are defined.
When new keywords are introduced, the keyword_idents lint should be updated so that automatic
+migrations can transition code that might be using the keyword as an identifier (see
+KeywordIdents).
+An alternative to consider is to implement the keyword as a weak keyword if the position it is used
+is sufficient to distinguish it.
An additional option to consider is the k# prefix which was introduced in RFC 3101.
+This allows the use of a keyword in editions before the edition where the keyword is introduced.
+This is currently not implemented.
Edition hygiene
+Spans are marked with the edition of the crate that the span came from. +See Macro hygiene in the Edition Guide for a user-centric description of what this means.
+You should normally use the edition from the token span instead of looking at the global Session
+edition.
+For example, use span.edition().at_least_rust_2021() instead of sess.at_least_rust_2021().
+This helps ensure that macros behave correctly when used across crates.
Lints
+Lints support a few different options for interacting with editions. +Lints can be future incompatible edition migration lints, which are used to support +migrations to newer editions. +Alternatively, lints can be edition-specific, where they change their +default level starting in a specific edition.
+Migration lints
+Migration lints are used to migrate projects from one edition to the next.
+They are implemented with a MachineApplicable suggestion which
+will rewrite code so that it will successfully compile in both the previous and the next
+edition.
+For example, the keyword_idents lint will take identifiers that conflict with a new keyword to
+use the raw identifier syntax to avoid the conflict (for example changing async to r#async).
Migration lints must be declared with the FutureIncompatibilityReason::EditionError or
+FutureIncompatibilityReason::EditionSemanticsChange future-incompatible
+option in the lint declaration:
declare_lint! {
+ pub KEYWORD_IDENTS,
+ Allow,
+ "detects edition keywords being used as an identifier",
+ @future_incompatible = FutureIncompatibleInfo {
+ reason: FutureIncompatibilityReason::EditionError(Edition::Edition2018),
+ reference: "issue #49716 <https://github.com/rust-lang/rust/issues/49716>",
+ };
+}
+When declared like this, the lint is automatically added to the appropriate
+rust-20xx-compatibility lint group.
+When a user runs cargo fix --edition, cargo will pass the --force-warn rust-20xx-compatibility
+flag to force all of these lints to appear during the edition migration.
+Cargo also passes --cap-lints=allow so that no other lints interfere with the edition migration.
Migration lints can be either Allow or Warn by default.
+If it is Allow, users usually won't see this warning unless they are doing an edition migration
+manually or there is a problem during the migration.
+Most migration lints are Allow.
If it is Warn by default, users on all editions will see this warning.
+Only use Warn if you think it is important for everyone to be aware of the change, and to
+encourage people to update their code on all editions.
+Beware that new warn-by-default lint that hit many projects can be very disruptive and frustrating
+for users.
+You may consider switching an Allow to Warn several years after the edition stabilizes.
+This will only show up for the relatively small number of stragglers who have not updated to the new
+edition.
Edition-specific lints
+Lints can be marked so that they have a different level starting in a specific edition.
+In the lint declaration, use the @edition marker:
declare_lint! {
+ pub SOME_LINT_NAME,
+ Allow,
+ "my lint description",
+ @edition Edition2024 => Warn;
+}
+Here, SOME_LINT_NAME defaults to Allow on all editions before 2024, and then becomes Warn
+afterwards.
This should generally be used sparingly, as there are other options:
+-
+
-
+
Small impact stylistic changes unrelated to an edition can just make the lint
+Warnon all +editions. If you want people to adopt a different way to write things, then go ahead and commit to +having it show up for all projects.Beware that if a new warn-by-default lint hits many projects, it can be very disruptive and +frustrating for users.
+
+ -
+
Change the new style to be a hard error in the new edition, and use a migration lint to +automatically convert projects to the new style. For example, +
+ellipsis_inclusive_range_patternsis a hard error in 2021, and warns in all previous editions.Beware that these cannot be added after the edition stabilizes.
+
+ -
+
Migration lints can also change over time. +For example, the migration lint can start out as
+Allowby default. +For people performing the migration, they will automatically get updated to the new code. +Then, after some years, the lint can be made toWarnin previous editions.For example
+anonymous_parameterswas a 2018 Edition migration lint (and a hard-error in 2018) +that wasAllowby default in previous editions. +Then, three years later, it was changed toWarnfor all previous editions, so that all users got +a warning that the style was being phased out. +If this was a warning from the start, it would have impacted many projects and be very disruptive. +By making it part of the edition, most users eventually updated to the new edition and were +handled by the migration. +Switching toWarnonly impacted a few stragglers who did not update.
+
Lints and stability
+Lints can be marked as being unstable, which can be helpful when developing a new edition feature, +and you want to test out a migration lint. +The feature gate can be specified in the lint's declaration like this:
+declare_lint! {
+ pub SOME_LINT_NAME,
+ Allow,
+ "my cool lint",
+ @feature_gate = sym::my_feature_name;
+}
+Then, the lint will only fire if the user has the appropriate #![feature(my_feature_name)].
+Just beware that when it comes time to do crater runs testing the migration that the feature gate
+will need to be removed.
Alternatively, you can implement an allow-by-default migration lint for an upcoming unstable +edition without a feature gate. +Although users may technically be able to enable the lint before the edition is stabilized, most +will not notice the new lint exists, and it should not disrupt anything or cause any breakage.
+Idiom lints
+In the 2018 edition, there was a concept of "idiom lints" under the rust-2018-idioms lint group.
+The concept was to have new idiomatic styles under a different lint group separate from the forced
+migrations under the rust-2018-compatibility lint group, giving some flexibility as to how people
+opt-in to certain edition changes.
Overall this approach did not seem to work very well, +and it is unlikely that we will use the idiom groups in the future.
+Standard library changes
+Preludes
+Each edition comes with a specific prelude of the standard library.
+These are implemented as regular modules in core::prelude and std::prelude.
+New items can be added to the prelude, just beware that this can conflict with user's pre-existing
+code.
+Usually a migration lint should be used to migrate existing code to avoid the conflict.
+For example, rust_2021_prelude_collisions is used to handle the collisions with the new traits
+in 2021.
Customized language behavior
+Usually it is not possible to make breaking changes to the standard library. +In some rare cases, the teams may decide that the behavior change is important enough to break this +rule. +The downside is that this requires special handling in the compiler to be able to distinguish when +the old and new signatures or behaviors should be used.
+One example is the change in method resolution for into_iter() of arrays.
+This was implemented with the #[rustc_skip_array_during_method_dispatch] attribute on the
+IntoIterator trait which then tells the compiler to consider an alternate trait resolution choice
+based on the edition.
Another example is the panic! macro changes.
+This required defining multiple panic macros, and having the built-in panic macro implementation
+determine the appropriate way to expand it.
+This also included the non_fmt_panics migration lint to adjust old code to the new form, which
+required the rustc_diagnostic_item attribute to detect the usage of the panic macro.
In general it is recommended to avoid these special cases except for very high value situations.
+ +":e:f.tabReplace?e.replace(/\t/g,f.tabReplace):e):e}function E(e){let n=null;const t=function(e){var n=e.className+" ";n+=e.parentNode?e.parentNode.className:"";const t=f.languageDetectRe.exec(n);if(t){var r=T(t[1]);return r||(console.warn(g.replace("{}",t[1])),console.warn("Falling back to no-highlight mode for this block.",e)),r?t[1]:"no-highlight"}return n.split(/\s+/).find(e=>p(e)||T(e))}(e);if(p(t))return;S("before:highlightBlock",{block:e,language:t}),f.useBR?(n=document.createElement("div")).innerHTML=e.innerHTML.replace(/\n/g,"").replace(/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/hir.html b/hir.html
new file mode 100644
index 000000000..911f7cace
--- /dev/null
+++ b/hir.html
@@ -0,0 +1,319 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ HIR Debugging
+Use the -Z unpretty=hir flag to produce a human-readable representation of the HIR.
+For cargo projects this can be done with cargo rustc -- -Z unpretty=hir.
+This output is useful when you need to see at a glance how your code was desugared and transformed
+during AST lowering.
For a full Debug dump of the data in the HIR, use the -Z unpretty=hir-tree flag.
+This may be useful when you need to see the full structure of the HIR from the perspective of the
+compiler.
If you are trying to correlate NodeIds or DefIds with source code, the
+-Z unpretty=expanded,identified flag may be useful.
TODO: anything else? #1159
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/img/coverage-branch-counting-01.png b/img/coverage-branch-counting-01.png
new file mode 100644
index 000000000..c445f3552
Binary files /dev/null and b/img/coverage-branch-counting-01.png differ
diff --git a/img/dataflow-graphviz-example.png b/img/dataflow-graphviz-example.png
new file mode 100644
index 000000000..718411a8c
Binary files /dev/null and b/img/dataflow-graphviz-example.png differ
diff --git a/img/github-cli.png b/img/github-cli.png
new file mode 100644
index 000000000..c3b0e7707
Binary files /dev/null and b/img/github-cli.png differ
diff --git a/img/github-whitespace-changes.png b/img/github-whitespace-changes.png
new file mode 100644
index 000000000..9a19a10aa
Binary files /dev/null and b/img/github-whitespace-changes.png differ
diff --git a/img/llvm-cov-show-01.png b/img/llvm-cov-show-01.png
new file mode 100644
index 000000000..35f045943
Binary files /dev/null and b/img/llvm-cov-show-01.png differ
diff --git a/img/other-peoples-commits.png b/img/other-peoples-commits.png
new file mode 100644
index 000000000..e4fc2c797
Binary files /dev/null and b/img/other-peoples-commits.png differ
diff --git a/img/rustbot-submodules.png b/img/rustbot-submodules.png
new file mode 100644
index 000000000..c2e6937cb
Binary files /dev/null and b/img/rustbot-submodules.png differ
diff --git a/img/submodule-conflicts.png b/img/submodule-conflicts.png
new file mode 100644
index 000000000..e90a6bbe8
Binary files /dev/null and b/img/submodule-conflicts.png differ
diff --git a/img/wpa-initial-memory.png b/img/wpa-initial-memory.png
new file mode 100644
index 000000000..b6020667e
Binary files /dev/null and b/img/wpa-initial-memory.png differ
diff --git a/img/wpa-stack.png b/img/wpa-stack.png
new file mode 100644
index 000000000..29eb5a54b
Binary files /dev/null and b/img/wpa-stack.png differ
diff --git a/implementing_new_features.html b/implementing_new_features.html
new file mode 100644
index 000000000..1c11a0688
--- /dev/null
+++ b/implementing_new_features.html
@@ -0,0 +1,370 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Out-of-band storage and the
+
+
+
+
+ The HIR
+ +The HIR – "High-Level Intermediate Representation" – is the primary IR used
+in most of rustc. It is a compiler-friendly representation of the abstract
+syntax tree (AST) that is generated after parsing, macro expansion, and name
+resolution (see Lowering for how the HIR is created).
+Many parts of HIR resemble Rust surface syntax quite closely, with
+the exception that some of Rust's expression forms have been desugared away.
+For example, for loops are converted into a loop and do not appear in
+the HIR. This makes HIR more amenable to analysis than a normal AST.
This chapter covers the main concepts of the HIR.
+You can view the HIR representation of your code by passing the
+-Z unpretty=hir-tree flag to rustc:
cargo rustc -- -Z unpretty=hir-tree
+You can also use the -Z unpretty=hir option to generate a HIR
+that is closer to the original source code expression:
cargo rustc -- -Z unpretty=hir
+Out-of-band storage and the Crate type
+The top-level data-structure in the HIR is the Crate, which stores
+the contents of the crate currently being compiled (we only ever
+construct HIR for the current crate). Whereas in the AST the crate
+data structure basically just contains the root module, the HIR
+Crate structure contains a number of maps and other things that
+serve to organize the content of the crate for easier access.
For example, the contents of individual items (e.g. modules,
+functions, traits, impls, etc) in the HIR are not immediately
+accessible in the parents. So, for example, if there is a module item
+foo containing a function bar():
+#![allow(unused)] +fn main() { +mod foo { + fn bar() { } +} +} +
then in the HIR the representation of module foo (the Mod
+struct) would only have the ItemId I of bar(). To get the
+details of the function bar(), we would lookup I in the
+items map.
One nice result from this representation is that one can iterate +over all items in the crate by iterating over the key-value pairs +in these maps (without the need to trawl through the whole HIR). +There are similar maps for things like trait items and impl items, +as well as "bodies" (explained below).
+The other reason to set up the representation this way is for better
+integration with incremental compilation. This way, if you gain access
+to an &rustc_hir::Item (e.g. for the mod foo), you do not immediately
+gain access to the contents of the function bar(). Instead, you only
+gain access to the id for bar(), and you must invoke some
+function to lookup the contents of bar() given its id; this gives
+the compiler a chance to observe that you accessed the data for
+bar(), and then record the dependency.
Identifiers in the HIR
+The HIR uses a bunch of different identifiers that coexist and serve different purposes.
+-
+
-
+
A
+DefId, as the name suggests, identifies a particular definition, or top-level +item, in a given crate. It is composed of two parts: aCrateNumwhich identifies +the crate the definition comes from, and aDefIndexwhich identifies the definition +within the crate. UnlikeHirIds, there isn't aDefIdfor every expression, which +makes them more stable across compilations.
+ -
+
A
+LocalDefIdis basically aDefIdthat is known to come from the current crate. +This allows us to drop theCrateNumpart, and use the type system to ensure that +only local definitions are passed to functions that expect a local definition.
+ -
+
A
+HirIduniquely identifies a node in the HIR of the current crate. It is composed +of two parts: anownerand alocal_idthat is unique within theowner. This +combination makes for more stable values which are helpful for incremental compilation. +UnlikeDefIds, aHirIdcan refer to [fine-grained entities][Node] like expressions, +but stays local to the current crate.
+ -
+
A
+BodyIdidentifies a HIRBodyin the current crate. It is currently only +a wrapper around aHirId. For more info about HIR bodies, please refer to the +HIR chapter.
+
These identifiers can be converted into one another through the HIR map.
+The HIR Map
+Most of the time when you are working with the HIR, you will do so via
+the HIR Map, accessible in the tcx via tcx.hir() (and defined in
+the hir::map module). The HIR map contains a number of methods to
+convert between IDs of various kinds and to lookup data associated
+with a HIR node.
For example, if you have a LocalDefId, and you would like to convert it
+to a HirId, you can use tcx.hir().local_def_id_to_hir_id(def_id).
+You need a LocalDefId, rather than a DefId, since only local items have HIR nodes.
Similarly, you can use tcx.hir().find(n) to lookup the node for a
+HirId. This returns a Option<Node<'hir>>, where Node is an enum
+defined in the map. By matching on this, you can find out what sort of
+node the HirId referred to and also get a pointer to the data
+itself. Often, you know what sort of node n is – e.g. if you know
+that n must be some HIR expression, you can do
+tcx.hir().expect_expr(n), which will extract and return the
+&hir::Expr, panicking if n is not in fact an expression.
Finally, you can use the HIR map to find the parents of nodes, via
+calls like tcx.hir().get_parent(n).
HIR Bodies
+A rustc_hir::Body represents some kind of executable code, such as the body
+of a function/closure or the definition of a constant. Bodies are
+associated with an owner, which is typically some kind of item
+(e.g. an fn() or const), but could also be a closure expression
+(e.g. |x, y| x + y). You can use the HIR map to find the body
+associated with a given def-id (maybe_body_owned_by) or to find
+the owner of a body (body_owner_def_id).
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/incrcomp-debugging.html b/incrcomp-debugging.html
new file mode 100644
index 000000000..5406bfba7
--- /dev/null
+++ b/incrcomp-debugging.html
@@ -0,0 +1,296 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ 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.
+NOTE: this section is for language features, not library features, +which use a different process.
+The @rfcbot FCP process
+When the change is small and uncontroversial, 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 the change is potentially controversial, +it would be a bad idea to push it 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).
+If such a change seems to be too small to require a full formal RFC process +(e.g., a small standard library addition, a big refactoring of the code, a +"technically-breaking" change, or a "big bugfix" that basically amounts to a +small feature) but is still too controversial or big to get by with a single r+, +you can propose a final comment period (FCP). Or, 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.
+Again, the FCP process is only needed if you need consensus – if you +don't think anyone would have a problem with your change, it's OK to +get by with only an r+. For example, it is OK to add or modify +unstable command-line flags or attributes 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.
+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 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 "logistic" 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 might 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.
+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 are not supposed to gain tenure +by being unstable and unchanged for a year.
+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. General discussions about the feature should be done on the tracking issue.
+For features that have an RFC, you should use the RFC's +tracking issue for the feature.
+For other features, you'll have to make a tracking issue +for that feature. The issue title should be "Tracking issue +for YOUR FEATURE". Use the "Tracking Issue" issue template.
+Stability in code
+The below steps needs to be followed in order to implement +a new unstable feature:
+-
+
-
+
Open a tracking issue - +if you have an RFC, you can use the tracking issue for the RFC.
+The tracking issue should be labeled with at least
+C-tracking-issue. +For a language feature, a labelF-feature_nameshould be added as well.
+ -
+
Pick a name for the feature gate (for RFCs, use the name +in the RFC).
+
+ -
+
Add the feature name to
+rustc_span/src/symbol.rsin theSymbols {...}block.Note that this block must be in alphabetical order.
+
+ -
+
Add a feature gate declaration to
+rustc_feature/src/unstable.rsin the unstable +declare_featuresblock.
+/// 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!For example:
+
+/// Allows defining identifiers beyond ASCII. +(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 toincomplete:
+/// Allows unsized rvalues at arguments and parameters. +(incomplete, unsized_locals, "CURRENT_RUSTC_VERSION", Some(48055), None), +To avoid semantic merge conflicts, please use
+CURRENT_RUSTC_VERSIONinstead of1.70or +another explicit version number.
+ -
+
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(or +sess.features_untracked().$feature_nameif the +tcx is unavailable)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
+GatedSpansviaself.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_cratefunction, which actually denies +features. Exactly how it is gated depends on the exact type of feature, but most +likely will use thegate_all!()macro.
+ -
+
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.stderrfile by running./x test tests/ui/feature-gates/ --bless.
+ -
+
Add a section to the unstable book, in +
+src/doc/unstable-book/src/language-features/$feature_name.md.
+ -
+
Write a lot of tests for the new feature, preferably in
+tests/ui/$feature_name/. +PRs without tests will not be accepted!
+ -
+
Get your PR reviewed and land it. You have now successfully +implemented a feature in Rust!
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/index.html b/index.html
new file mode 100644
index 000000000..25d3d06c1
--- /dev/null
+++ b/index.html
@@ -0,0 +1,339 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Debugging and Testing Dependencies
+Testing the dependency graph
+There are various ways to write tests against the dependency graph. The
+simplest mechanisms are the #[rustc_if_this_changed] and
+#[rustc_then_this_would_need] annotations. These are used in ui tests to test
+whether the expected set of paths exist in the dependency graph.
As an example, see tests/ui/dep-graph/dep-graph-caller-callee.rs, or the
+tests below.
#[rustc_if_this_changed]
+fn foo() { }
+
+#[rustc_then_this_would_need(TypeckTables)] //~ ERROR OK
+fn bar() { foo(); }
+This should be read as
+++If this (
+foo) is changed, then this (i.e.bar)'s TypeckTables would need to be changed.
Technically, what occurs is that the test is expected to emit the string "OK" on +stderr, associated to this line.
+You could also add the lines
+#[rustc_then_this_would_need(TypeckTables)] //~ ERROR no path
+fn baz() { }
+Whose meaning is
+++If
+foois changed, thenbaz's TypeckTables does not need to be changed. +The macro must emit an error, and the error message must contains "no path".
Recall that the //~ ERROR OK is a comment from the point of view of the Rust
+code we test, but is meaningful from the point of view of the test itself.
Debugging the dependency graph
+Dumping the graph
+The compiler is also capable of dumping the dependency graph for your
+debugging pleasure. To do so, pass the -Z dump-dep-graph flag. The
+graph will be dumped to dep_graph.{txt,dot} in the current
+directory. You can override the filename with the RUST_DEP_GRAPH
+environment variable.
Frequently, though, the full dep graph is quite overwhelming and not +particularly helpful. Therefore, the compiler also allows you to filter +the graph. You can filter in three ways:
+-
+
- All edges originating in a particular set of nodes (usually a single node). +
- All edges reaching a particular set of nodes. +
- All edges that lie between given start and end nodes. +
To filter, use the RUST_DEP_GRAPH_FILTER environment variable, which should
+look like one of the following:
source_filter // nodes originating from source_filter
+-> target_filter // nodes that can reach target_filter
+source_filter -> target_filter // nodes in between source_filter and target_filter
+source_filter and target_filter are a &-separated list of strings.
+A node is considered to match a filter if all of those strings appear in its
+label. So, for example:
RUST_DEP_GRAPH_FILTER='-> TypeckTables'
+would select the predecessors of all TypeckTables nodes. Usually though you
+want the TypeckTables node for some particular fn, so you might write:
RUST_DEP_GRAPH_FILTER='-> TypeckTables & bar'
+This will select only the predecessors of TypeckTables nodes for functions
+with bar in their name.
Perhaps you are finding that when you change foo you need to re-type-check
+bar, but you don't think you should have to. In that case, you might do:
RUST_DEP_GRAPH_FILTER='Hir & foo -> TypeckTables & bar'
+This will dump out all the nodes that lead from Hir(foo) to
+TypeckTables(bar), from which you can (hopefully) see the source
+of the erroneous edge.
Tracking down incorrect edges
+Sometimes, after you dump the dependency graph, you will find some
+path that should not exist, but you will not be quite sure how it came
+to be. When the compiler is built with debug assertions, it can
+help you track that down. Simply set the RUST_FORBID_DEP_GRAPH_EDGE
+environment variable to a filter. Every edge created in the dep-graph
+will be tested against that filter – if it matches, a bug! is
+reported, so you can easily see the backtrace (RUST_BACKTRACE=1).
The syntax for these filters is the same as described in the previous +section. However, note that this filter is applied to every edge +and doesn't handle longer paths in the graph, unlike the previous +section.
+Example:
+You find that there is a path from the Hir of foo to the type
+check of bar and you don't think there should be. You dump the
+dep-graph as described in the previous section and open dep-graph.txt
+to see something like:
Hir(foo) -> Collect(bar)
+Collect(bar) -> TypeckTables(bar)
+That first edge looks suspicious to you. So you set
+RUST_FORBID_DEP_GRAPH_EDGE to Hir&foo -> Collect&bar, re-run, and
+then observe the backtrace. Voila, bug fixed!
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/lang-items.html b/lang-items.html
new file mode 100644
index 000000000..b43e5b5bf
--- /dev/null
+++ b/lang-items.html
@@ -0,0 +1,258 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Getting Started
+Thank you for your interest in contributing to Rust! There are many ways to +contribute, and we appreciate all of them.
+-
+
- Asking Questions + + +
- What should I work on? + + +
- Cloning and Building +
- Contributor Procedures +
- Other Resources +
If this is your first time contributing, the walkthrough chapter can give you a good example of +how a typical contribution would go.
+This documentation is not intended to be comprehensive; it is meant to be a +quick guide for the most useful things. For more information, see this +chapter on how to build and run the compiler.
+Asking Questions
+If you have questions, please make a post on the Rust Zulip server or
+internals.rust-lang.org. If you are contributing to Rustup, be aware they are not on
+Zulip - you can ask questions in #wg-rustup on Discord.
+See the list of teams and working groups and the Community page on the
+official website for more resources.
As a reminder, all contributors are expected to follow our Code of Conduct.
+The compiler team (or t-compiler) usually hangs out in Zulip in this
+"stream"; it will be easiest to get questions answered there.
Please ask questions! A lot of people report feeling that they are "wasting
+expert time", but nobody on t-compiler feels this way. Contributors are
+important to us.
Also, if you feel comfortable, prefer public topics, as this means others can +see the questions and answers, and perhaps even integrate them back into this +guide :)
+Experts
+Not all t-compiler members are experts on all parts of rustc; it's a
+pretty large project. To find out who could have some expertise on
+different parts of the compiler, consult triagebot assign groups.
+The sections that start with [assign* in triagebot.toml file.
+But also, feel free to ask questions even if you can't figure out who to ping.
Another way to find experts for a given part of the compiler is to see who has made recent commits.
+For example, to find people who have recently worked on name resolution since the 1.68.2 release,
+you could run git shortlog -n 1.68.2.. compiler/rustc_resolve/. Ignore any commits starting with
+"Rollup merge" or commits by @bors (see CI contribution procedures for
+more information about these commits).
Etiquette
+We do ask that you be mindful to include as much useful information as you can +in your question, but we recognize this can be hard if you are unfamiliar with +contributing to Rust.
+Just pinging someone without providing any context can be a bit annoying and
+just create noise, so we ask that you be mindful of the fact that the
+t-compiler folks get a lot of pings in a day.
What should I work on?
+The Rust project is quite large and it can be difficult to know which parts of the project need +help, or are a good starting place for beginners. Here are some suggested starting places.
+Easy or mentored issues
+If you're looking for somewhere to start, check out the following issue +search. See the Triage for an explanation of these labels. You can also try +filtering the search to areas you're interested in. For example:
+-
+
repo:rust-lang/rust-clippywill only show clippy issues
+label:T-compilerwill only show issues related to the compiler
+label:A-diagnosticswill only show diagnostic issues
+
Not all important or beginner work has issue labels. +See below for how to find work that isn't labelled.
+Recurring work
+Some work is too large to be done by a single person. In this case, it's common to have "Tracking +issues" to co-ordinate the work between contributors. Here are some example tracking issues where +it's easy to pick up work without a large time commitment:
+-
+
- Rustdoc Askama Migration +
- Diagnostic Translation +
- Move UI tests to subdirectories +
- Port run-make tests from Make to Rust +
If you find more recurring work, please feel free to add it here!
+Clippy issues
+The Clippy project has spent a long time making its contribution process as friendly to newcomers +as possible. Consider working on it first to get familiar with the process and the compiler +internals.
+See the Clippy contribution guide for instructions on getting started.
+Diagnostic issues
+Many diagnostic issues are self-contained and don't need detailed background knowledge of the +compiler. You can see a list of diagnostic issues here.
+Picking up abandoned pull requests
+Sometimes, contributors send a pull request, but later find out that they don't have enough
+time to work on it, or they simply are not interested in it anymore. Such PRs are often
+eventually closed and they receive the S-inactive label. You could try to examine some of
+these PRs and pick up the work. You can find the list of such PRs here.
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
+pull request, continuing the work on the feature.
Contributing to std (standard library)
+See std-dev-guide.
+Contributing code to other Rust projects
+There are a bunch of other projects that you can contribute to outside of the
+rust-lang/rust repo, including cargo, miri, rustup, and many others.
These repos might have their own contributing guidelines and procedures. Many +of them are owned by working groups. For more info, see the documentation in those repos' READMEs.
+Other ways to contribute
+There are a bunch of other ways you can contribute, especially if you don't
+feel comfortable jumping straight into the large rust-lang/rust codebase.
The following tasks are doable without much background knowledge but are +incredibly helpful:
+-
+
- Cleanup crew: find minimal reproductions of ICEs, bisect +regressions, etc. This is a way of helping that saves a ton of time for +others to fix an error later. +
- Writing documentation: if you are feeling a bit more intrepid, you could try +to read a part of the code and write doc comments for it. This will help you +to learn some part of the compiler while also producing a useful artifact! +
- Triaging issues: categorizing, replicating, and minimizing issues is very helpful to the Rust maintainers. +
- Working groups: there are a bunch of working groups on a wide variety +of rust-related things. +
- Answer questions in the Get Help! channels on the Rust Discord +server, on users.rust-lang.org, or on +StackOverflow. +
- Participate in the RFC process. +
- Find a requested community library, build it, and publish +it to Crates.io. Easier said than done, but very, very +valuable! +
Cloning and Building
+See "How to build and run the compiler".
+Contributor Procedures
+This section has moved to the "Contribution Procedures" chapter.
+Other Resources
+This section has moved to the "About this guide" chapter.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/licenses.html b/licenses.html
new file mode 100644
index 000000000..167a12d0f
--- /dev/null
+++ b/licenses.html
@@ -0,0 +1,244 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Lang items
+The compiler has certain pluggable operations; that is, functionality that isn't hard-coded into
+the language, but is implemented in libraries, with a special marker to tell the compiler it
+exists. The marker is the attribute #[lang = "..."], and there are various different values of
+..., i.e. various different 'lang items'.
Many such lang items can be implemented only in one sensible way, such as add (trait core::ops::Add) or future_trait (trait core::future::Future). Others can be overridden to
+achieve some specific goals; for example, you can control your binary's entrypoint.
Features provided by lang items include:
+-
+
- overloadable operators via traits: the traits corresponding to the
+
==,<, dereference (*),+, etc. operators are all +marked with lang items; those specific four areeq,ord, +deref, andaddrespectively.
+ - panicking and stack unwinding; the
eh_personality,panicand +panic_bounds_checkslang items.
+ - the traits in
std::markerused to indicate properties of types used by the compiler; +lang itemssend,syncandcopy.
+ - the special marker types used for variance indicators found in
+
core::marker; lang itemphantom_data.
+
Lang items are loaded lazily by the compiler; e.g. if one never uses Box
+then there is no need to define functions for exchange_malloc and
+box_free. rustc will emit an error when an item is needed but not found
+in the current crate or any that it depends on.
Most lang items are defined by the core library, but if you're trying to build an
+executable with #![no_std], you'll still need to define a few lang items that are
+usually provided by std.
Retrieving a language item
+You can retrieve lang items by calling tcx.lang_items().
Here's a small example of retrieving the trait Sized {} language item:
+#![allow(unused)] +fn main() { +// Note that in case of `#![no_core]`, the trait is not available. +if let Some(sized_trait_def_id) = tcx.lang_items().sized_trait() { + // do something with `sized_trait_def_id` +} +} +
Note that sized_trait() returns an Option, not the DefId itself.
+That's because language items are defined in the standard library, so if someone compiles with
+#![no_core] (or for some lang items, #![no_std]), the lang item may not be present.
+You can either:
-
+
- Give a hard error if the lang item is necessary to continue (don't panic, since this can happen in +user code). +
- Proceed with limited functionality, by just omitting whatever you were going to do with the
+
DefId.
+
List of all language items
+You can find language items in the following places:
+-
+
- An exhaustive reference in the compiler documentation:
rustc_hir::LangItem
+ - An auto-generated list with source locations by using ripgrep:
rg '#\[.*lang =' library/
+
Note that language items are explicitly unstable and may change in any new release.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/llvm-coverage-instrumentation.html b/llvm-coverage-instrumentation.html
new file mode 100644
index 000000000..ecce4dde6
--- /dev/null
+++ b/llvm-coverage-instrumentation.html
@@ -0,0 +1,599 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ rust-lang/rust Licenses
+The rustc compiler source and standard library are dual licensed under the Apache License v2.0 and the MIT License unless otherwise specified.
Detailed licensing information is available in the COPYRIGHT document of the rust-lang/rust repository.
Guidelines for reviewers
+In general, reviewers need to be looking not only for the code quality of contributions but also +that they are properly licensed. +We have some tips below for things to look out for when reviewing, but if you ever feel uncertain +as to whether some code might be properly licensed, err on the safe side — reach out to the Council +or Compiler Team Leads for feedback!
+Things to watch out for:
+-
+
- The PR author states that they copied, ported, or adapted the code from some other source. +
- There is a comment in the code pointing to a webpage or describing where the algorithm was taken +from. +
- The algorithm or code pattern seems like it was likely copied from somewhere else. +
- When adding new dependencies, double check the dependency's license. +
In all of these cases, we will want to check that source to make sure it is licensed in a way +that is compatible with Rust’s license.
+Examples
+-
+
- Porting C code from a GPL project, like GNU binutils, is not allowed. That would require Rust +itself to be licensed under the GPL. +
- Copying code from an algorithms text book may be allowed, but some algorithms are patented. +
Porting
+Contributions to rustc, especially around platform and compiler intrinsics, often include porting +over work from other projects, mainly LLVM and GCC.
+Some general rules apply:
+-
+
- Copying work needs to adhere to the original license
+
-
+
- This applies to direct copy & paste +
- This also applies to code you looked at and ported +
+
In general, taking inspiration from other codebases is fine, but please exercise caution when +porting code.
+Ports of full libraries (e.g. C libraries shipped with LLVM) must keep the license of the original +library.
+ +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/macro-expansion.html b/macro-expansion.html
new file mode 100644
index 000000000..78dca73ec
--- /dev/null
+++ b/macro-expansion.html
@@ -0,0 +1,675 @@
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Recommended
+Components of LLVM Coverage Instrumentation in
+MIR Pass:
+Implementation Details of the
+The
+
+
+
+
+
+ LLVM Source-Based Code Coverage
+-
+
- Recommended
config.tomlsettings
+ - Rust symbol mangling +
- Components of LLVM Coverage Instrumentation in
rustc+ +
+ - Testing LLVM Coverage +
- Implementation Details of the
InstrumentCoverageMIR Pass + +
+
rustc supports detailed source-based code and test coverage analysis
+with a command line option (-C instrument-coverage) that instruments Rust
+libraries and binaries with additional instructions and data, at compile time.
The coverage instrumentation injects calls to the LLVM intrinsic instruction
+llvm.instrprof.increment at code branches
+(based on a MIR-based control flow analysis), and LLVM converts these to
+instructions that increment static counters, when executed. The LLVM coverage
+instrumentation also requires a Coverage Map that encodes source metadata,
+mapping counter IDs--directly and indirectly--to the file locations (with
+start and end line and column).
Rust libraries, with or without coverage instrumentation, can be linked into
+instrumented binaries. When the program is executed and cleanly terminates,
+LLVM libraries write the final counter values to a file (default.profraw or
+a custom file set through environment variable LLVM_PROFILE_FILE).
Developers use existing LLVM coverage analysis tools to decode .profraw
+files, with corresponding Coverage Maps (from matching binaries that produced
+them), and generate various reports for analysis, for example:
+
Detailed instructions and examples are documented in the +rustc book.
+Recommended config.toml settings
+When working on the coverage instrumentation code, it is usually necessary to
+enable the profiler runtime by setting profiler = true in [build].
+This allows the compiler to produce instrumented binaries, and makes it possible
+to run the full coverage test suite.
Enabling debug assertions in the compiler and in LLVM is recommended, but not +mandatory.
+# Similar to the "compiler" profile, but also enables debug assertions in LLVM.
+# These assertions can detect malformed coverage mappings in some cases.
+profile = "codegen"
+
+[build]
+# IMPORTANT: This tells the build system to build the LLVM profiler runtime.
+# Without it, the compiler can't produce coverage-instrumented binaries,
+# and many of the coverage tests will be skipped.
+profiler = true
+
+[rust]
+# Enable debug assertions in the compiler.
+debug-assertions = true
+Rust symbol mangling
+-C instrument-coverage automatically enables Rust symbol mangling v0 (as
+if the user specified -C symbol-mangling-version=v0 option when invoking
+rustc) to ensure consistent and reversible name mangling. This has two
+important benefits:
-
+
- LLVM coverage tools can analyze coverage over multiple runs, including some +changes to source code; so mangled names must be consistent across compilations. +
- LLVM coverage reports can report coverage by function, and even separates +out the coverage counts of each unique instantiation of a generic function, +if invoked with multiple type substitution variations. +
Components of LLVM Coverage Instrumentation in rustc
+LLVM Runtime Dependency
+Coverage data is only generated by running the executable Rust program. rustc
+statically links coverage-instrumented binaries with LLVM runtime code
+(compiler-rt) that implements program hooks
+(such as an exit hook) to write the counter values to the .profraw file.
In the rustc source tree,
+library/profiler_builtins bundles the LLVM compiler-rt code into a Rust library crate.
+Note that when building rustc,
+profiler_builtins is only included when build.profiler = true is set in config.toml.
When compiling with -C instrument-coverage,
+CrateLoader::postprocess() dynamically loads
+profiler_builtins by calling inject_profiler_runtime().
MIR Pass: InstrumentCoverage
+Coverage instrumentation is performed on the MIR with a MIR pass
+called InstrumentCoverage. This MIR pass analyzes
+the control flow graph (CFG)--represented by MIR BasicBlocks--to identify
+code branches, attaches FunctionCoverageInfo to the function's body,
+and injects additional Coverage statements into the
+BasicBlocks.
A MIR Coverage statement is a virtual instruction that indicates a counter
+should be incremented when its adjacent statements are executed, to count
+a span of code (CodeRegion). It counts the number of times a
+branch is executed, and is referred to by coverage mappings in the function's
+coverage-info struct.
Note that many coverage counters will not be converted into
+physical counters (or any other executable instructions) in the final binary.
+Some of them will be (see CoverageKind::CounterIncrement),
+but other counters can be computed on the fly, when generating a coverage
+report, by mapping a CodeRegion to a coverage-counter expression.
As an example:
++#![allow(unused)] +fn main() { +fn some_func(flag: bool) { + // increment Counter(1) + ... + if flag { + // increment Counter(2) + ... + } else { + // count = Expression(1) = Counter(1) - Counter(2) + ... + } + // count = Expression(2) = Counter(1) + Zero + // or, alternatively, Expression(2) = Counter(2) + Expression(1) + ... +} +} +
In this example, four contiguous code regions are counted while only +incrementing two counters.
+CFG analysis is used to not only determine where the branches are, for
+conditional expressions like if, else, match, and loop, but also to
+determine where expressions can be used in place of physical counters.
The advantages of optimizing coverage through expressions are more pronounced
+with loops. Loops generally include at least one conditional branch that
+determines when to break out of a loop (a while condition, or an if or
+match with a break). In MIR, this is typically lowered to a SwitchInt,
+with one branch to stay in the loop, and another branch to break out of the
+loop. The branch that breaks out will almost always execute less often,
+so InstrumentCoverage chooses to add a CounterIncrement to that branch, and
+uses an expression (Counter(loop) - Counter(break)) for the branch that
+continues.
The InstrumentCoverage MIR pass is documented in
+more detail below.
Counter Injection and Coverage Map Pre-staging
+When the compiler enters the Codegen phase, with a
+coverage-enabled MIR, codegen_statement() converts each
+MIR Statement into some backend-specific action or instruction.
+codegen_statement() forwards Coverage statements to
+codegen_coverage():
+#![allow(unused)] +fn main() { + pub fn codegen_statement(&mut self, mut bx: Bx, statement: &mir::Statement<'tcx>) -> Bx { + ... + match statement.kind { + ... + mir::StatementKind::Coverage(box ref coverage) => { + self.codegen_coverage(bx, coverage, statement.source_info.scope); + } +} +
codegen_coverage() handles inlined statements and then forwards the coverage
+statement to Builder::add_coverage, which handles each CoverageKind as
+follows:
-
+
- For both
CounterIncrementandExpressionUsed, the underlying counter or +expression ID is passed through to the correspondingFunctionCoverage+struct to indicate that the corresponding regions of code were not removed +by MIR optimizations.
+ - For
CoverageKind::CounterIncrements, an instruction is injected in the backend +IR to increment the physical counter, by calling theBuilderMethod+instrprof_increment().
+
+#![allow(unused)] +fn main() { + fn add_coverage(&mut self, instance: Instance<'tcx>, coverage: &Coverage) { + ... + let Coverage { kind } = coverage; + match *kind { + CoverageKind::CounterIncrement { id } => { + func_coverage.mark_counter_id_seen(id); + ... + bx.instrprof_increment(fn_name, hash, num_counters, index); + } + CoverageKind::ExpressionUsed { id } => { + func_coverage.mark_expression_id_seen(id); + } + } + } +} +
++The function name
+instrprof_increment()is taken from the LLVM intrinsic +call of the same name (llvm.instrprof.increment), +and uses the same arguments and types; but note that, up to and through this +stage (even though modeled after LLVM's implementation for code coverage +instrumentation), the data and instructions are not strictly LLVM-specific.But since LLVM is the only Rust-supported backend with the tooling to +process this form of coverage instrumentation, the backend for
+Coverage+statements is only implemented for LLVM, at this time.
Coverage Map Generation
+With the instructions to increment counters now implemented in LLVM IR, +the last remaining step is to inject the LLVM IR variables that hold the +static data for the coverage map.
+rustc_codegen_llvm's compile_codegen_unit() calls
+coverageinfo_finalize(),
+which delegates its implementation to the
+rustc_codegen_llvm::coverageinfo::mapgen module.
For each function Instance (code-generated from MIR, including multiple
+instances of the same MIR for generic functions that have different type
+substitution combinations), mapgen's finalize() method queries the
+Instance-associated FunctionCoverage for its Counters, Expressions,
+and CodeRegions; and calls LLVM codegen APIs to generate
+properly-configured variables in LLVM IR, according to very specific
+details of the LLVM Coverage Mapping Format
+(Version 6).1
1
+
+The Rust compiler (as of Nov 2024) supports LLVM Coverage Mapping Format 6. +The Rust compiler will automatically use the most up-to-date coverage mapping format +version that is compatible with the compiler's built-in version of LLVM.
++#![allow(unused)] +fn main() { +pub fn finalize<'ll, 'tcx>(cx: &CodegenCx<'ll, 'tcx>) { + ... + if !tcx.sess.instrument_coverage_except_unused_functions() { + add_unused_functions(cx); + } + + let mut function_coverage_map = match cx.coverage_context() { + Some(ctx) => ctx.take_function_coverage_map(), + None => return, + }; + ... + let mut mapgen = CoverageMapGenerator::new(); + + for (instance, function_coverage) in function_coverage_map { + ... + let coverage_mapping_buffer = llvm::build_byte_buffer(|coverage_mapping_buffer| { + mapgen.write_coverage_mapping(expressions, counter_regions, coverage_mapping_buffer); + }); +} +
code snippet trimmed for brevity
+One notable first step performed by mapgen::finalize() is the call to
+add_unused_functions():
When finalizing the coverage map, FunctionCoverage only has the CodeRegions
+and counters for the functions that went through codegen; such as public
+functions and "used" functions (functions referenced by other "used" or public
+items). Any other functions (considered unused) were still parsed and processed
+through the MIR stage.
The set of unused functions is computed via the set difference of all MIR
+DefIds (tcx query mir_keys) minus the codegenned DefIds (tcx query
+codegened_and_inlined_items). add_unused_functions() computes the set of
+unused functions, queries the tcx for the previously-computed CodeRegions,
+for each unused MIR, synthesizes an LLVM function (with no internal statements,
+since it will not be called), and adds a new FunctionCoverage, with
+Unreachable code regions.
Testing LLVM Coverage
+(See also the compiletest documentation for the tests/coverage
+test suite.)
Coverage instrumentation in the MIR is validated by a mir-opt test:
+tests/mir-opt/coverage/instrument_coverage.rs.
Coverage instrumentation in LLVM IR is validated by the tests/coverage
+test suite in coverage-map mode.
+These tests compile a test program to LLVM IR assembly, and then
+use the src/tools/coverage-dump tool to extract and pretty-print the
+coverage mappings that would be embedded in the final binary.
End-to-end testing of coverage instrumentation and coverage reporting is
+performed by the tests/coverage test suite in coverage-run mode,
+and by the tests/coverage-run-rustdoc test suite.
+These tests compile and run a test program with coverage
+instrumentation, then use LLVM tools to convert the coverage data into a
+human-readable coverage report.
++Tests in
+coverage-runmode have an implicit//@ needs-profiler-runtime+directive, so they will be skipped if the profiler runtime has not been +enabled inconfig.toml.
Finally, the tests/codegen/instrument-coverage/testprog.rs test compiles a simple Rust program
+with -C instrument-coverage and compares the compiled program's LLVM IR to
+expected LLVM IR instructions and structured data for a coverage-enabled
+program, including various checks for Coverage Map-related metadata and the LLVM
+intrinsic calls to increment the runtime counters.
Expected results for the coverage, coverage-run-rustdoc,
+and mir-opt tests can be refreshed by running:
./x test coverage --bless
+./x test coverage-run-rustdoc --bless
+./x test tests/mir-opt --bless
+Implementation Details of the InstrumentCoverage MIR Pass
+The bulk of the implementation of the InstrumentCoverage MIR pass is performed
+by instrument_function_for_coverage. For each eligible MIR body, the instrumentor:
-
+
- Prepares a coverage graph +
- Extracts mapping information from MIR +
- Prepares counters for each relevant node/edge in the coverage graph +
- Creates mapping data to be embedded in side-tables attached to the MIR body +
- Injects counters and other coverage statements into MIR +
The coverage graph is a coverage-specific simplification of the MIR control
+flow graph (CFG). Its nodes are BasicCoverageBlocks, which
+encompass one or more sequentially-executed MIR BasicBlocks
+(with no internal branching).
Nodes and edges in the graph can have associated BcbCounters, which are
+stored in CoverageCounters.
The CoverageGraph
+The CoverageGraph is derived from the MIR (mir::Body).
+#![allow(unused)] +fn main() { + let basic_coverage_blocks = CoverageGraph::from_mir(mir_body); +} +
Like mir::Body, the CoverageGraph is also a
+DirectedGraph. Both graphs represent the function's
+fundamental control flow, with many of the same
+graph traits, supporting start_node(), num_nodes(),
+successors(), predecessors(), and is_dominated_by().
For anyone that knows how to work with the MIR, as a CFG, the
+CoverageGraph will be familiar, and can be used in much the same way.
+The nodes of the CoverageGraph are BasicCoverageBlocks (BCBs), which
+index into an IndexVec of BasicCoverageBlockData. This is analogous
+to the MIR CFG of BasicBlocks that index BasicBlockData.
Each BasicCoverageBlockData captures one or more MIR BasicBlocks,
+exclusively, and represents the maximal-length sequence of BasicBlocks
+without conditional branches.
compute_basic_coverage_blocks() builds the
+CoverageGraph as a coverage-specific simplification of the MIR CFG. In
+contrast with the SimplifyCfg MIR pass, this step does
+not alter the MIR itself, because the CoverageGraph aggressively simplifies
+the CFG, and ignores nodes that are not relevant to coverage. For example:
-
+
- The BCB CFG ignores (excludes) branches considered not relevant
+to the current coverage solution. It excludes unwind-related code2
+that is injected by the Rust compiler but has no physical source
+code to count, which allows a
Call-terminated BasicBlock +to be merged with its successor, within a single BCB.
+ - A
Goto-terminatedBasicBlockcan be merged with its successor +as long as it has the only incoming edge to the successor +BasicBlock.
+ - Some BasicBlock terminators support Rust-specific concerns--like
+borrow-checking--that are not relevant to coverage analysis.
FalseUnwind, +for example, can be treated the same as aGoto(potentially merged with +its successor into the same BCB).
+
2
+
+(Note, however, that Issue #78544 considers
+providing future support for coverage of programs that intentionally
+panic, as an option, with some non-trivial cost.)
The BCB CFG is critical to simplifying the coverage analysis by ensuring graph path-based
+queries (is_dominated_by(), predecessors, successors, etc.) have branch (control flow)
+significance.
make_bcb_counters()
+make_bcb_counters traverses the CoverageGraph and adds a
+Counter or Expression to every BCB. It uses Control Flow Analysis
+to determine where an Expression can be used in place of a Counter.
+Expressions have no runtime overhead, so if a viable expression (adding or
+subtracting two other counters or expressions) can compute the same result as
+an embedded counter, an Expression is preferred.
TraverseCoverageGraphWithLoops
+provides a traversal order that ensures all BasicCoverageBlock nodes in a
+loop are visited before visiting any node outside that loop. The traversal
+state includes a context_stack, with the current loop's context information
+(if in a loop), as well as context for nested loops.
Within loops, nodes with multiple outgoing edges (generally speaking, these
+are BCBs terminated in a SwitchInt) can be optimized when at least one
+branch exits the loop and at least one branch stays within the loop. (For an
+if or while, there are only two branches, but a match may have more.)
A branch that does not exit the loop should be counted by Expression, if
+possible. Note that some situations require assigning counters to BCBs before
+they are visited by traversal, so the counter_kind (CoverageKind for
+a Counter or Expression) may have already been assigned, in which case
+one of the other branches should get the Expression.
For a node with more than two branches (such as for more than two
+match patterns), only one branch can be optimized by Expression. All
+others require a Counter (unless its BCB counter_kind was previously
+assigned).
A branch expression is derived from the equation:
+Counter(branching_node) = SUM(Counter(branches))
+It's important to
+be aware that the branches in this equation are the outgoing edges
+from the branching_node, but a branch's target node may have other
+incoming edges. Given the following graph, for example, the count for
+B is the sum of its two incoming edges:
+
In this situation, BCB node B may require an edge counter for its
+"edge from A", and that edge might be computed from an Expression,
+Counter(A) - Counter(C). But an expression for the BCB node B
+would be the sum of all incoming edges:
Expression((Counter(A) - Counter(C)) + SUM(Counter(remaining_edges)))
+Note that this is only one possible configuration. The actual choice
+of Counter vs. Expression also depends on the order of counter
+assignments, and whether a BCB or incoming edge counter already has
+its Counter or Expression.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mark.min.js b/mark.min.js
new file mode 100644
index 000000000..163623188
--- /dev/null
+++ b/mark.min.js
@@ -0,0 +1,7 @@
+/*!***************************************************
+* mark.js v8.11.1
+* https://markjs.io/
+* Copyright (c) 2014–2018, Julian Kühnel
+* Released under the MIT license https://git.io/vwTVl
+*****************************************************/
+!function(e,t){"object"==typeof exports&&"undefined"!=typeof module?module.exports=t():"function"==typeof define&&define.amd?define(t):e.Mark=t()}(this,function(){"use strict";var e="function"==typeof Symbol&&"symbol"==typeof Symbol.iterator?function(e){return typeof e}:function(e){return e&&"function"==typeof Symbol&&e.constructor===Symbol&&e!==Symbol.prototype?"symbol":typeof e},t=function(e,t){if(!(e instanceof t))throw new TypeError("Cannot call a class as a function")},n=function(){function e(e,t){for(var n=0;n
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Macro expansion
+-
+
- Expansion and AST Integration + + +
- Hygiene and Hierarchies + + +
- Producing Macro Output +
- Macros By Example + + +
- Procedural Macros + + +
++N.B.
+rustc_ast,rustc_expand, andrustc_builtin_macrosare all +undergoing refactoring, so some of the links in this chapter may be broken.
Rust has a very powerful macro system. In the previous chapter, we saw how +the parser sets aside macros to be expanded (using temporary placeholders). +This chapter is about the process of expanding those macros iteratively until +we have a complete Abstract Syntax Tree (AST) for our crate with no +unexpanded macros (or a compile error).
+First, we discuss the algorithm that expands and integrates macro output into +ASTs. Next, we take a look at how hygiene data is collected. Finally, we look +at the specifics of expanding different types of macros.
+Many of the algorithms and data structures described below are in rustc_expand,
+with fundamental data structures in rustc_expand::base.
Also of note, cfg and cfg_attr are treated specially from other macros, and are
+handled in rustc_expand::config.
Expansion and AST Integration
+Firstly, expansion happens at the crate level. Given a raw source code for
+a crate, the compiler will produce a massive AST with all macros expanded, all
+modules inlined, etc. The primary entry point for this process is the
+MacroExpander::fully_expand_fragment method. With few exceptions, we
+use this method on the whole crate (see "Eager Expansion"
+below for more detailed discussion of edge case expansion issues).
At a high level, fully_expand_fragment works in iterations. We keep a
+queue of unresolved macro invocations (i.e. macros we haven't found the
+definition of yet). We repeatedly try to pick a macro from the queue, resolve
+it, expand it, and integrate it back. If we can't make progress in an
+iteration, this represents a compile error. Here is the algorithm:
-
+
- Initialize a
queueof unresolved macros.
+ - Repeat until
queueis empty (or we make no progress, which is an error): +-
+
- Resolve imports in our partially built crate as +much as possible. +
- Collect as many macro
Invocations as possible from our +partially built crate (fn-like, attributes, derives) and add them to the +queue.
+ - Dequeue the first element and attempt to resolve it. +
- If it's resolved:
+
-
+
- Run the macro's expander function that consumes a
TokenStreamor +AST and produces aTokenStreamorAstFragment(depending on +the macro kind). (ATokenStreamis a collection ofTokenTrees, +each of which are a token (punctuation, identifier, or literal) or a +delimited group (anything inside()/[]/{})). +-
+
- At this point, we know everything about the macro itself and can
+call
set_expn_datato fill in its properties in the global +data; that is the hygiene data associated withExpnId(see +Hygiene below).
+
+ - At this point, we know everything about the macro itself and can
+call
- Integrate that piece of AST into the currently-existing though
+partially-built AST. This is essentially where the "token-like mass"
+becomes a proper set-in-stone AST with side-tables. It happens as
+follows:
+
-
+
- If the macro produces tokens (e.g. a proc macro), we parse into +an AST, which may produce parse errors. +
- During expansion, we create
SyntaxContexts (hierarchy 2) (see +Hygiene below).
+ - These three passes happen one after another on every AST fragment
+freshly expanded from a macro:
+
-
+
NodeIds are assigned byInvocationCollector. This +also collects new macro calls from this new AST piece and +adds them to the queue.
+- "Def paths" are created and
DefIds are +assigned to them byDefCollector.
+ - Names are put into modules (from the resolver's point of
+view) by
BuildReducedGraphVisitor.
+
+
+ - After expanding a single macro and integrating its output, continue
+to the next iteration of
fully_expand_fragment.
+
+ - Run the macro's expander function that consumes a
- If it's not resolved:
+
-
+
- Put the macro back in the queue. +
- Continue to next iteration... +
+
+
Error Recovery
+If we make no progress in an iteration we have reached a compilation error
+(e.g. an undefined macro). We attempt to recover from failures (i.e.
+unresolved macros or imports) with the intent of generating diagnostics.
+Failure recovery happens by expanding unresolved macros into
+ExprKind::Err and allows compilation to continue past the first error
+so that rustc can report more errors than just the original failure.
Name Resolution
+Notice that name resolution is involved here: we need to resolve imports and
+macro names in the above algorithm. This is done in
+rustc_resolve::macros, which resolves macro paths, validates
+those resolutions, and reports various errors (e.g. "not found", "found, but
+it's unstable", "expected x, found y"). However, we don't try to resolve
+other names yet. This happens later, as we will see in the chapter: Name
+Resolution.
Eager Expansion
+Eager expansion means we expand the arguments of a macro invocation before +the macro invocation itself. This is implemented only for a few special +built-in macros that expect literals; expanding arguments first for some of +these macro results in a smoother user experience. As an example, consider +the following:
+macro bar($i: ident) { $i }
+macro foo($i: ident) { $i }
+
+foo!(bar!(baz));
+A lazy-expansion would expand foo! first. An eager-expansion would expand
+bar! first.
Eager-expansion is not a generally available feature of Rust. Implementing
+eager-expansion more generally would be challenging, so we implement it for a
+few special built-in macros for the sake of user-experience. The built-in
+macros are implemented in rustc_builtin_macros, along with some other
+early code generation facilities like injection of standard library imports or
+generation of test harness. There are some additional helpers for building
+AST fragments in rustc_expand::build. Eager-expansion generally
+performs a subset of the things that lazy (normal) expansion does. It is done
+by invoking fully_expand_fragment on only part of a crate (as opposed
+to the whole crate, like we normally do).
Other Data Structures
+Here are some other notable data structures involved in expansion and +integration:
+-
+
ResolverExpand- atraitused to break crate dependencies. This allows the +resolver services to be used inrustc_ast, despiterustc_resolveand +pretty much everything else depending onrustc_ast.
+ExtCtxt/ExpansionData- holds various intermediate expansion +infrastructure data.
+Annotatable- a piece of AST that can be an attribute target, almost the same +thing asAstFragmentexcept for types and patterns that can be produced by +macros but cannot be annotated with attributes.
+MacResult- a "polymorphic" AST fragment, something that can turn into +a differentAstFragmentdepending on itsAstFragmentKind(i.e. an item, +expression, pattern, etc).
+
Hygiene and Hierarchies
+If you have ever used the C/C++ preprocessor macros, you know that there are some +annoying and hard-to-debug gotchas! For example, consider the following C code:
+#define DEFINE_FOO struct Bar {int x;}; struct Foo {Bar bar;};
+
+// Then, somewhere else
+struct Bar {
+ ...
+};
+
+DEFINE_FOO
+Most people avoid writing C like this – and for good reason: it doesn't
+compile. The struct Bar defined by the macro clashes names with the struct Bar defined in the code. Consider also the following example:
#define DO_FOO(x) {\
+ int y = 0;\
+ foo(x, y);\
+ }
+
+// Then elsewhere
+int y = 22;
+DO_FOO(y);
+Do you see the problem? We wanted to generate a call foo(22, 0), but instead
+we got foo(0, 0) because the macro defined its own y!
These are both examples of macro hygiene issues. Hygiene relates to how to +handle names defined within a macro. In particular, a hygienic macro system +prevents errors due to names introduced within a macro. Rust macros are hygienic +in that they do not allow one to write the sorts of bugs above.
+At a high level, hygiene within the Rust compiler is accomplished by keeping +track of the context where a name is introduced and used. We can then +disambiguate names based on that context. Future iterations of the macro system +will allow greater control to the macro author to use that context. For example, +a macro author may want to introduce a new name to the context where the macro +was called. Alternately, the macro author may be defining a variable for use +only within the macro (i.e. it should not be visible outside the macro).
+The context is attached to AST nodes. All AST nodes generated by macros have
+context attached. Additionally, there may be other nodes that have context
+attached, such as some desugared syntax (non-macro-expanded nodes are
+considered to just have the "root" context, as described below).
+Throughout the compiler, we use rustc_span::Spans to refer to code locations.
+This struct also has hygiene information attached to it, as we will see later.
Because macros invocations and definitions can be nested, the syntax context of +a node must be a hierarchy. For example, if we expand a macro and there is +another macro invocation or definition in the generated output, then the syntax +context should reflect the nesting.
+However, it turns out that there are actually a few types of context we may +want to track for different purposes. Thus, there are not just one but three +expansion hierarchies that together comprise the hygiene information for a +crate.
+All of these hierarchies need some sort of "macro ID" to identify individual
+elements in the chain of expansions. This ID is ExpnId. All macros receive
+an integer ID, assigned continuously starting from 0 as we discover new macro
+calls. All hierarchies start at ExpnId::root, which is its own
+parent.
The rustc_span::hygiene crate contains all of the hygiene-related algorithms
+(with the exception of some hacks in Resolver::resolve_crate_root)
+and structures related to hygiene and expansion that are kept in global data.
The actual hierarchies are stored in HygieneData. This is a global
+piece of data containing hygiene and expansion info that can be accessed from
+any Ident without any context.
The Expansion Order Hierarchy
+The first hierarchy tracks the order of expansions, i.e., when a macro +invocation is in the output of another macro.
+Here, the children in the hierarchy will be the "innermost" tokens. The
+ExpnData struct itself contains a subset of properties from both macro
+definition and macro call available through global data.
+ExpnData::parent tracks the child-to-parent link in this hierarchy.
For example:
+macro_rules! foo { () => { println!(); } }
+
+fn main() { foo!(); }
+In this code, the AST nodes that are finally generated would have hierarchy
+root -> id(foo) -> id(println).
The Macro Definition Hierarchy
+The second hierarchy tracks the order of macro definitions, i.e., when we are +expanding one macro another macro definition is revealed in its output. This +one is a bit tricky and more complex than the other two hierarchies.
+SyntaxContext represents a whole chain in this hierarchy via an ID.
+SyntaxContextData contains data associated with the given
+SyntaxContext; mostly it is a cache for results of filtering that chain in
+different ways. SyntaxContextData::parent is the child-to-parent
+link here, and SyntaxContextData::outer_expns are individual
+elements in the chain. The "chaining-operator" is
+SyntaxContext::apply_mark in compiler code.
A Span, mentioned above, is actually just a compact representation of
+a code location and SyntaxContext. Likewise, an Ident is just an interned
+Symbol + Span (i.e. an interned string + hygiene data).
For built-in macros, we use the context:
+SyntaxContext::empty().apply_mark(expn_id), and such macros are
+considered to be defined at the hierarchy root. We do the same for proc macros because we haven't implemented cross-crate hygiene yet.
If the token had context X before being produced by a macro then after being
+produced by the macro it has context X -> macro_id. Here are some examples:
Example 0:
+macro m() { ident }
+
+m!();
+Here ident which initially has context SyntaxContext::root has
+context ROOT -> id(m) after it's produced by m.
Example 1:
+macro m() { macro n() { ident } }
+
+m!();
+n!();
+In this example the ident has context ROOT initially, then ROOT -> id(m)
+after the first expansion, then ROOT -> id(m) -> id(n).
Example 2:
+Note that these chains are not entirely determined by their last element, in
+other words ExpnId is not isomorphic to SyntaxContext.
macro m($i: ident) { macro n() { ($i, bar) } }
+
+m!(foo);
+After all expansions, foo has context ROOT -> id(n) and bar has context
+ROOT -> id(m) -> id(n).
Currently this hierarchy for tracking macro definitions is subject to the +so-called "context transplantation hack". Modern (i.e. experimental) +macros have stronger hygiene than the legacy "Macros By Example" (MBE) +system which can result in weird interactions between the two. The hack is +intended to make things "just work" for now.
+The Call-site Hierarchy
+The third and final hierarchy tracks the location of macro invocations.
+In this hierarchy ExpnData::call_site is the child -> parent
+link.
Here is an example:
+macro bar($i: ident) { $i }
+macro foo($i: ident) { $i }
+
+foo!(bar!(baz));
+For the baz AST node in the final output, the expansion-order hierarchy is
+ROOT -> id(foo) -> id(bar) -> baz, while the call-site hierarchy is ROOT -> baz.
Macro Backtraces
+Macro backtraces are implemented in rustc_span using the hygiene machinery
+in rustc_span::hygiene.
Producing Macro Output
+Above, we saw how the output of a macro is integrated into the AST for a crate, +and we also saw how the hygiene data for a crate is generated. But how do we +actually produce the output of a macro? It depends on the type of macro.
+There are two types of macros in Rust:
+-
+
macro_rules!macros (a.k.a. "Macros By Example" (MBE)), and,
+- procedural macros (proc macros); including custom derives. +
During the parsing phase, the normal Rust parser will set aside the contents of +macros and their invocations. Later, macros are expanded using these +portions of the code.
+Some important data structures/interfaces here:
+-
+
SyntaxExtension- a lowered macro representation, contains its expander +function, which transforms aTokenStreamor AST into another +TokenStreamor AST + some additional data like stability, or a list of +unstable features allowed inside the macro.
+SyntaxExtensionKind- expander functions may have several different +signatures (take one token stream, or two, or a piece of AST, etc). This is +anenumthat lists them.
+BangProcMacro/TTMacroExpander/AttrProcMacro/MultiItemModifier- +traits representing the expander function signatures.
+
Macros By Example
+MBEs have their own parser distinct from the Rust parser. When macros are
+expanded, we may invoke the MBE parser to parse and expand a macro. The
+MBE parser, in turn, may call the Rust parser when it needs to bind a
+metavariable (e.g. $my_expr) while parsing the contents of a macro
+invocation. The code for macro expansion is in
+compiler/rustc_expand/src/mbe/.
Example
+macro_rules! printer {
+ (print $mvar:ident) => {
+ println!("{}", $mvar);
+ };
+ (print twice $mvar:ident) => {
+ println!("{}", $mvar);
+ println!("{}", $mvar);
+ };
+}
+Here $mvar is called a metavariable. Unlike normal variables, rather than
+binding to a value at runtime, a metavariable binds at compile time to a
+tree of tokens. A token is a single "unit" of the grammar, such as an
+identifier (e.g. foo) or punctuation (e.g. =>). There are also other
+special tokens, such as EOF, which its self indicates that there are no more
+tokens. There are token trees resulting from the paired parentheses-like
+characters ((...), [...], and {...}) – they include the open and
+close and all the tokens in between (Rust requires that parentheses-like
+characters be balanced). Having macro expansion operate on token streams
+rather than the raw bytes of a source-file abstracts away a lot of complexity.
+The macro expander (and much of the rest of the compiler) doesn't consider
+the exact line and column of some syntactic construct in the code; it considers
+which constructs are used in the code. Using tokens allows us to care about
+what without worrying about where. For more information about tokens, see
+the Parsing chapter of this book.
printer!(print foo); // `foo` is a variable
+The process of expanding the macro invocation into the syntax tree
+println!("{}", foo) and then expanding the syntax tree into a call to
+Display::fmt is one common example of macro expansion.
The MBE parser
+There are two parts to MBE expansion done by the macro parser:
+-
+
- parsing the definition, and, +
- parsing the invocations. +
We think of the MBE parser as a nondeterministic finite automaton (NFA) based
+regex parser since it uses an algorithm similar in spirit to the Earley
+parsing algorithm. The macro
+parser is defined in
+compiler/rustc_expand/src/mbe/macro_parser.rs.
The interface of the macro parser is as follows (this is slightly simplified):
+fn parse_tt(
+ &mut self,
+ parser: &mut Cow<'_, Parser<'_>>,
+ matcher: &[MatcherLoc]
+) -> ParseResult
+We use these items in macro parser:
+-
+
- a
parservariable is a reference to the state of a normal Rust parser, +including the token stream and parsing session. The token stream is what we +are about to ask the MBE parser to parse. We will consume the raw stream of +tokens and output a binding of metavariables to corresponding token trees. +The parsing session can be used to report parser errors.
+ - a
matchervariable is a sequence ofMatcherLocs that we want to match +the token stream against. They're converted from token trees before matching.
+
In the analogy of a regex parser, the token stream is the input and we are
+matching it against the pattern defined by matcher. Using our examples, the
+token stream could be the stream of tokens containing the inside of the example
+invocation print foo, while matcher might be the sequence of token (trees)
+print $mvar:ident.
The output of the parser is a ParseResult, which indicates which of
+three cases has occurred:
-
+
- Success: the token stream matches the given matcher and we have produced a +binding from metavariables to the corresponding token trees. +
- Failure: the token stream does not match matcher and results in an error +message such as "No rule expected token ...". +
- Error: some fatal error has occurred in the parser. For example, this +happens if there is more than one pattern match, since that indicates the +macro is ambiguous. +
The full interface is defined here.
+The macro parser does pretty much exactly the same as a normal regex parser
+with one exception: in order to parse different types of metavariables, such as
+ident, block, expr, etc., the macro parser must call back to the normal
+Rust parser. Both the definition and invocation of macros are parsed using
+the parser in a process which is non-intuitively self-referential.
The code to parse macro definitions is in
+compiler/rustc_expand/src/mbe/macro_rules.rs. It defines the
+pattern for matching a macro definition as $( $lhs:tt => $rhs:tt );+. In
+other words, a macro_rules definition should have in its body at least one
+occurrence of a token tree followed by => followed by another token tree.
+When the compiler comes to a macro_rules definition, it uses this pattern to
+match the two token trees per the rules of the definition of the macro, thereby
+utilizing the macro parser itself. In our example definition, the
+metavariable $lhs would match the patterns of both arms: (print $mvar:ident) and (print twice $mvar:ident). And $rhs would match the
+bodies of both arms: { println!("{}", $mvar); } and { println!("{}", $mvar); println!("{}", $mvar); }. The parser keeps this knowledge around for when it
+needs to expand a macro invocation.
When the compiler comes to a macro invocation, it parses that invocation using
+a NFA-based macro parser described above. However, the matcher variable
+used is the first token tree ($lhs) extracted from the arms of the macro
+definition. Using our example, we would try to match the token stream print foo from the invocation against the matchers print $mvar:ident and print twice $mvar:ident that we previously extracted from the definition. The
+algorithm is exactly the same, but when the macro parser comes to a place in the
+current matcher where it needs to match a non-terminal (e.g. $mvar:ident),
+it calls back to the normal Rust parser to get the contents of that
+non-terminal. In this case, the Rust parser would look for an ident token,
+which it finds (foo) and returns to the macro parser. Then, the macro parser
+proceeds in parsing as normal. Also, note that exactly one of the matchers from
+the various arms should match the invocation; if there is more than one match,
+the parse is ambiguous, while if there are no matches at all, there is a syntax
+error.
For more information about the macro parser's implementation, see the comments
+in compiler/rustc_expand/src/mbe/macro_parser.rs.
Procedural Macros
+Procedural macros are also expanded during parsing. However, rather than +having a parser in the compiler, proc macros are implemented as custom, +third-party crates. The compiler will compile the proc macro crate and +specially annotated functions in them (i.e. the proc macro itself), passing +them a stream of tokens. A proc macro can then transform the token stream and +output a new token stream, which is synthesized into the AST.
+The token stream type used by proc macros is stable, so rustc does not
+use it internally. The compiler's (unstable) token stream is defined in
+rustc_ast::tokenstream::TokenStream. This is converted into the
+stable proc_macro::TokenStream and back in
+rustc_expand::proc_macro and rustc_expand::proc_macro_server.
+Since the Rust ABI is currently unstable, we use the C ABI for this conversion.
Custom Derive
+Custom derives are a special type of proc macro.
+Macros By Example and Macros 2.0
+There is an legacy and mostly undocumented effort to improve the MBE system +by giving it more hygiene-related features, better scoping and visibility +rules, etc. Internally this uses the same machinery as today's MBEs with some +additional syntactic sugar and are allowed to be in namespaces.
+ + +
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
diff --git a/mermaid-init.js b/mermaid-init.js
new file mode 100644
index 000000000..313a6e8bc
--- /dev/null
+++ b/mermaid-init.js
@@ -0,0 +1 @@
+mermaid.initialize({startOnLoad:true});
diff --git a/mermaid.min.js b/mermaid.min.js
new file mode 100644
index 000000000..d45942f36
--- /dev/null
+++ b/mermaid.min.js
@@ -0,0 +1,4 @@
+/* MIT Licensed. Copyright (c) 2014 - 2021 Knut Sveidqvist */
+/*! For license information please see https://github.com/mermaid-js/mermaid/blob/8.13.10/LICENSE */
+!function(t,e){"object"==typeof exports&&"object"==typeof module?module.exports=e():"function"==typeof define&&define.amd?define([],e):"object"==typeof exports?exports.mermaid=e():t.mermaid=e()}("undefined"!=typeof self?self:this,(function(){return(()=>{var t={1362:(t,e,n)=>{t=n.nmd(t);var r=function(){var t=function(t,e,n,r){for(n=n||{},r=t.length;r--;n[t[r]]=e);return n},e=[1,6],n=[1,7],r=[1,8],i=[1,9],a=[1,12],o=[1,11],s=[1,15,24],c=[1,19],u=[1,31],l=[1,34],h=[1,32],f=[1,33],d=[1,35],p=[1,36],y=[1,37],g=[1,38],m=[1,41],v=[1,42],b=[1,43],_=[1,44],x=[15,24],w=[1,56],k=[1,57],T=[1,58],E=[1,59],C=[1,60],S=[1,61],A=[15,24,31,38,39,47,50,51,52,53,54,55,60,62],M=[15,24,29,31,38,39,43,47,50,51,52,53,54,55,60,62,77,78,79,80],N=[7,8,9,10,15,18,22,24],D=[47,77,78,79,80],O=[47,54,55,77,78,79,80],B=[47,50,51,52,53,77,78,79,80],L=[15,24,31],I=[1,93],R={trace:function(){},yy:{},symbols_:{error:2,start:3,mermaidDoc:4,direction:5,directive:6,direction_tb:7,direction_bt:8,direction_rl:9,direction_lr:10,graphConfig:11,openDirective:12,typeDirective:13,closeDirective:14,NEWLINE:15,":":16,argDirective:17,open_directive:18,type_directive:19,arg_directive:20,close_directive:21,CLASS_DIAGRAM:22,statements:23,EOF:24,statement:25,className:26,alphaNumToken:27,classLiteralName:28,GENERICTYPE:29,relationStatement:30,LABEL:31,classStatement:32,methodStatement:33,annotationStatement:34,clickStatement:35,cssClassStatement:36,CLASS:37,STYLE_SEPARATOR:38,STRUCT_START:39,members:40,STRUCT_STOP:41,ANNOTATION_START:42,ANNOTATION_END:43,MEMBER:44,SEPARATOR:45,relation:46,STR:47,relationType:48,lineType:49,AGGREGATION:50,EXTENSION:51,COMPOSITION:52,DEPENDENCY:53,LINE:54,DOTTED_LINE:55,CALLBACK:56,LINK:57,LINK_TARGET:58,CLICK:59,CALLBACK_NAME:60,CALLBACK_ARGS:61,HREF:62,CSSCLASS:63,commentToken:64,textToken:65,graphCodeTokens:66,textNoTagsToken:67,TAGSTART:68,TAGEND:69,"==":70,"--":71,PCT:72,DEFAULT:73,SPACE:74,MINUS:75,keywords:76,UNICODE_TEXT:77,NUM:78,ALPHA:79,BQUOTE_STR:80,$accept:0,$end:1},terminals_:{2:"error",7:"direction_tb",8:"direction_bt",9:"direction_rl",10:"direction_lr",15:"NEWLINE",16:":",18:"open_directive",19:"type_directive",20:"arg_directive",21:"close_directive",22:"CLASS_DIAGRAM",24:"EOF",29:"GENERICTYPE",31:"LABEL",37:"CLASS",38:"STYLE_SEPARATOR",39:"STRUCT_START",41:"STRUCT_STOP",42:"ANNOTATION_START",43:"ANNOTATION_END",44:"MEMBER",45:"SEPARATOR",47:"STR",50:"AGGREGATION",51:"EXTENSION",52:"COMPOSITION",53:"DEPENDENCY",54:"LINE",55:"DOTTED_LINE",56:"CALLBACK",57:"LINK",58:"LINK_TARGET",59:"CLICK",60:"CALLBACK_NAME",61:"CALLBACK_ARGS",62:"HREF",63:"CSSCLASS",66:"graphCodeTokens",68:"TAGSTART",69:"TAGEND",70:"==",71:"--",72:"PCT",73:"DEFAULT",74:"SPACE",75:"MINUS",76:"keywords",77:"UNICODE_TEXT",78:"NUM",79:"ALPHA",80:"BQUOTE_STR"},productions_:[0,[3,1],[3,1],[3,2],[5,1],[5,1],[5,1],[5,1],[4,1],[6,4],[6,6],[12,1],[13,1],[17,1],[14,1],[11,4],[23,1],[23,2],[23,3],[26,1],[26,1],[26,2],[26,2],[26,2],[25,1],[25,2],[25,1],[25,1],[25,1],[25,1],[25,1],[25,1],[25,1],[32,2],[32,4],[32,5],[32,7],[34,4],[40,1],[40,2],[33,1],[33,2],[33,1],[33,1],[30,3],[30,4],[30,4],[30,5],[46,3],[46,2],[46,2],[46,1],[48,1],[48,1],[48,1],[48,1],[49,1],[49,1],[35,3],[35,4],[35,3],[35,4],[35,4],[35,5],[35,3],[35,4],[35,4],[35,5],[35,3],[35,4],[35,4],[35,5],[36,3],[64,1],[64,1],[65,1],[65,1],[65,1],[65,1],[65,1],[65,1],[65,1],[67,1],[67,1],[67,1],[67,1],[27,1],[27,1],[27,1],[28,1]],performAction:function(t,e,n,r,i,a,o){var s=a.length-1;switch(i){case 4:r.setDirection("TB");break;case 5:r.setDirection("BT");break;case 6:r.setDirection("RL");break;case 7:r.setDirection("LR");break;case 11:r.parseDirective("%%{","open_directive");break;case 12:r.parseDirective(a[s],"type_directive");break;case 13:a[s]=a[s].trim().replace(/'/g,'"'),r.parseDirective(a[s],"arg_directive");break;case 14:r.parseDirective("}%%","close_directive","class");break;case 19:case 20:this.$=a[s];break;case 21:this.$=a[s-1]+a[s];break;case 22:case 23:this.$=a[s-1]+"~"+a[s];break;case 24:r.addRelation(a[s]);break;case 25:a[s-1].title=r.cleanupLabel(a[s]),r.addRelation(a[s-1]);break;case 33:r.addClass(a[s]);break;case 34:r.addClass(a[s-2]),r.setCssClass(a[s-2],a[s]);break;case 35:r.addClass(a[s-3]),r.addMembers(a[s-3],a[s-1]);break;case 36:r.addClass(a[s-5]),r.setCssClass(a[s-5],a[s-3]),r.addMembers(a[s-5],a[s-1]);break;case 37:r.addAnnotation(a[s],a[s-2]);break;case 38:this.$=[a[s]];break;case 39:a[s].push(a[s-1]),this.$=a[s];break;case 40:case 42:case 43:break;case 41:r.addMember(a[s-1],r.cleanupLabel(a[s]));break;case 44:this.$={id1:a[s-2],id2:a[s],relation:a[s-1],relationTitle1:"none",relationTitle2:"none"};break;case 45:this.$={id1:a[s-3],id2:a[s],relation:a[s-1],relationTitle1:a[s-2],relationTitle2:"none"};break;case 46:this.$={id1:a[s-3],id2:a[s],relation:a[s-2],relationTitle1:"none",relationTitle2:a[s-1]};break;case 47:this.$={id1:a[s-4],id2:a[s],relation:a[s-2],relationTitle1:a[s-3],relationTitle2:a[s-1]};break;case 48:this.$={type1:a[s-2],type2:a[s],lineType:a[s-1]};break;case 49:this.$={type1:"none",type2:a[s],lineType:a[s-1]};break;case 50:this.$={type1:a[s-1],type2:"none",lineType:a[s]};break;case 51:this.$={type1:"none",type2:"none",lineType:a[s]};break;case 52:this.$=r.relationType.AGGREGATION;break;case 53:this.$=r.relationType.EXTENSION;break;case 54:this.$=r.relationType.COMPOSITION;break;case 55:this.$=r.relationType.DEPENDENCY;break;case 56:this.$=r.lineType.LINE;break;case 57:this.$=r.lineType.DOTTED_LINE;break;case 58:case 64:this.$=a[s-2],r.setClickEvent(a[s-1],a[s]);break;case 59:case 65:this.$=a[s-3],r.setClickEvent(a[s-2],a[s-1]),r.setTooltip(a[s-2],a[s]);break;case 60:case 68:this.$=a[s-2],r.setLink(a[s-1],a[s]);break;case 61:case 69:this.$=a[s-3],r.setLink(a[s-2],a[s-1],a[s]);break;case 62:case 70:this.$=a[s-3],r.setLink(a[s-2],a[s-1]),r.setTooltip(a[s-2],a[s]);break;case 63:case 71:this.$=a[s-4],r.setLink(a[s-3],a[s-2],a[s]),r.setTooltip(a[s-3],a[s-1]);break;case 66:this.$=a[s-3],r.setClickEvent(a[s-2],a[s-1],a[s]);break;case 67:this.$=a[s-4],r.setClickEvent(a[s-3],a[s-2],a[s-1]),r.setTooltip(a[s-3],a[s]);break;case 72:r.setCssClass(a[s-1],a[s])}},table:[{3:1,4:2,5:3,6:4,7:e,8:n,9:r,10:i,11:5,12:10,18:a,22:o},{1:[3]},{1:[2,1]},{1:[2,2]},{3:13,4:2,5:3,6:4,7:e,8:n,9:r,10:i,11:5,12:10,18:a,22:o},{1:[2,8]},t(s,[2,4]),t(s,[2,5]),t(s,[2,6]),t(s,[2,7]),{13:14,19:[1,15]},{15:[1,16]},{19:[2,11]},{1:[2,3]},{14:17,16:[1,18],21:c},t([16,21],[2,12]),{5:29,6:28,7:e,8:n,9:r,10:i,12:10,18:a,23:20,25:21,26:30,27:39,28:40,30:22,32:23,33:24,34:25,35:26,36:27,37:u,42:l,44:h,45:f,56:d,57:p,59:y,63:g,77:m,78:v,79:b,80:_},{15:[1,45]},{17:46,20:[1,47]},{15:[2,14]},{24:[1,48]},{15:[1,49],24:[2,16]},t(x,[2,24],{31:[1,50]}),t(x,[2,26]),t(x,[2,27]),t(x,[2,28]),t(x,[2,29]),t(x,[2,30]),t(x,[2,31]),t(x,[2,32]),t(x,[2,40],{46:51,48:54,49:55,31:[1,53],47:[1,52],50:w,51:k,52:T,53:E,54:C,55:S}),{26:62,27:39,28:40,77:m,78:v,79:b,80:_},t(x,[2,42]),t(x,[2,43]),{27:63,77:m,78:v,79:b},{26:64,27:39,28:40,77:m,78:v,79:b,80:_},{26:65,27:39,28:40,77:m,78:v,79:b,80:_},{26:66,27:39,28:40,77:m,78:v,79:b,80:_},{47:[1,67]},t(A,[2,19],{27:39,28:40,26:68,29:[1,69],77:m,78:v,79:b,80:_}),t(A,[2,20],{29:[1,70]}),t(M,[2,86]),t(M,[2,87]),t(M,[2,88]),t([15,24,29,31,38,39,47,50,51,52,53,54,55,60,62],[2,89]),t(N,[2,9]),{14:71,21:c},{21:[2,13]},{1:[2,15]},{5:29,6:28,7:e,8:n,9:r,10:i,12:10,18:a,23:72,24:[2,17],25:21,26:30,27:39,28:40,30:22,32:23,33:24,34:25,35:26,36:27,37:u,42:l,44:h,45:f,56:d,57:p,59:y,63:g,77:m,78:v,79:b,80:_},t(x,[2,25]),{26:73,27:39,28:40,47:[1,74],77:m,78:v,79:b,80:_},{46:75,48:54,49:55,50:w,51:k,52:T,53:E,54:C,55:S},t(x,[2,41]),{49:76,54:C,55:S},t(D,[2,51],{48:77,50:w,51:k,52:T,53:E}),t(O,[2,52]),t(O,[2,53]),t(O,[2,54]),t(O,[2,55]),t(B,[2,56]),t(B,[2,57]),t(x,[2,33],{38:[1,78],39:[1,79]}),{43:[1,80]},{47:[1,81]},{47:[1,82]},{60:[1,83],62:[1,84]},{27:85,77:m,78:v,79:b},t(A,[2,21]),t(A,[2,22]),t(A,[2,23]),{15:[1,86]},{24:[2,18]},t(L,[2,44]),{26:87,27:39,28:40,77:m,78:v,79:b,80:_},{26:88,27:39,28:40,47:[1,89],77:m,78:v,79:b,80:_},t(D,[2,50],{48:90,50:w,51:k,52:T,53:E}),t(D,[2,49]),{27:91,77:m,78:v,79:b},{40:92,44:I},{26:94,27:39,28:40,77:m,78:v,79:b,80:_},t(x,[2,58],{47:[1,95]}),t(x,[2,60],{47:[1,97],58:[1,96]}),t(x,[2,64],{47:[1,98],61:[1,99]}),t(x,[2,68],{47:[1,101],58:[1,100]}),t(x,[2,72]),t(N,[2,10]),t(L,[2,46]),t(L,[2,45]),{26:102,27:39,28:40,77:m,78:v,79:b,80:_},t(D,[2,48]),t(x,[2,34],{39:[1,103]}),{41:[1,104]},{40:105,41:[2,38],44:I},t(x,[2,37]),t(x,[2,59]),t(x,[2,61]),t(x,[2,62],{58:[1,106]}),t(x,[2,65]),t(x,[2,66],{47:[1,107]}),t(x,[2,69]),t(x,[2,70],{58:[1,108]}),t(L,[2,47]),{40:109,44:I},t(x,[2,35]),{41:[2,39]},t(x,[2,63]),t(x,[2,67]),t(x,[2,71]),{41:[1,110]},t(x,[2,36])],defaultActions:{2:[2,1],3:[2,2],5:[2,8],12:[2,11],13:[2,3],19:[2,14],47:[2,13],48:[2,15],72:[2,18],105:[2,39]},parseError:function(t,e){if(!e.recoverable){var n=new Error(t);throw n.hash=e,n}this.trace(t)},parse:function(t){var e=this,n=[0],r=[],i=[null],a=[],o=this.table,s="",c=0,u=0,l=0,h=2,f=1,d=a.slice.call(arguments,1),p=Object.create(this.lexer),y={yy:{}};for(var g in this.yy)Object.prototype.hasOwnProperty.call(this.yy,g)&&(y.yy[g]=this.yy[g]);p.setInput(t,y.yy),y.yy.lexer=p,y.yy.parser=this,void 0===p.yylloc&&(p.yylloc={});var m=p.yylloc;a.push(m);var v=p.options&&p.options.ranges;function b(){var t;return"number"!=typeof(t=r.pop()||p.lex()||f)&&(t instanceof Array&&(t=(r=t).pop()),t=e.symbols_[t]||t),t}"function"==typeof y.yy.parseError?this.parseError=y.yy.parseError:this.parseError=Object.getPrototypeOf(this).parseError;for(var _,x,w,k,T,E,C,S,A,M={};;){if(w=n[n.length-1],this.defaultActions[w]?k=this.defaultActions[w]:(null==_&&(_=b()),k=o[w]&&o[w][_]),void 0===k||!k.length||!k[0]){var N="";for(E in A=[],o[w])this.terminals_[E]&&E>h&&A.push("'"+this.terminals_[E]+"'");N=p.showPosition?"Parse error on line "+(c+1)+":\n"+p.showPosition()+"\nExpecting "+A.join(", ")+", got '"+(this.terminals_[_]||_)+"'":"Parse error on line "+(c+1)+": Unexpected "+(_==f?"end of input":"'"+(this.terminals_[_]||_)+"'"),this.parseError(N,{text:p.match,token:this.terminals_[_]||_,line:p.yylineno,loc:m,expected:A})}if(k[0]instanceof Array&&k.length>1)throw new Error("Parse Error: multiple actions possible at state: "+w+", token: "+_);switch(k[0]){case 1:n.push(_),i.push(p.yytext),a.push(p.yylloc),n.push(k[1]),_=null,x?(_=x,x=null):(u=p.yyleng,s=p.yytext,c=p.yylineno,m=p.yylloc,l>0&&l--);break;case 2:if(C=this.productions_[k[1]][1],M.$=i[i.length-C],M._$={first_line:a[a.length-(C||1)].first_line,last_line:a[a.length-1].last_line,first_column:a[a.length-(C||1)].first_column,last_column:a[a.length-1].last_column},v&&(M._$.range=[a[a.length-(C||1)].range[0],a[a.length-1].range[1]]),void 0!==(T=this.performAction.apply(M,[s,u,c,y.yy,k[1],i,a].concat(d))))return T;C&&(n=n.slice(0,-1*C*2),i=i.slice(0,-1*C),a=a.slice(0,-1*C)),n.push(this.productions_[k[1]][0]),i.push(M.$),a.push(M._$),S=o[n[n.length-2]][n[n.length-1]],n.push(S);break;case 3:return!0}}return!0}},F={EOF:1,parseError:function(t,e){if(!this.yy.parser)throw new Error(t);this.yy.parser.parseError(t,e)},setInput:function(t,e){return this.yy=e||this.yy||{},this._input=t,this._more=this._backtrack=this.done=!1,this.yylineno=this.yyleng=0,this.yytext=this.matched=this.match="",this.conditionStack=["INITIAL"],this.yylloc={first_line:1,first_column:0,last_line:1,last_column:0},this.options.ranges&&(this.yylloc.range=[0,0]),this.offset=0,this},input:function(){var t=this._input[0];return this.yytext+=t,this.yyleng++,this.offset++,this.match+=t,this.matched+=t,t.match(/(?:\r\n?|\n).*/g)?(this.yylineno++,this.yylloc.last_line++):this.yylloc.last_column++,this.options.ranges&&this.yylloc.range[1]++,this._input=this._input.slice(1),t},unput:function(t){var e=t.length,n=t.split(/(?:\r\n?|\n)/g);this._input=t+this._input,this.yytext=this.yytext.substr(0,this.yytext.length-e),this.offset-=e;var r=this.match.split(/(?:\r\n?|\n)/g);this.match=this.match.substr(0,this.match.length-1),this.matched=this.matched.substr(0,this.matched.length-1),n.length-1&&(this.yylineno-=n.length-1);var i=this.yylloc.range;return this.yylloc={first_line:this.yylloc.first_line,last_line:this.yylineno+1,first_column:this.yylloc.first_column,last_column:n?(n.length===r.length?this.yylloc.first_column:0)+r[r.length-n.length].length-n[0].length:this.yylloc.first_column-e},this.options.ranges&&(this.yylloc.range=[i[0],i[0]+this.yyleng-e]),this.yyleng=this.yytext.length,this},more:function(){return this._more=!0,this},reject:function(){return this.options.backtrack_lexer?(this._backtrack=!0,this):this.parseError("Lexical error on line "+(this.yylineno+1)+". You can only invoke reject() in the lexer when the lexer is of the backtracking persuasion (options.backtrack_lexer = true).\n"+this.showPosition(),{text:"",token:null,line:this.yylineno})},less:function(t){this.unput(this.match.slice(t))},pastInput:function(){var t=this.matched.substr(0,this.matched.length-this.match.length);return(t.length>20?"...":"")+t.substr(-20).replace(/\n/g,"")},upcomingInput:function(){var t=this.match;return t.length<20&&(t+=this._input.substr(0,20-t.length)),(t.substr(0,20)+(t.length>20?"...":"")).replace(/\n/g,"")},showPosition:function(){var t=this.pastInput(),e=new Array(t.length+1).join("-");return t+this.upcomingInput()+"\n"+e+"^"},test_match:function(t,e){var n,r,i;if(this.options.backtrack_lexer&&(i={yylineno:this.yylineno,yylloc:{first_line:this.yylloc.first_line,last_line:this.last_line,first_column:this.yylloc.first_column,last_column:this.yylloc.last_column},yytext:this.yytext,match:this.match,matches:this.matches,matched:this.matched,yyleng:this.yyleng,offset:this.offset,_more:this._more,_input:this._input,yy:this.yy,conditionStack:this.conditionStack.slice(0),done:this.done},this.options.ranges&&(i.yylloc.range=this.yylloc.range.slice(0))),(r=t[0].match(/(?:\r\n?|\n).*/g))&&(this.yylineno+=r.length),this.yylloc={first_line:this.yylloc.last_line,last_line:this.yylineno+1,first_column:this.yylloc.last_column,last_column:r?r[r.length-1].length-r[r.length-1].match(/\r?\n?/)[0].length:this.yylloc.last_column+t[0].length},this.yytext+=t[0],this.match+=t[0],this.matches=t,this.yyleng=this.yytext.length,this.options.ranges&&(this.yylloc.range=[this.offset,this.offset+=this.yyleng]),this._more=!1,this._backtrack=!1,this._input=this._input.slice(t[0].length),this.matched+=t[0],n=this.performAction.call(this,this.yy,this,e,this.conditionStack[this.conditionStack.length-1]),this.done&&this._input&&(this.done=!1),n)return n;if(this._backtrack){for(var a in i)this[a]=i[a];return!1}return!1},next:function(){if(this.done)return this.EOF;var t,e,n,r;this._input||(this.done=!0),this._more||(this.yytext="",this.match="");for(var i=this._currentRules(),a=0;a
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+ Example:
+The
+
+
+
+
+ Memory Management in Rustc
+Generally rustc tries to be pretty careful how it manages memory. +The compiler allocates a lot of data structures throughout compilation, +and if we are not careful, it will take a lot of time and space to do so.
+One of the main way the compiler manages this is using arenas and interning.
+Arenas and Interning
+Since A LOT of data structures are created during compilation, for performance
+reasons, we allocate them from a global memory pool.
+Each are allocated once from a long-lived arena.
+This is called arena allocation.
+This system reduces allocations/deallocations of memory.
+It also allows for easy comparison of types (more on types here) for equality:
+for each interned type X, we implemented PartialEq for X,
+so we can just compare pointers.
+The CtxtInterners type contains a bunch of maps of interned types and the arena itself.
Example: ty::TyKind
+Taking the example of ty::TyKind which represents a type in the compiler (you
+can read more here). Each time we want to construct a type, the
+compiler doesn’t naively allocate from the buffer. Instead, we check if that
+type was already constructed. If it was, we just get the same pointer we had
+before, otherwise we make a fresh pointer. With this schema if we want to know
+if two types are the same, all we need to do is compare the pointers which is
+efficient. ty::TyKind should never be constructed on the stack, and it would be unusable
+if done so.
+You always allocate them from this arena and you always intern them so they are
+unique.
At the beginning of the compilation we make a buffer and each time we need to allocate a type we use
+some of this memory buffer. If we run out of space we get another one. The lifetime of that buffer
+is 'tcx. Our types are tied to that lifetime, so when compilation finishes all the memory related
+to that buffer is freed and our 'tcx references would be invalid.
In addition to types, there are a number of other arena-allocated data structures that you can +allocate, and which are found in this module. Here are a few examples:
+-
+
GenericArgs, allocated withmk_args– this will intern a slice of types, often used +to specify the values to be substituted for generics args (e.g.HashMap<i32, u32>would be +represented as a slice&'tcx [tcx.types.i32, tcx.types.u32]).
+TraitRef, typically passed by value – a trait reference consists of a reference to a trait +along with its various type parameters (includingSelf), likei32: Display(here, the def-id +would reference theDisplaytrait, and the args would containi32). Note thatdef-idis +defined and discussed in depth in theAdtDef and DefIdsection.
+Predicatedefines something the trait system has to prove (see traits module).
+
The tcx and how it uses lifetimes
+The typing context (tcx) is the central data structure in the compiler. It is the context that
+you use to perform all manner of queries. The struct TyCtxt defines a reference to this shared
+context:
tcx: TyCtxt<'tcx>
+// ----
+// |
+// arena lifetime
+As you can see, the TyCtxt type takes a lifetime parameter. When you see a reference with a
+lifetime like 'tcx, you know that it refers to arena-allocated data (or data that lives as long as
+the arenas, anyhow).
A Note On Lifetimes
+The Rust compiler is a fairly large program containing lots of big data
+structures (e.g. the Abstract Syntax Tree (AST), High-Level Intermediate
+Representation (HIR), and the type system) and as such, arenas and
+references are heavily relied upon to minimize unnecessary memory use. This
+manifests itself in the way people can plug into the compiler (i.e. the
+driver), preferring a "push"-style API (callbacks) instead
+of the more Rust-ic "pull" style (think the Iterator trait).
Thread-local storage and interning are used a lot through the compiler to reduce
+duplication while also preventing a lot of the ergonomic issues due to many
+pervasive lifetimes. The rustc_middle::ty::tls module is used to access these
+thread-locals, although you should rarely need to touch it.