summaryrefslogtreecommitdiffstats
path: root/src/doc
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-18 02:49:42 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-18 02:49:42 +0000
commit837b550238aa671a591ccf282dddeab29cadb206 (patch)
tree914b6b8862bace72bd3245ca184d374b08d8a672 /src/doc
parentAdding debian version 1.70.0+dfsg2-1. (diff)
downloadrustc-837b550238aa671a591ccf282dddeab29cadb206.tar.xz
rustc-837b550238aa671a591ccf282dddeab29cadb206.zip
Merging upstream version 1.71.1+dfsg1.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'src/doc')
-rw-r--r--src/doc/book/LICENSE-APACHE2
-rw-r--r--src/doc/edition-guide/src/editions/transitioning-an-existing-project-to-a-new-edition.md2
-rw-r--r--src/doc/embedded-book/src/interoperability/c-with-rust.md6
-rw-r--r--src/doc/embedded-book/src/interoperability/index.md51
-rw-r--r--src/doc/embedded-book/src/intro/index.md1
-rw-r--r--src/doc/embedded-book/src/start/exceptions.md4
-rw-r--r--src/doc/embedded-book/src/start/registers.md2
-rw-r--r--src/doc/nomicon/book.toml2
-rw-r--r--src/doc/nomicon/src/intro.md2
-rw-r--r--src/doc/nomicon/src/unbounded-lifetimes.md40
-rw-r--r--src/doc/reference/src/SUMMARY.md1
-rw-r--r--src/doc/reference/src/attributes.md3
-rw-r--r--src/doc/reference/src/attributes/codegen.md2
-rw-r--r--src/doc/reference/src/attributes/debugger.md141
-rw-r--r--src/doc/reference/src/inline-assembly.md2
-rw-r--r--src/doc/reference/src/items/external-blocks.md36
-rw-r--r--src/doc/reference/src/keywords.md1
-rw-r--r--src/doc/reference/src/macros-by-example.md2
-rw-r--r--src/doc/reference/src/procedural-macros.md2
-rw-r--r--src/doc/reference/src/types/impl-trait.md18
-rw-r--r--src/doc/rust-by-example/README.md10
-rw-r--r--src/doc/rust-by-example/src/error/multiple_error_types/reenter_question_mark.md2
-rw-r--r--src/doc/rust-by-example/src/hello/print.md5
-rw-r--r--src/doc/rust-by-example/src/primitives/array.md4
-rw-r--r--src/doc/rustc-dev-guide/src/SUMMARY.md1
-rw-r--r--src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md6
-rw-r--r--src/doc/rustc-dev-guide/src/building/suggested.md27
-rw-r--r--src/doc/rustc-dev-guide/src/getting-started.md4
-rw-r--r--src/doc/rustc-dev-guide/src/hir-debugging.md2
-rw-r--r--src/doc/rustc-dev-guide/src/mir/optimizations.md2
-rw-r--r--src/doc/rustc-dev-guide/src/solve/trait-solving.md4
-rw-r--r--src/doc/rustc-dev-guide/src/tests/headers.md5
-rw-r--r--src/doc/rustc-dev-guide/src/tests/suggest-tests.md55
-rw-r--r--src/doc/rustc-dev-guide/src/tests/ui.md3
-rw-r--r--src/doc/rustc/src/SUMMARY.md2
-rw-r--r--src/doc/rustc/src/codegen-options/index.md15
-rw-r--r--src/doc/rustc/src/command-line-arguments.md6
-rw-r--r--src/doc/rustc/src/exploit-mitigations.md17
-rw-r--r--src/doc/rustc/src/images/image3.pngbin72412 -> 19069 bytes
-rw-r--r--src/doc/rustc/src/instrument-coverage.md2
-rw-r--r--src/doc/rustc/src/json.md2
-rw-r--r--src/doc/rustc/src/platform-support.md5
-rw-r--r--src/doc/rustc/src/platform-support/armv7-sony-vita-newlibeabihf.md (renamed from src/doc/rustc/src/platform-support/armv7-sony-vita-eabihf.md)97
-rw-r--r--src/doc/rustc/src/platform-support/armv7-unknown-linux-uclibceabi.md2
-rw-r--r--src/doc/rustc/src/platform-support/esp-idf.md41
-rw-r--r--src/doc/rustc/src/platform-support/loongarch-linux.md4
-rw-r--r--src/doc/rustc/src/platform-support/unknown-uefi.md2
-rw-r--r--src/doc/rustc/src/platform-support/x86_64h-apple-darwin.md57
-rw-r--r--src/doc/rustdoc/src/SUMMARY.md1
-rw-r--r--src/doc/rustdoc/src/how-to-read-rustdoc.md9
-rw-r--r--src/doc/rustdoc/src/how-to-write-documentation.md6
-rw-r--r--src/doc/rustdoc/src/images/collapsed-long-item.pngbin0 -> 17017 bytes
-rw-r--r--src/doc/rustdoc/src/images/collapsed-trait-impls.pngbin0 -> 44225 bytes
-rw-r--r--src/doc/rustdoc/src/lints.md38
-rw-r--r--src/doc/rustdoc/src/read-documentation/in-doc-settings.md64
-rw-r--r--src/doc/rustdoc/src/references.md8
-rw-r--r--src/doc/rustdoc/src/scraped-examples.md4
-rw-r--r--src/doc/rustdoc/src/write-documentation/linking-to-items-by-name.md9
-rw-r--r--src/doc/style-guide/src/principles.md2
-rw-r--r--src/doc/style-guide/src/statements.md37
-rw-r--r--src/doc/style-guide/src/types.md2
-rw-r--r--src/doc/unstable-book/src/compiler-flags/check-cfg.md2
-rw-r--r--src/doc/unstable-book/src/compiler-flags/extern-options.md2
-rw-r--r--src/doc/unstable-book/src/compiler-flags/move-size-limit.md2
-rw-r--r--src/doc/unstable-book/src/compiler-flags/sanitizer.md118
-rw-r--r--src/doc/unstable-book/src/language-features/asm-experimental-arch.md28
-rw-r--r--src/doc/unstable-book/src/language-features/cfi-encoding.md25
-rw-r--r--src/doc/unstable-book/src/language-features/debugger-visualizer.md27
-rw-r--r--src/doc/unstable-book/src/language-features/intrinsics.md2
-rw-r--r--src/doc/unstable-book/src/language-features/raw-dylib.md34
-rw-r--r--src/doc/unstable-book/src/language-features/transparent-unions.md2
-rw-r--r--src/doc/unstable-book/src/library-features/libstd-thread-internals.md5
72 files changed, 899 insertions, 230 deletions
diff --git a/src/doc/book/LICENSE-APACHE b/src/doc/book/LICENSE-APACHE
index 16fe87b06..38634daab 100644
--- a/src/doc/book/LICENSE-APACHE
+++ b/src/doc/book/LICENSE-APACHE
@@ -186,7 +186,7 @@ APPENDIX: How to apply the Apache License to your work.
same "printed page" as the copyright notice for easier
identification within third-party archives.
-Copyright [yyyy] [name of copyright owner]
+Copyright 2010 The Rust Project Developers
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
diff --git a/src/doc/edition-guide/src/editions/transitioning-an-existing-project-to-a-new-edition.md b/src/doc/edition-guide/src/editions/transitioning-an-existing-project-to-a-new-edition.md
index 434352943..d4ebd23bf 100644
--- a/src/doc/edition-guide/src/editions/transitioning-an-existing-project-to-a-new-edition.md
+++ b/src/doc/edition-guide/src/editions/transitioning-an-existing-project-to-a-new-edition.md
@@ -13,7 +13,7 @@ The following sections dig into the details of these steps, and some of the issu
> It's our intention that the migration to new editions is as smooth an
> experience as possible. If it's difficult for you to upgrade to the latest edition,
> we consider that a bug. If you run into problems with this process, please
-> [file a bug](https://github.com/rust-lang/rust/issues/new/choose). Thank you!
+> [file a bug report](https://github.com/rust-lang/rust/issues/new/choose). Thank you!
## Starting the migration
diff --git a/src/doc/embedded-book/src/interoperability/c-with-rust.md b/src/doc/embedded-book/src/interoperability/c-with-rust.md
index 6bec3bd87..9c56c6aaa 100644
--- a/src/doc/embedded-book/src/interoperability/c-with-rust.md
+++ b/src/doc/embedded-book/src/interoperability/c-with-rust.md
@@ -127,7 +127,9 @@ In the simplest case of compiling a single C file as a dependency to a static li
```rust,ignore
fn main() {
cc::Build::new()
- .file("foo.c")
- .compile("libfoo.a");
+ .file("src/foo.c")
+ .compile("foo");
}
```
+
+The `build.rs` is placed at the root of the package. Then `cargo build` will compile and execute it before the build of the package. A static archive named `libfoo.a` is generated and placed in the `target` directory.
diff --git a/src/doc/embedded-book/src/interoperability/index.md b/src/doc/embedded-book/src/interoperability/index.md
index 4ff5fd9df..267bd6788 100644
--- a/src/doc/embedded-book/src/interoperability/index.md
+++ b/src/doc/embedded-book/src/interoperability/index.md
@@ -2,40 +2,42 @@
Interoperability between Rust and C code is always dependent
on transforming data between the two languages.
-For this purposes there are two dedicated modules
+For this purpose, there is a dedicated module
in the `stdlib` called
-[`std::ffi`](https://doc.rust-lang.org/std/ffi/index.html) and
-[`std::os::raw`](https://doc.rust-lang.org/std/os/raw/index.html).
+[`std::ffi`](https://doc.rust-lang.org/std/ffi/index.html).
-`std::os::raw` deals with low-level primitive types that can
-be converted implicitly by the compiler
-because the memory layout between Rust and C
-is similar enough or the same.
+`std::ffi` provides type definitions for C primitive types,
+such as `char`, `int`, and `long`.
+It also provides some utility for converting more complex
+types such as strings, mapping both `&str` and `String`
+to C types that are easier and safer to handle.
-`std::ffi` provides some utility for converting more complex
-types such as Strings, mapping both `&str` and `String`
-to C-types that are easier and safer to handle.
-
-Neither of these modules are available in `core`, but you can find a `#![no_std]`
-compatible version of `std::ffi::{CStr,CString}` in the [`cstr_core`] crate, and
-most of the `std::os::raw` types in the [`cty`] crate.
+As of Rust 1.30,
+functionalities of `std::ffi` are available
+in either `core::ffi` or `alloc::ffi`
+depending on whether or not memory allocation is involved.
+The [`cty`] crate and the [`cstr_core`] crate
+also offer similar functionalities.
[`cstr_core`]: https://crates.io/crates/cstr_core
[`cty`]: https://crates.io/crates/cty
-| Rust type | Intermediate | C type |
-|------------|--------------|--------------|
-| String | CString | *char |
-| &str | CStr | *const char |
-| () | c_void | void |
-| u32 or u64 | c_uint | unsigned int |
-| etc | ... | ... |
+| Rust type | Intermediate | C type |
+|----------------|--------------|----------------|
+| `String` | `CString` | `char *` |
+| `&str` | `CStr` | `const char *` |
+| `()` | `c_void` | `void` |
+| `u32` or `u64` | `c_uint` | `unsigned int` |
+| etc | ... | ... |
-As mentioned above, primitive types can be converted
-by the compiler implicitly.
+A value of a C primitive type can be used
+as one of the corresponding Rust type and vice versa,
+since the former is simply a type alias of the latter.
+For example, the following code compiles on platforms
+where `unsigned int` is 32-bit long.
```rust,ignore
-unsafe fn foo(num: u32) {
+fn foo(num: u32) {
let c_num: c_uint = num;
let r_num: u32 = c_num;
}
@@ -51,7 +53,6 @@ We are collecting examples and use cases for this on our issue tracker in
[issue #61]: https://github.com/rust-embedded/book/issues/61
-
## Interoperability with RTOSs
Integrating Rust with an RTOS such as FreeRTOS or ChibiOS is still a work in
diff --git a/src/doc/embedded-book/src/intro/index.md b/src/doc/embedded-book/src/intro/index.md
index 7a600fee0..272c2428f 100644
--- a/src/doc/embedded-book/src/intro/index.md
+++ b/src/doc/embedded-book/src/intro/index.md
@@ -60,6 +60,7 @@ If you are unfamiliar with anything mentioned above or if you want more informat
| Rust, Embedded | [Embedded Rust Bookshelf](https://docs.rust-embedded.org) | Here you can find several other resources provided by Rust's Embedded Working Group. |
| Rust, Embedded | [Embedonomicon](https://docs.rust-embedded.org/embedonomicon/) | The nitty gritty details when doing embedded programming in Rust. |
| Rust, Embedded | [embedded FAQ](https://docs.rust-embedded.org/faq.html) | Frequently asked questions about Rust in an embedded context. |
+| Rust, Embedded | [Comprehensive Rust 🦀: Bare Metal](https://google.github.io/comprehensive-rust/bare-metal.html) | Teaching material for a 1-day class on bare-metal Rust development |
| Interrupts | [Interrupt](https://en.wikipedia.org/wiki/Interrupt) | - |
| Memory-mapped IO/Peripherals | [Memory-mapped I/O](https://en.wikipedia.org/wiki/Memory-mapped_I/O) | - |
| SPI, UART, RS232, USB, I2C, TTL | [Stack Exchange about SPI, UART, and other interfaces](https://electronics.stackexchange.com/questions/37814/usart-uart-rs232-usb-spi-i2c-ttl-etc-what-are-all-of-these-and-how-do-th) | - |
diff --git a/src/doc/embedded-book/src/start/exceptions.md b/src/doc/embedded-book/src/start/exceptions.md
index b15717da9..bd9b85b76 100644
--- a/src/doc/embedded-book/src/start/exceptions.md
+++ b/src/doc/embedded-book/src/start/exceptions.md
@@ -50,7 +50,7 @@ possible.
> Note that the `exception` attribute transforms definitions of static variables
> inside the function by wrapping them into `unsafe` blocks and providing us
> with new appropriate variables of type `&mut` of the same name.
-> Thus we can derefence the reference via `*` to access the values of the variables without
+> Thus we can dereference the reference via `*` to access the values of the variables without
> needing to wrap them in an `unsafe` block.
## A complete example
@@ -258,7 +258,7 @@ ResetTrampoline:
800094c: b #-0x4 <ResetTrampoline+0xa>
```
-You can lookup the value of the program counter `0x0800094a` in the dissassembly.
+You can lookup the value of the program counter `0x0800094a` in the disassembly.
You'll see that a load operation (`ldr r0, [r0]` ) caused the exception.
The `r0` field of `ExceptionFrame` will tell you the value of register `r0`
was `0x3fff_fffe` at that time.
diff --git a/src/doc/embedded-book/src/start/registers.md b/src/doc/embedded-book/src/start/registers.md
index fe184792c..2d4a8e85b 100644
--- a/src/doc/embedded-book/src/start/registers.md
+++ b/src/doc/embedded-book/src/start/registers.md
@@ -134,7 +134,7 @@ pwm0.enable.write(temp); // Uh oh! Wrong variable!
## Using a HAL crate
-The HAL crate for a chip typically works by implementing a custom Trait for the raw structures exposed by the PAC. Often this trait will define a function called `constrain()` for single peripherals or `split()` for things like GPIO ports with multiple pins. This function will consume the underlying raw peripheral structure and return a new object with a higher-level API. This API may also do things like have the Serial port `new` function require a borrow on some `Clock` structure, which can only be generated by calling the function which configures the PLLs and sets up all the clock frequencies. In this way, it is statically impossible to create a Serial port object without first having configured the clock rates, or for the Serial port object to mis-convert the baud rate into clock ticks. Some crates even define special traits for the states each GPIO pin can be in, requiring the user to put a pin into the correct state (say, by selecting the appropriate Alternate Function Mode) before passing the pin into Peripheral. All with no run-time cost!
+The HAL crate for a chip typically works by implementing a custom Trait for the raw structures exposed by the PAC. Often this trait will define a function called `constrain()` for single peripherals or `split()` for things like GPIO ports with multiple pins. This function will consume the underlying raw peripheral structure and return a new object with a higher-level API. This API may also do things like have the Serial port `new` function require a borrow on some `Clock` structure, which can only be generated by calling the function which configures the PLLs and sets up all the clock frequencies. In this way, it is statically impossible to create a Serial port object without first having configured the clock rates, or for the Serial port object to misconvert the baud rate into clock ticks. Some crates even define special traits for the states each GPIO pin can be in, requiring the user to put a pin into the correct state (say, by selecting the appropriate Alternate Function Mode) before passing the pin into Peripheral. All with no run-time cost!
Let's see an example:
diff --git a/src/doc/nomicon/book.toml b/src/doc/nomicon/book.toml
index a2011c61f..693aca4a4 100644
--- a/src/doc/nomicon/book.toml
+++ b/src/doc/nomicon/book.toml
@@ -32,4 +32,4 @@ git-repository-url = "https://github.com/rust-lang/nomicon"
"./arc.html" = "./arc-mutex/arc.html"
[rust]
-edition = "2018"
+edition = "2021"
diff --git a/src/doc/nomicon/src/intro.md b/src/doc/nomicon/src/intro.md
index 4e77ffafe..323c0ceb3 100644
--- a/src/doc/nomicon/src/intro.md
+++ b/src/doc/nomicon/src/intro.md
@@ -39,7 +39,7 @@ Topics that are within the scope of this book include: the meaning of (un)safety
The Rustonomicon is not a place to exhaustively describe the semantics and guarantees of every single API in the standard library, nor is it a place to exhaustively describe every feature of Rust.
-Unless otherwise noted, Rust code in this book uses the Rust 2018 edition.
+Unless otherwise noted, Rust code in this book uses the Rust 2021 edition.
[trpl]: ../book/index.html
[ref]: ../reference/index.html
diff --git a/src/doc/nomicon/src/unbounded-lifetimes.md b/src/doc/nomicon/src/unbounded-lifetimes.md
index 03febd6ad..9ca2a2f2e 100644
--- a/src/doc/nomicon/src/unbounded-lifetimes.md
+++ b/src/doc/nomicon/src/unbounded-lifetimes.md
@@ -1,13 +1,13 @@
# Unbounded Lifetimes
Unsafe code can often end up producing references or lifetimes out of thin air.
-Such lifetimes come into the world as *unbounded*. The most common source of this
-is dereferencing a raw pointer, which produces a reference with an unbounded lifetime.
-Such a lifetime becomes as big as context demands. This is in fact more powerful
-than simply becoming `'static`, because for instance `&'static &'a T`
-will fail to typecheck, but the unbound lifetime will perfectly mold into
-`&'a &'a T` as needed. However for most intents and purposes, such an unbounded
-lifetime can be regarded as `'static`.
+Such lifetimes come into the world as *unbounded*. The most common source of
+this is taking a reference to a dereferenced raw pointer, which produces a
+reference with an unbounded lifetime. Such a lifetime becomes as big as context
+demands. This is in fact more powerful than simply becoming `'static`, because
+for instance `&'static &'a T` will fail to typecheck, but the unbound lifetime
+will perfectly mold into `&'a &'a T` as needed. However for most intents and
+purposes, such an unbounded lifetime can be regarded as `'static`.
Almost no reference is `'static`, so this is probably wrong. `transmute` and
`transmute_copy` are the two other primary offenders. One should endeavor to
@@ -17,17 +17,25 @@ boundaries.
Given a function, any output lifetimes that don't derive from inputs are
unbounded. For instance:
-<!-- ignore: simplified code -->
-```rust,ignore
-fn get_str<'a>() -> &'a str;
+<!-- no_run: This example exhibits undefined behavior. -->
+```rust,no_run
+fn get_str<'a>(s: *const String) -> &'a str {
+ unsafe { &*s }
+}
+
+fn main() {
+ let soon_dropped = String::from("hello");
+ let dangling = get_str(&soon_dropped);
+ drop(soon_dropped);
+ println!("Invalid str: {}", dangling); // Invalid str: gӚ_`
+}
```
-will produce an `&str` with an unbounded lifetime. The easiest way to avoid
-unbounded lifetimes is to use lifetime elision at the function boundary.
-If an output lifetime is elided, then it *must* be bounded by an input lifetime.
-Of course it might be bounded by the *wrong* lifetime, but this will usually
-just cause a compiler error, rather than allow memory safety to be trivially
-violated.
+The easiest way to avoid unbounded lifetimes is to use lifetime elision at the
+function boundary. If an output lifetime is elided, then it *must* be bounded by
+an input lifetime. Of course it might be bounded by the *wrong* lifetime, but
+this will usually just cause a compiler error, rather than allow memory safety
+to be trivially violated.
Within a function, bounding lifetimes is more error-prone. The safest and easiest
way to bound a lifetime is to return it from a function with a bound lifetime.
diff --git a/src/doc/reference/src/SUMMARY.md b/src/doc/reference/src/SUMMARY.md
index 4d9cc1d76..2b17bf45d 100644
--- a/src/doc/reference/src/SUMMARY.md
+++ b/src/doc/reference/src/SUMMARY.md
@@ -44,6 +44,7 @@
- [Code generation](attributes/codegen.md)
- [Limits](attributes/limits.md)
- [Type System](attributes/type_system.md)
+ - [Debugger](attributes/debugger.md)
- [Statements and expressions](statements-and-expressions.md)
- [Statements](statements.md)
diff --git a/src/doc/reference/src/attributes.md b/src/doc/reference/src/attributes.md
index 5d619c990..92ce1cd09 100644
--- a/src/doc/reference/src/attributes.md
+++ b/src/doc/reference/src/attributes.md
@@ -271,6 +271,8 @@ The following is an index of all built-in attributes.
- Type System
- [`non_exhaustive`] — Indicate that a type will have more fields/variants
added in future.
+- Debugger
+ - [`debugger_visualizer`] — Embeds a file that specifies debugger output for a type.
[Doc comments]: comments.md#doc-comments
[ECMA-334]: https://www.ecma-international.org/publications/standards/Ecma-334.htm
@@ -291,6 +293,7 @@ The following is an index of all built-in attributes.
[`cold`]: attributes/codegen.md#the-cold-attribute
[`crate_name`]: crates-and-source-files.md#the-crate_name-attribute
[`crate_type`]: linkage.md
+[`debugger_visualizer`]: attributes/debugger.md#the-debugger_visualizer-attribute
[`deny`]: attributes/diagnostics.md#lint-check-attributes
[`deprecated`]: attributes/diagnostics.md#the-deprecated-attribute
[`derive`]: attributes/derive.md
diff --git a/src/doc/reference/src/attributes/codegen.md b/src/doc/reference/src/attributes/codegen.md
index ab59cd8e7..8629e835d 100644
--- a/src/doc/reference/src/attributes/codegen.md
+++ b/src/doc/reference/src/attributes/codegen.md
@@ -89,6 +89,7 @@ Feature | Implicitly Enables | Description
`bmi1` | | [BMI1] — Bit Manipulation Instruction Sets
`bmi2` | | [BMI2] — Bit Manipulation Instruction Sets 2
`cmpxchg16b`| | [`cmpxchg16b`] - Compares and exchange 16 bytes (128 bits) of data atomically
+`f16c` | `avx` | [F16C] — 16-bit floating point conversion instructions
`fma` | `avx` | [FMA3] — Three-operand fused multiply-add
`fxsr` | | [`fxsave`] and [`fxrstor`] — Save and restore x87 FPU, MMX Technology, and SSE State
`lzcnt` | | [`lzcnt`] — Leading zeros count
@@ -118,6 +119,7 @@ Feature | Implicitly Enables | Description
[BMI1]: https://en.wikipedia.org/wiki/Bit_Manipulation_Instruction_Sets
[BMI2]: https://en.wikipedia.org/wiki/Bit_Manipulation_Instruction_Sets#BMI2
[`cmpxchg16b`]: https://www.felixcloutier.com/x86/cmpxchg8b:cmpxchg16b
+[F16C]: https://en.wikipedia.org/wiki/F16C
[FMA3]: https://en.wikipedia.org/wiki/FMA_instruction_set
[`fxsave`]: https://www.felixcloutier.com/x86/fxsave
[`fxrstor`]: https://www.felixcloutier.com/x86/fxrstor
diff --git a/src/doc/reference/src/attributes/debugger.md b/src/doc/reference/src/attributes/debugger.md
new file mode 100644
index 000000000..6ea80221e
--- /dev/null
+++ b/src/doc/reference/src/attributes/debugger.md
@@ -0,0 +1,141 @@
+# Debugger attributes
+
+The following [attributes] are used for enhancing the debugging experience when using third-party debuggers like GDB or WinDbg.
+
+## The `debugger_visualizer` attribute
+
+The *`debugger_visualizer` attribute* can be used to embed a debugger visualizer file into the debug information.
+This enables an improved debugger experience for displaying values in the debugger.
+It uses the [_MetaListNameValueStr_] syntax to specify its inputs, and must be specified as a crate attribute.
+
+### Using `debugger_visualizer` with Natvis
+
+Natvis is an XML-based framework for Microsoft debuggers (such as Visual Studio and WinDbg) that uses declarative rules to customize the display of types.
+For detailed information on the Natvis format, refer to Microsoft's [Natvis documentation].
+
+This attribute only supports embedding Natvis files on `-windows-msvc` targets.
+
+The path to the Natvis file is specified with the `natvis_file` key, which is a path relative to the crate source file:
+
+<!-- ignore: requires external files, and msvc -->
+```rust ignore
+#![debugger_visualizer(natvis_file = "Rectangle.natvis")]
+
+struct FancyRect {
+ x: f32,
+ y: f32,
+ dx: f32,
+ dy: f32,
+}
+
+fn main() {
+ let fancy_rect = FancyRect { x: 10.0, y: 10.0, dx: 5.0, dy: 5.0 };
+ println!("set breakpoint here");
+}
+```
+
+and `Rectangle.natvis` contains:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<AutoVisualizer xmlns="http://schemas.microsoft.com/vstudio/debugger/natvis/2010">
+ <Type Name="foo::FancyRect">
+ <DisplayString>({x},{y}) + ({dx}, {dy})</DisplayString>
+ <Expand>
+ <Synthetic Name="LowerLeft">
+ <DisplayString>({x}, {y})</DisplayString>
+ </Synthetic>
+ <Synthetic Name="UpperLeft">
+ <DisplayString>({x}, {y + dy})</DisplayString>
+ </Synthetic>
+ <Synthetic Name="UpperRight">
+ <DisplayString>({x + dx}, {y + dy})</DisplayString>
+ </Synthetic>
+ <Synthetic Name="LowerRight">
+ <DisplayString>({x + dx}, {y})</DisplayString>
+ </Synthetic>
+ </Expand>
+ </Type>
+</AutoVisualizer>
+```
+
+When viewed under WinDbg, the `fancy_rect` variable would be shown as follows:
+
+```text
+> Variables:
+ > fancy_rect: (10.0, 10.0) + (5.0, 5.0)
+ > LowerLeft: (10.0, 10.0)
+ > UpperLeft: (10.0, 15.0)
+ > UpperRight: (15.0, 15.0)
+ > LowerRight: (15.0, 10.0)
+```
+
+### Using `debugger_visualizer` with GDB
+
+GDB supports the use of a structured Python script, called a *pretty printer*, that describes how a type should be visualized in the debugger view.
+For detailed information on pretty printers, refer to GDB's [pretty printing documentation].
+
+Embedded pretty printers are not automatically loaded when debugging a binary under GDB.
+There are two ways to enable auto-loading embedded pretty printers:
+1. Launch GDB with extra arguments to explicitly add a directory or binary to the auto-load safe path: `gdb -iex "add-auto-load-safe-path safe-path path/to/binary" path/to/binary`
+ For more information, see GDB's [auto-loading documentation].
+1. Create a file named `gdbinit` under `$HOME/.config/gdb` (you may need to create the directory if it doesn't already exist). Add the following line to that file: `add-auto-load-safe-path path/to/binary`.
+
+These scripts are embedded using the `gdb_script_file` key, which is a path relative to the crate source file.
+
+<!-- ignore: requires external files -->
+```rust ignore
+#![debugger_visualizer(gdb_script_file = "printer.py")]
+
+struct Person {
+ name: String,
+ age: i32,
+}
+
+fn main() {
+ let bob = Person { name: String::from("Bob"), age: 10 };
+ println!("set breakpoint here");
+}
+```
+
+and `printer.py` contains:
+
+```python
+import gdb
+
+class PersonPrinter:
+ "Print a Person"
+
+ def __init__(self, val):
+ self.val = val
+ self.name = val["name"]
+ self.age = int(val["age"])
+
+ def to_string(self):
+ return "{} is {} years old.".format(self.name, self.age)
+
+def lookup(val):
+ lookup_tag = val.type.tag
+ if lookup_tag is None:
+ return None
+ if "foo::Person" == lookup_tag:
+ return PersonPrinter(val)
+
+ return None
+
+gdb.current_objfile().pretty_printers.append(lookup)
+```
+
+When the crate's debug executable is passed into GDB[^rust-gdb], `print bob` will display:
+
+```text
+"Bob" is 10 years old.
+```
+
+[^rust-gdb]: Note: This assumes you are using the `rust-gdb` script which configures pretty-printers for standard library types like `String`.
+
+[auto-loading documentation]: https://sourceware.org/gdb/onlinedocs/gdb/Auto_002dloading-safe-path.html
+[attributes]: ../attributes.md
+[Natvis documentation]: https://docs.microsoft.com/en-us/visualstudio/debugger/create-custom-views-of-native-objects
+[pretty printing documentation]: https://sourceware.org/gdb/onlinedocs/gdb/Pretty-Printing.html
+[_MetaListNameValueStr_]: ../attributes.md#meta-item-attribute-syntax
diff --git a/src/doc/reference/src/inline-assembly.md b/src/doc/reference/src/inline-assembly.md
index a12f495ff..6c23d592c 100644
--- a/src/doc/reference/src/inline-assembly.md
+++ b/src/doc/reference/src/inline-assembly.md
@@ -17,6 +17,7 @@ The compiler will emit an error if `asm!` is used on an unsupported target.
## Example
```rust
+# #[cfg(target_arch = "x86_64")] {
use std::arch::asm;
// Multiply x by 6 using shifts and adds
@@ -32,6 +33,7 @@ unsafe {
);
}
assert_eq!(x, 4 * 6);
+# }
```
## Syntax
diff --git a/src/doc/reference/src/items/external-blocks.md b/src/doc/reference/src/items/external-blocks.md
index ce2190829..25ae37bc3 100644
--- a/src/doc/reference/src/items/external-blocks.md
+++ b/src/doc/reference/src/items/external-blocks.md
@@ -231,9 +231,38 @@ resolution logic to find that import library. Alternatively, specifying
`kind = "raw-dylib"` instructs the compiler to generate an import library
during compilation and provide that to the linker instead.
-`raw-dylib` is only supported on Windows and not supported on 32-bit x86
-(`target_arch="x86"`). Using it when targeting other platforms or
-x86 on Windows will result in a compiler error.
+`raw-dylib` is only supported on Windows. Using it when targeting other
+platforms will result in a compiler error.
+
+#### The `import_name_type` key
+
+On x86 Windows, names of functions are "decorated" (i.e., have a specific prefix
+and/or suffix added) to indicate their calling convention. For example, a
+`stdcall` calling convention function with the name `fn1` that has no arguments
+would be decorated as `_fn1@0`. However, the [PE Format] does also permit names
+to have no prefix or be undecorated. Additionally, the MSVC and GNU toolchains
+use different decorations for the same calling conventions which means, by
+default, some Win32 functions cannot be called using the `raw-dylib` link kind
+via the GNU toolchain.
+
+To allow for these differences, when using the `raw-dylib` link kind you may
+also specify the `import_name_type` key with one of the following values to
+change how functions are named in the generated import library:
+
+* `decorated`: The function name will be fully-decorated using the MSVC
+ toolchain format.
+* `noprefix`: The function name will be decorated using the MSVC toolchain
+ format, but skipping the leading `?`, `@`, or optionally `_`.
+* `undecorated`: The function name will not be decorated.
+
+If the `import_name_type` key is not specified, then the function name will be
+fully-decorated using the target toolchain's format.
+
+Variables are never decorated and so the `import_name_type` key has no effect on
+how they are named in the generated import library.
+
+The `import_name_type` key is only supported on x86 Windows. Using it when
+targeting other platforms will result in a compiler error.
### The `link_name` attribute
@@ -308,3 +337,4 @@ restrictions as [regular function parameters].
[`whole-archive` documentation for rustc]: ../../rustc/command-line-arguments.html#linking-modifiers-whole-archive
[`verbatim` documentation for rustc]: ../../rustc/command-line-arguments.html#linking-modifiers-verbatim
[`dylib` versus `raw-dylib`]: #dylib-versus-raw-dylib
+[PE Format]: https://learn.microsoft.com/windows/win32/debug/pe-format#import-name-type
diff --git a/src/doc/reference/src/keywords.md b/src/doc/reference/src/keywords.md
index 67f1089d8..1855a35d0 100644
--- a/src/doc/reference/src/keywords.md
+++ b/src/doc/reference/src/keywords.md
@@ -111,6 +111,7 @@ is possible to declare a variable or method with the name `union`.
Beginning in the 2018 edition, `dyn` has been promoted to a strict keyword.
> **<sup>Lexer</sup>**\
+> KW_MACRO_RULES : `macro_rules`\
> KW_UNION : `union`\
> KW_STATICLIFETIME : `'static`
>
diff --git a/src/doc/reference/src/macros-by-example.md b/src/doc/reference/src/macros-by-example.md
index cd9dc3402..51aa919fc 100644
--- a/src/doc/reference/src/macros-by-example.md
+++ b/src/doc/reference/src/macros-by-example.md
@@ -166,7 +166,7 @@ The repetition operators are:
- `*` — indicates any number of repetitions.
- `+` — indicates any number but at least one.
-- `?` — indicates an optional fragment with zero or one occurrences.
+- `?` — indicates an optional fragment with zero or one occurrence.
Since `?` represents at most one occurrence, it cannot be used with a
separator.
diff --git a/src/doc/reference/src/procedural-macros.md b/src/doc/reference/src/procedural-macros.md
index 31f029a63..7d69ab72d 100644
--- a/src/doc/reference/src/procedural-macros.md
+++ b/src/doc/reference/src/procedural-macros.md
@@ -251,7 +251,7 @@ use my_macro::show_streams;
#[show_streams]
fn invoke1() {}
// out: attr: ""
-// out: item: "fn invoke1() { }"
+// out: item: "fn invoke1() {}"
// Example: Attribute with input
#[show_streams(bar)]
diff --git a/src/doc/reference/src/types/impl-trait.md b/src/doc/reference/src/types/impl-trait.md
index 413f999f8..af900408e 100644
--- a/src/doc/reference/src/types/impl-trait.md
+++ b/src/doc/reference/src/types/impl-trait.md
@@ -31,15 +31,15 @@ The caller must provide a type that satisfies the bounds declared by the anonymo
For example, these two forms are almost equivalent:
-```rust,ignore
+```rust
trait Trait {}
// generic type parameter
-fn foo<T: Trait>(arg: T) {
+fn with_generic_type<T: Trait>(arg: T) {
}
// impl Trait in argument position
-fn foo(arg: impl Trait) {
+fn with_impl_trait(arg: impl Trait) {
}
```
@@ -96,16 +96,24 @@ With `impl Trait`, unlike with a generic type parameter, the function chooses th
The function:
-```rust,ignore
+```rust
+# trait Trait {}
fn foo<T: Trait>() -> T {
+ // ...
+# panic!()
+}
```
allows the caller to determine the return type, `T`, and the function returns that type.
The function:
-```rust,ignore
+```rust
+# trait Trait {}
+# impl Trait for () {}
fn foo() -> impl Trait {
+ // ...
+}
```
doesn't allow the caller to determine the return type.
diff --git a/src/doc/rust-by-example/README.md b/src/doc/rust-by-example/README.md
index 462f733e5..e43b044c8 100644
--- a/src/doc/rust-by-example/README.md
+++ b/src/doc/rust-by-example/README.md
@@ -15,11 +15,11 @@ to read it online.
If you'd like to read it locally, [install Rust], and then:
```bash
-$ git clone https://github.com/rust-lang/rust-by-example
-$ cd rust-by-example
-$ cargo install mdbook
-$ mdbook build
-$ mdbook serve
+git clone https://github.com/rust-lang/rust-by-example
+cd rust-by-example
+cargo install mdbook
+mdbook build
+mdbook serve
```
[install Rust]: https://www.rust-lang.org/tools/install
diff --git a/src/doc/rust-by-example/src/error/multiple_error_types/reenter_question_mark.md b/src/doc/rust-by-example/src/error/multiple_error_types/reenter_question_mark.md
index 61f80fc3e..998b741e7 100644
--- a/src/doc/rust-by-example/src/error/multiple_error_types/reenter_question_mark.md
+++ b/src/doc/rust-by-example/src/error/multiple_error_types/reenter_question_mark.md
@@ -5,7 +5,7 @@ Notice in the previous example that our immediate reaction to calling
error:
```rust,ignore
-.and_then(|s| s.parse::<i32>()
+.and_then(|s| s.parse::<i32>())
.map_err(|e| e.into())
```
diff --git a/src/doc/rust-by-example/src/hello/print.md b/src/doc/rust-by-example/src/hello/print.md
index d578337ad..bf23a9023 100644
--- a/src/doc/rust-by-example/src/hello/print.md
+++ b/src/doc/rust-by-example/src/hello/print.md
@@ -44,8 +44,9 @@ fn main() {
println!("{number:>5}", number=1);
// You can pad numbers with extra zeroes,
+ println!("{number:0>5}", number=1); // 00001
// and left-adjust by flipping the sign. This will output "10000".
- println!("{number:0<5}", number=1);
+ println!("{number:0<5}", number=1); // 10000
// You can use named arguments in the format specifier by appending a `$`.
println!("{number:0>width$}", number=1, width=5);
@@ -62,7 +63,7 @@ fn main() {
// This will not compile because `Structure` does not implement
// fmt::Display.
- //println!("This struct `{}` won't print...", Structure(3));
+ // println!("This struct `{}` won't print...", Structure(3));
// TODO ^ Try uncommenting this line
// For Rust 1.58 and above, you can directly capture the argument from a
diff --git a/src/doc/rust-by-example/src/primitives/array.md b/src/doc/rust-by-example/src/primitives/array.md
index 9cec24d69..5f5e69944 100644
--- a/src/doc/rust-by-example/src/primitives/array.md
+++ b/src/doc/rust-by-example/src/primitives/array.md
@@ -63,7 +63,9 @@ fn main() {
}
}
- // Out of bound indexing causes compile time error.
+ // Out of bound indexing on array causes compile time error.
//println!("{}", xs[5]);
+ // Out of bound indexing on slice causes runtime error.
+ //println!("{}", xs[..][5]);
}
```
diff --git a/src/doc/rustc-dev-guide/src/SUMMARY.md b/src/doc/rustc-dev-guide/src/SUMMARY.md
index b01cb6797..58a476bdc 100644
--- a/src/doc/rustc-dev-guide/src/SUMMARY.md
+++ b/src/doc/rustc-dev-guide/src/SUMMARY.md
@@ -24,6 +24,7 @@
- [Test headers](./tests/headers.md)
- [Performance testing](./tests/perf.md)
- [Crater](./tests/crater.md)
+ - [Suggest tests tool](./tests/suggest-tests.md)
- [Debugging the compiler](./compiler-debugging.md)
- [Using the tracing/logging instrumentation](./tracing.md)
- [Profiling the compiler](./profiling.md)
diff --git a/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md b/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md
index 59893bdc1..eb674c8fe 100644
--- a/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md
+++ b/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md
@@ -99,10 +99,10 @@ Also, note that `x.py` supports all kinds of path suffixes for `compiler`, `libr
and `src/tools` directories. So, you can simply run `x.py test tidy` instead of
`x.py test src/tools/tidy`. Or, `x.py build std` instead of `x.py build library/std`.
-[rust-analyzer]: ./building/suggested.html#configuring-rust-analyzer-for-rustc
+[rust-analyzer]: suggested.html#configuring-rust-analyzer-for-rustc
-See the chapters on [building](./building/how-to-build-and-run.md),
-[testing](./tests/intro.md), and [rustdoc](./rustdoc.md) for more details.
+See the chapters on [building](how-to-build-and-run),
+[testing](../tests/intro), and [rustdoc](../rustdoc) for more details.
### Building the compiler
diff --git a/src/doc/rustc-dev-guide/src/building/suggested.md b/src/doc/rustc-dev-guide/src/building/suggested.md
index 3049d87db..9dcc795f2 100644
--- a/src/doc/rustc-dev-guide/src/building/suggested.md
+++ b/src/doc/rustc-dev-guide/src/building/suggested.md
@@ -109,6 +109,23 @@ the problem. A nice side-effect of this style is that you are left
with a fairly fine-grained set of commits at the end, all of which
build and pass tests. This often helps reviewing.
+## `x suggest`
+
+The `x suggest` subcommand suggests (and runs) a subset of the extensive
+`rust-lang/rust` tests based on files you have changed. This is especially useful
+for new contributors who have not mastered the arcane `x` flags yet and more
+experienced contributors as a shorthand for reducing mental effort. In all cases
+it is useful not to run the full tests (which can take on the order of tens of
+minutes) and just run a subset which are relevant to your changes. For example,
+running `tidy` and `linkchecker` is useful when editing Markdown files, whereas UI
+tests are much less likely to be helpful. While `x suggest` is a useful tool, it
+does not guarantee perfect coverage (just as PR CI isn't a substitute for bors).
+See the [dedicated chapter](../tests/suggest-tests.md) for more information and
+contribution instructions.
+
+Please note that `x suggest` is in a beta state currently and the tests that it
+will suggest are limited.
+
## Configuring `rustup` to use nightly
Some parts of the bootstrap process uses pinned, nightly versions of tools like
@@ -322,3 +339,13 @@ pkgs.mkShell {
RUST_BOOTSTRAP_CONFIG = config;
}
```
+
+## Shell Completions
+
+If you use Bash, Fish or PowerShell, you can find automatically-generated shell completion scripts for `x.py` in [`src/etc/completions`](https://github.com/rust-lang/rust/tree/master/src/etc/completions).
+Zsh support will also be included once issues with [`clap_complete`](https://crates.io/crates/clap_complete) have been resolved.
+
+You can use `source ./src/etc/completions/x.py.<extension>`
+to load completions for your shell of choice,
+or `source .\src\etc\completions\x.py.ps1` for PowerShell.
+Adding this to your shell's startup script (e.g. `.bashrc`) will automatically load this completion. \ No newline at end of file
diff --git a/src/doc/rustc-dev-guide/src/getting-started.md b/src/doc/rustc-dev-guide/src/getting-started.md
index d5c948994..297873d98 100644
--- a/src/doc/rustc-dev-guide/src/getting-started.md
+++ b/src/doc/rustc-dev-guide/src/getting-started.md
@@ -90,7 +90,7 @@ filtering the search to areas you're interested in. For example:
Not all important or beginner work has issue labels.
See below for how to find work that isn't labelled.
-[help-wanted-search]: https://github.com/issues?q=is%3Aopen+is%3Aissue+org%3Arust-lang+no%3Aassignee+label%3AE-easy%2C%22good+first+issue%22%2Cgood-first-issue%2CE-medium%2CE-help-wanted%2CE-mentor
+[help-wanted-search]: https://github.com/issues?q=is%3Aopen+is%3Aissue+org%3Arust-lang+no%3Aassignee+label%3AE-easy%2C%22good+first+issue%22%2Cgood-first-issue%2CE-medium%2CE-help-wanted%2CE-mentor+-label%3AS-blocked+
[Triage]: ./contributing.md#issue-triage
### Recurring work
@@ -169,7 +169,7 @@ incredibly helpful:
## Cloning and Building
-See ["How to build and run the compiler"](./building//how-to-build-and-run.md).
+See ["How to build and run the compiler"](./building/how-to-build-and-run.md).
## Contributor Procedures
diff --git a/src/doc/rustc-dev-guide/src/hir-debugging.md b/src/doc/rustc-dev-guide/src/hir-debugging.md
index 8788ad4de..c25a558a0 100644
--- a/src/doc/rustc-dev-guide/src/hir-debugging.md
+++ b/src/doc/rustc-dev-guide/src/hir-debugging.md
@@ -3,6 +3,6 @@
The `-Z unpretty=hir-tree` flag will dump out the HIR.
If you are trying to correlate `NodeId`s or `DefId`s with source code, the
-`--pretty expanded,identified` flag may be useful.
+`-Z unpretty=expanded,identified` flag may be useful.
TODO: anything else? [#1159](https://github.com/rust-lang/rustc-dev-guide/issues/1159)
diff --git a/src/doc/rustc-dev-guide/src/mir/optimizations.md b/src/doc/rustc-dev-guide/src/mir/optimizations.md
index 037cf5874..293d2fe91 100644
--- a/src/doc/rustc-dev-guide/src/mir/optimizations.md
+++ b/src/doc/rustc-dev-guide/src/mir/optimizations.md
@@ -131,6 +131,6 @@ needed for correctness), then fuel should not be used. An example of this is `Pr
perform optimizations. In these situations, we should allow for the initial gathering pass
and then check fuel as close to the mutation as possible. This allows for the best
debugging experience, because we can determine where in the list of candidates an optimization
-may have been misapplied. Examples of this are `InstCombine` and `ConstantPropagation`.
+may have been misapplied. Examples of this are `InstSimplify` and `ConstantPropagation`.
[consideroptimizing]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/context/struct.TyCtxt.html#method.consider_optimizing
diff --git a/src/doc/rustc-dev-guide/src/solve/trait-solving.md b/src/doc/rustc-dev-guide/src/solve/trait-solving.md
index 71f6581c2..b0cd9af6c 100644
--- a/src/doc/rustc-dev-guide/src/solve/trait-solving.md
+++ b/src/doc/rustc-dev-guide/src/solve/trait-solving.md
@@ -96,6 +96,10 @@ Trait solving during codegen should have the same result as during typeck. As we
all free regions during codegen we must not rely on them during typeck. A noteworthy example
is special behavior for `'static`.
+We also have to be careful with relying on equality of regions in the trait solver.
+This is fine for codegen, as we treat all erased regions are equal. We can however
+lose equality information from HIR to MIR typeck.
+
### 7. Removing ambiguity makes strictly more things compile
We *should* not rely on ambiguity for things to compile.
diff --git a/src/doc/rustc-dev-guide/src/tests/headers.md b/src/doc/rustc-dev-guide/src/tests/headers.md
index 5b71f3ea1..682c96b44 100644
--- a/src/doc/rustc-dev-guide/src/tests/headers.md
+++ b/src/doc/rustc-dev-guide/src/tests/headers.md
@@ -52,6 +52,8 @@ found in [`header.rs`] from the compiletest source.
* [`stderr-per-bitwidth`](ui.md#output-comparison) — separate output per bit width
* [`dont-check-compiler-stderr`](ui.md#output-comparison) — don't validate stderr
* [`dont-check-compiler-stdout`](ui.md#output-comparison) — don't validate stdout
+ * [`compare-output-lines-by-subset`](ui.md#output-comparison) — checks output by
+ line subset
* [Building auxiliary crates](compiletest.md#building-auxiliary-crates)
* `aux-build`
* `aux-crate`
@@ -72,6 +74,7 @@ found in [`header.rs`] from the compiletest source.
* [Environment variable headers](#environment-variable-headers)
* `rustc-env`
* `exec-env`
+ * `unset-exec-env`
* `unset-rustc-env`
* [Miscellaneous headers](#miscellaneous-headers)
* `compile-flags` — adds compiler flags
@@ -177,6 +180,8 @@ The following headers affect environment variables.
form `KEY=VALUE`.
* `exec-env` is an environment variable to set when executing a test of the
form `KEY=VALUE`.
+* `unset-exec-env` specifies an environment variable to unset when executing a
+ test.
* `unset-rustc-env` specifies an environment variable to unset when running
`rustc`.
diff --git a/src/doc/rustc-dev-guide/src/tests/suggest-tests.md b/src/doc/rustc-dev-guide/src/tests/suggest-tests.md
new file mode 100644
index 000000000..f6b6d1537
--- /dev/null
+++ b/src/doc/rustc-dev-guide/src/tests/suggest-tests.md
@@ -0,0 +1,55 @@
+# Suggest tests tool
+
+This chapter is about the internals of and contribution instructions for the
+`suggest-tests` tool. For a high-level overview of the tool, see
+[this section](../building/suggested.md#x-suggest). This tool is currently in a
+beta state and is tracked by [this](https://github.com/rust-lang/rust/issues/109933)
+issue on Github. Currently the number of tests it will suggest are very limited
+in scope, we are looking to expand this (contributions welcome!).
+
+## Internals
+
+The tool is defined in a separate crate ([`src/tools/suggest-tests`](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests))
+which outputs suggestions which are parsed by a shim in bootstrap
+([`src/bootstrap/suggest.rs`](https://github.com/rust-lang/rust/blob/master/src/bootstrap/suggest.rs)).
+The only notable thing the bootstrap shim does is (when invoked with the
+`--run` flag) use bootstrap's internal mechanisms to create a new `Builder` and
+uses it to invoke the suggested commands. The `suggest-tests` crate is where the
+fun happens, two kinds of suggestions are defined: "static" and "dynamic"
+suggestions.
+
+### Static suggestions
+
+Defined [here](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests/src/static_suggestions.rs).
+Static suggestions are simple: they are just [globs](https://crates.io/crates/glob)
+which map to a `x` command. In `suggest-tests`, this is implemented with a
+simple `macro_rules` macro.
+
+### Dynamic suggestions
+
+Defined [here](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests/src/dynamic_suggestions.rs).
+These are more complicated than static suggestions and are implemented as
+functions with the following signature: `fn(&Path) -> Vec<Suggestion>`. In
+other words, each suggestion takes a path to a modified file and (after running
+arbitrary Rust code) can return any number of suggestions, or none. Dynamic
+suggestions are useful for situations where fine-grained control over
+suggestions is needed. For example, modifications to the `compiler/xyz/` path
+should trigger the `x test compiler/xyz` suggestion. In the future, dynamic
+suggestions might even read file contents to determine if (what) tests should
+run.
+
+## Adding a suggestion
+
+The following steps should serve as a rough guide to add suggestions to
+`suggest-tests` (very welcome!):
+
+1. Determine the rules for your suggestion. Is it simple and operates only on
+ a single path or does it match globs? Does it need fine-grained control over
+ the resulting command or does "one size fit all"?
+2. Based on the previous step, decide if your suggestion should be implemented
+ as either static or dynamic.
+3. Implement the suggestion. If it is dynamic then a test is highly recommended,
+ to verify that your logic is correct and to give an example of the suggestion.
+ See the [tests.rs](https://github.com/rust-lang/rust/blob/master/src/tools/suggest-tests/src/tests.rs)
+ file.
+4. Open a PR implementing your suggestion. **(TODO: add example PR)**
diff --git a/src/doc/rustc-dev-guide/src/tests/ui.md b/src/doc/rustc-dev-guide/src/tests/ui.md
index cc32ad1d3..d94d8cc4e 100644
--- a/src/doc/rustc-dev-guide/src/tests/ui.md
+++ b/src/doc/rustc-dev-guide/src/tests/ui.md
@@ -84,6 +84,9 @@ check for output files:
[Normalization](#normalization)).
* `dont-check-compiler-stderr` — Ignores stderr from the compiler.
* `dont-check-compiler-stdout` — Ignores stdout from the compiler.
+* `compare-output-lines-by-subset` — Checks that the output contains the
+ contents of the stored output files by lines opposed to checking for strict
+ equality.
UI tests run with with `-Zdeduplicate-diagnostics=no` flag which disables
rustc's built-in diagnostic deduplication mechanism.
diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md
index 8ded2ee59..73343ba9d 100644
--- a/src/doc/rustc/src/SUMMARY.md
+++ b/src/doc/rustc/src/SUMMARY.md
@@ -27,6 +27,7 @@
- [armv7-unknown-linux-uclibceabihf](platform-support/armv7-unknown-linux-uclibceabihf.md)
- [\*-android and \*-androideabi](platform-support/android.md)
- [\*-linux-ohos](platform-support/openharmony.md)
+ - [\*-esp-espidf](platform-support/esp-idf.md)
- [\*-unknown-fuchsia](platform-support/fuchsia.md)
- [\*-kmc-solid_\*](platform-support/kmc-solid.md)
- [loongarch\*-unknown-linux-\*](platform-support/loongarch-linux.md)
@@ -42,6 +43,7 @@
- [wasm64-unknown-unknown](platform-support/wasm64-unknown-unknown.md)
- [x86_64-fortanix-unknown-sgx](platform-support/x86_64-fortanix-unknown-sgx.md)
- [x86_64-unknown-none](platform-support/x86_64-unknown-none.md)
+ - [x86_64h-apple-darwin](platform-support/x86_64h-apple-darwin.md)
- [Targets](targets/index.md)
- [Built-in Targets](targets/built-in.md)
- [Custom Targets](targets/custom.md)
diff --git a/src/doc/rustc/src/codegen-options/index.md b/src/doc/rustc/src/codegen-options/index.md
index 62347f169..1041d5026 100644
--- a/src/doc/rustc/src/codegen-options/index.md
+++ b/src/doc/rustc/src/codegen-options/index.md
@@ -84,12 +84,20 @@ Note: The [`-g` flag][option-g-debug] is an alias for `-C debuginfo=2`.
This flag controls whether or not the linker includes its default libraries.
It takes one of the following values:
-* `y`, `yes`, `on`, `true` or no value: include default libraries (the default).
-* `n`, `no`, `off` or `false`: exclude default libraries.
+* `y`, `yes`, `on`, `true`: include default libraries.
+* `n`, `no`, `off` or `false` or no value: exclude default libraries (the default).
For example, for gcc flavor linkers, this issues the `-nodefaultlibs` flag to
the linker.
+## dlltool
+
+On `windows-gnu` targets, this flag controls which dlltool `rustc` invokes to
+generate import libraries when using the [`raw-dylib` link kind](../../reference/items/external-blocks.md#the-link-attribute).
+It takes a path to [the dlltool executable](https://sourceware.org/binutils/docs/binutils/dlltool.html).
+If this flag is not specified, a dlltool executable will be inferred based on
+the host environment and target.
+
## embed-bitcode
This flag controls whether or not the compiler embeds LLVM bitcode into object
@@ -574,7 +582,8 @@ change in the future.
This instructs `rustc` to generate code specifically for a particular processor.
You can run `rustc --print target-cpus` to see the valid options to pass
-here. Each target has a default base CPU. Special values include:
+and the default target CPU for the current buid target.
+Each target has a default base CPU. Special values include:
* `native` can be passed to use the processor of the host machine.
* `generic` refers to an LLVM target with minimal features but modern tuning.
diff --git a/src/doc/rustc/src/command-line-arguments.md b/src/doc/rustc/src/command-line-arguments.md
index d4d26654e..3be4382b0 100644
--- a/src/doc/rustc/src/command-line-arguments.md
+++ b/src/doc/rustc/src/command-line-arguments.md
@@ -248,8 +248,14 @@ The valid types of print values are:
exact format of this debugging output is not a stable guarantee, other than
that it will include the linker executable and the text of each command-line
argument passed to the linker.
+- `deployment-target` - The currently selected [deployment target] (or minimum OS version)
+ for the selected Apple platform target. This value can be used or passed along to other
+ components alongside a Rust build that need this information, such as C compilers.
+ This returns rustc's minimum supported deployment target if no `*_DEPLOYMENT_TARGET` variable
+ is present in the environment, or otherwise returns the variable's parsed value.
[conditional compilation]: ../reference/conditional-compilation.html
+[deployment target]: https://developer.apple.com/library/archive/documentation/DeveloperTools/Conceptual/cross_development/Configuring/configuring.html
<a id="option-g-debug"></a>
## `-g`: include debug information
diff --git a/src/doc/rustc/src/exploit-mitigations.md b/src/doc/rustc/src/exploit-mitigations.md
index 98b49e071..a82a53248 100644
--- a/src/doc/rustc/src/exploit-mitigations.md
+++ b/src/doc/rustc/src/exploit-mitigations.md
@@ -115,9 +115,9 @@ equivalent.
<tr>
<td>Stack smashing protection
</td>
- <td>No
+ <td>Yes
</td>
- <td>
+ <td>Nightly
</td>
</tr>
<tr>
@@ -432,18 +432,16 @@ saved return instruction pointer, and checking if this value has changed
when returning from a function. This is also known as “Stack Protector” or
“Stack Smashing Protector (SSP)”.
-The Rust compiler does not support stack smashing protection. However, more
-comprehensive alternatives to stack smashing protection exist, such as
-shadow and safe stack (see backward-edge control flow protection).
+The Rust compiler supports stack smashing protection on nightly builds[42].
![Screenshot of IDA Pro listing cross references to __stack_chk_fail in hello-rust.](images/image3.png "Cross references to __stack_chk_fail in hello-rust.")
Fig. 14. IDA Pro listing cross references to `__stack_chk_fail` in
hello-rust.
To check if stack smashing protection is enabled for a given binary, search
-for cross references to `__stack_chk_fail`. The only cross references to
-`__stack_chk_fail` in hello-rust are from the statically-linked libbacktrace
-library (see Fig. 14).
+for cross references to `__stack_chk_fail`. The presence of these
+cross-references in Rust-compiled code (e.g., `hello_rust::main`) indicates
+that the stack smashing protection is enabled (see Fig. 14).
### Forward-edge control flow protection
@@ -697,3 +695,6 @@ defaults (unrelated to `READ_IMPLIES_EXEC`).
41. “ControlFlowIntegrity.” The Rust Unstable Book.
[https://doc.rust-lang.org/unstable-book/compiler-flags/sanitizer.html#controlflowintegrity](../unstable-book/compiler-flags/sanitizer.html#controlflowintegrity).
+
+42. bbjornse. “add codegen option for using LLVM stack smash protection #84197.”
+ GitHub. <https://github.com/rust-lang/rust/pull/84197>
diff --git a/src/doc/rustc/src/images/image3.png b/src/doc/rustc/src/images/image3.png
index a49e14b5e..ef02c605e 100644
--- a/src/doc/rustc/src/images/image3.png
+++ b/src/doc/rustc/src/images/image3.png
Binary files differ
diff --git a/src/doc/rustc/src/instrument-coverage.md b/src/doc/rustc/src/instrument-coverage.md
index b0b2f4196..2535cd4f1 100644
--- a/src/doc/rustc/src/instrument-coverage.md
+++ b/src/doc/rustc/src/instrument-coverage.md
@@ -117,7 +117,7 @@ $ ls formatjson5.profraw
formatjson5.profraw
```
-If `LLVM_PROFILE_FILE` contains a path to a non-existent directory, the missing directory structure will be created. Additionally, the following special pattern strings are rewritten:
+If `LLVM_PROFILE_FILE` contains a path to a nonexistent directory, the missing directory structure will be created. Additionally, the following special pattern strings are rewritten:
- `%p` - The process ID.
- `%h` - The hostname of the machine running the program.
diff --git a/src/doc/rustc/src/json.md b/src/doc/rustc/src/json.md
index d8843280b..11d7b5b59 100644
--- a/src/doc/rustc/src/json.md
+++ b/src/doc/rustc/src/json.md
@@ -61,7 +61,7 @@ Diagnostics have the following format:
/* The file where the span is located.
Note that this path may not exist. For example, if the path
points to the standard library, and the rust src is not
- available in the sysroot, then it may point to a non-existent
+ available in the sysroot, then it may point to a nonexistent
file. Beware that this may also point to the source of an
external crate.
*/
diff --git a/src/doc/rustc/src/platform-support.md b/src/doc/rustc/src/platform-support.md
index c378532db..3b2463aa5 100644
--- a/src/doc/rustc/src/platform-support.md
+++ b/src/doc/rustc/src/platform-support.md
@@ -88,6 +88,7 @@ target | notes
`arm-unknown-linux-gnueabi` | ARMv6 Linux (kernel 3.2, glibc 2.17)
`arm-unknown-linux-gnueabihf` | ARMv6 Linux, hardfloat (kernel 3.2, glibc 2.17)
`armv7-unknown-linux-gnueabihf` | ARMv7 Linux, hardfloat (kernel 3.2, glibc 2.17)
+[`loongarch64-unknown-linux-gnu`](platform-support/loongarch-linux.md) | LoongArch64 Linux, LP64D ABI (kernel 5.19, glibc 2.36)
`mips-unknown-linux-gnu` | MIPS Linux (kernel 4.4, glibc 2.23)
`mips64-unknown-linux-gnuabi64` | MIPS64 Linux, n64 ABI (kernel 4.4, glibc 2.23)
`mips64el-unknown-linux-gnuabi64` | MIPS64 (LE) Linux, n64 ABI (kernel 4.4, glibc 2.23)
@@ -266,7 +267,6 @@ target | std | host | notes
`i686-uwp-windows-gnu` | ? | |
`i686-uwp-windows-msvc` | ? | |
`i686-wrs-vxworks` | ? | |
-[`loongarch64-unknown-linux-gnu`](platform-support/loongarch-linux.md) | ? | | LoongArch64 Linux (LP64D ABI)
[`m68k-unknown-linux-gnu`](platform-support/m68k-unknown-linux-gnu.md) | ? | | Motorola 680x0 Linux
`mips-unknown-linux-uclibc` | ✓ | | MIPS Linux with uClibc
[`mips64-openwrt-linux-musl`](platform-support/mips64-openwrt-linux-musl.md) | ? | | MIPS64 for OpenWrt Linux MUSL
@@ -297,7 +297,7 @@ target | std | host | notes
`riscv32gc-unknown-linux-musl` | | | RISC-V Linux (kernel 5.4, musl + RISCV32 support patches)
`riscv32im-unknown-none-elf` | * | | Bare RISC-V (RV32IM ISA)
[`riscv32imac-unknown-xous-elf`](platform-support/riscv32imac-unknown-xous-elf.md) | ? | | RISC-V Xous (RV32IMAC ISA)
-`riscv32imc-esp-espidf` | ✓ | | RISC-V ESP-IDF
+[`riscv32imc-esp-espidf`](platform-support/esp-idf.md) | ✓ | | RISC-V ESP-IDF
`riscv64gc-unknown-freebsd` | | | RISC-V FreeBSD
`riscv64gc-unknown-fuchsia` | | | RISC-V Fuchsia
`riscv64gc-unknown-linux-musl` | | | RISC-V Linux (kernel 4.20, musl 1.2.0)
@@ -327,5 +327,6 @@ target | std | host | notes
`x86_64-uwp-windows-gnu` | ✓ | |
`x86_64-uwp-windows-msvc` | ✓ | |
`x86_64-wrs-vxworks` | ? | |
+`x86_64h-apple-darwin` | ✓ | ✓ | macOS with late-gen Intel (at least Haswell)
[runs on NVIDIA GPUs]: https://github.com/japaric-archived/nvptx#targets
diff --git a/src/doc/rustc/src/platform-support/armv7-sony-vita-eabihf.md b/src/doc/rustc/src/platform-support/armv7-sony-vita-newlibeabihf.md
index 6619c90b8..d75bd92be 100644
--- a/src/doc/rustc/src/platform-support/armv7-sony-vita-eabihf.md
+++ b/src/doc/rustc/src/platform-support/armv7-sony-vita-newlibeabihf.md
@@ -1,26 +1,40 @@
-# armv7-sony-vita-eabihf
+# armv7-sony-vita-newlibeabihf
**Tier: 3**
This tier supports the ARM Cortex A9 processor running on a PlayStation Vita console. `armv7-vita-newlibeabihf` aims to have support for `std` crate using `newlib` as a bridge.
+Rust support for this target is not affiliated with Sony, and is not derived
+from nor used with any official Sony SDK.
+
## Designated Developers
* [@amg98](https://github.com/amg98)
+* [@nikarh](https://github.com/nikarh)
## Requirements
-This target is cross compiled, and requires installing [VITASDK](https://vitasdk.org/) toolchain on your system.
+This target is cross-compiled, and requires installing [VITASDK](https://vitasdk.org/) toolchain on your system. Dynamic linking is not supported.
+
+`#![no_std]` crates can be built using `build-std` to build `core`, and optionally
+`alloc`, and `panic_abort`.
+
+`std` is partially supported, but mostly works. Some APIs are unimplemented
+and will simply return an error, such as `std::process`. An allocator is provided
+by default.
+
+In order to support some APIs, binaries must be linked against `libc` written
+for the target, using a linker for the target. These are provided by the
+VITASDK toolchain.
+
+This target generates binaries in the ELF format.
## Building
-You can build Rust with support for the target by adding it to the `target`
-list in `config.toml`:
+Rust does not ship pre-compiled artifacts for this target. You can use `build-std` flag to build binaries with `std`:
-```toml
-[build]
-build-stage = 1
-target = ["armv7-sony-vita-newlibeabihf"]
+```sh
+cargo build -Z build-std=std,panic_abort --target=armv7-sony-vita-newlibeabihf --release
```
## Cross-compilation
@@ -33,26 +47,81 @@ Currently there is no support to run the rustc test suite for this target.
## Building and Running Rust Programs
-To test your developed rust programs for PlayStation Vita, first you have to prepare a proper executable for the device using the resulting ELF file you get from compilation step. The needed steps can be automated using tools like `cargo-make`. Use the example below as a template for your project:
+`std` support for this target relies on newlib. In order to work, newlib must be initialized correctly. The easiest way to achieve this with VITASDK newlib implementation is by compiling your program as a staticlib with and exposing your main function from rust to `_init` function in `crt0`.
+
+Add this to your `Cargo.toml`:
+
+```toml
+[lib]
+crate-type = ["staticlib"]
+
+[profile.release]
+panic = 'abort'
+lto = true
+opt-level = 3
+```
+
+Your entrypoint should look roughly like this, `src/lib.rs`:
+```rust,ignore,no_run
+#[used]
+#[export_name = "_newlib_heap_size_user"]
+pub static _NEWLIB_HEAP_SIZE_USER: u32 = 100 * 1024 * 1024; // Default heap size is only 32mb, increase it to something suitable for your application
+
+#[no_mangle]
+pub extern "C" fn main() {
+ println!("Hello, world!");
+}
+```
+
+To test your developed rust programs on PlayStation Vita, first you must correctly link and package your rust staticlib. These steps can be preformed using tools available in VITASDK, and can be automated using tools like `cargo-make`.
+
+First, set up environment variables for `VITASDK`, and it's binaries:
+
+```sh
+export VITASDK=/opt/vitasdk
+export PATH=$PATH:$VITASDK/bin
+```
+
+Use the example below as a template for your project:
```toml
[env]
TITLE = "Rust Hello World"
TITLEID = "RUST00001"
+# Add other libs required by your project here
+LINKER_LIBS = "-lpthread -lm -lmathneon"
+
# At least a "sce_sys" folder should be place there for app metadata (title, icons, description...)
# You can find sample assets for that on $VITASDK/share/gcc-arm-vita-eabi/samples/hello_world/sce_sys/
STATIC_DIR = "static" # Folder where static assets should be placed (sce_sys folder is at $STATIC_DIR/sce_sys)
CARGO_TARGET_DIR = { script = ["echo ${CARGO_TARGET_DIR:=target}"] }
-RUST_TARGET_PATH = { script = ["echo $(pwd)"]}
RUST_TARGET = "armv7-sony-vita-newlibeabihf"
CARGO_OUT_DIR = "${CARGO_TARGET_DIR}/${RUST_TARGET}/release"
-[tasks.xbuild]
-# This is the command where you get the ELF executable file (e.g. call to cargo build)
+TARGET_LINKER = "arm-vita-eabi-gcc"
+TARGET_LINKER_FLAGS = "-Wl,-q"
+
+[tasks.build]
+description = "Build the project using `cargo` as a static lib."
+command = "cargo"
+args = ["build", "-Z", "build-std=std,panic_abort", "--target=armv7-sony-vita-newlibeabihf", "--release"]
+
+[tasks.link]
+description = "Build an ELF executable using the `vitasdk` linker."
+dependencies = ["build"]
+script = [
+ """
+ ${TARGET_LINKER} ${TARGET_LINKER_FLAGS} \
+ -L"${CARGO_OUT_DIR}" \
+ -l"${CARGO_MAKE_CRATE_FS_NAME}" \
+ ${LINKER_LIBS} \
+ -o"${CARGO_OUT_DIR}/${CARGO_MAKE_CRATE_NAME}.elf"
+ """
+]
[tasks.strip]
description = "Strip the produced ELF executable."
-dependencies = ["xbuild"]
+dependencies = ["link"]
command = "arm-vita-eabi-strip"
args = ["-g", '${CARGO_OUT_DIR}/${CARGO_MAKE_CRATE_FS_NAME}.elf']
@@ -124,4 +193,4 @@ script = [
]
```
-After running the above script, you should be able to get a *.vpk file in the same folder your *.elf executable resides. Now you can pick it and install it on your own PlayStation Vita using, for example, [VitaShell](https://github.com/TheOfficialFloW/VitaShell/releases) or you can use an emulator. For the time being, the most mature emulator for PlayStation Vita is [Vita3K](https://vita3k.org/), although I personally recommend testing your programs in real hardware, as the emulator is quite experimental.
+After running the above script, you should be able to get a *.vpk file in the same folder your *.elf executable resides. Now you can pick it and install it on your own PlayStation Vita using, or you can use an [Vita3K](https://vita3k.org/) emulator.
diff --git a/src/doc/rustc/src/platform-support/armv7-unknown-linux-uclibceabi.md b/src/doc/rustc/src/platform-support/armv7-unknown-linux-uclibceabi.md
index 09e03e4dc..e351ea001 100644
--- a/src/doc/rustc/src/platform-support/armv7-unknown-linux-uclibceabi.md
+++ b/src/doc/rustc/src/platform-support/armv7-unknown-linux-uclibceabi.md
@@ -66,7 +66,7 @@ After completing these steps you can use rust normally in a native environment.
To cross compile, you'll need to:
-* Build the rust cross toochain using [rust-bootstrap-armv7-unknown-linux-uclibceabi](https://github.com/lancethepants/rust-bootstrap-armv7-unknown-linux-uclibceabi) or your own built toolchain.
+* Build the rust cross toolchain using [rust-bootstrap-armv7-unknown-linux-uclibceabi](https://github.com/lancethepants/rust-bootstrap-armv7-unknown-linux-uclibceabi) or your own built toolchain.
* Link your built toolchain with
```text
diff --git a/src/doc/rustc/src/platform-support/esp-idf.md b/src/doc/rustc/src/platform-support/esp-idf.md
new file mode 100644
index 000000000..8a4ca347e
--- /dev/null
+++ b/src/doc/rustc/src/platform-support/esp-idf.md
@@ -0,0 +1,41 @@
+# `*-esp-espidf`
+
+**Tier: 3**
+
+Targets for the [ESP-IDF](https://github.com/espressif/esp-idf) development framework running on RISC-V and Xtensa CPUs.
+
+## Target maintainers
+
+- Ivan Markov [@ivmarkov](https://github.com/ivmarkov)
+- Scott Mabin [@MabezDev](https://github.com/MabezDev)
+
+## Requirements
+
+The target names follow this format: `$ARCH-esp-espidf`, where `$ARCH` specifies the target processor architecture. The following targets are currently defined:
+
+| Target name | Target CPU(s) |
+|--------------------------------|-----------------------|
+| `riscv32imc-esp-espidf` | [ESP32-C3](https://www.espressif.com/en/products/socs/esp32-c3) |
+
+The minimum supported ESP-IDF version is `v4.3`, though it is recommended to use the latest stable release if possible.
+
+## Building the target
+
+The target can be built by enabling it for a `rustc` build. The `build-std` feature is required to build the standard library for ESP-IDF. `ldproxy` is also required for linking, it can be installed from crates.io.
+
+```toml
+[build]
+target = ["$ARCH-esp-espidf"]
+
+[target.$ARCH-esp-espidf]
+linker = "ldproxy"
+
+[unstable]
+build-std = ["std", "panic_abort"]
+```
+
+The `esp-idf-sys` crate will handle the compilation of ESP-IDF, including downloading the relevant toolchains for the build.
+
+## Cross-compilation toolchains and C code
+
+`esp-idf-sys` exposes the toolchain used in the compilation of ESP-IDF, see the crate [documentation for build output propagation](https://github.com/esp-rs/esp-idf-sys#conditional-compilation) for more information.
diff --git a/src/doc/rustc/src/platform-support/loongarch-linux.md b/src/doc/rustc/src/platform-support/loongarch-linux.md
index d7d31d872..999e71f80 100644
--- a/src/doc/rustc/src/platform-support/loongarch-linux.md
+++ b/src/doc/rustc/src/platform-support/loongarch-linux.md
@@ -1,6 +1,6 @@
# loongarch\*-unknown-linux-\*
-**Tier: 3**
+**Tier: 2**
[LoongArch] is a new RISC ISA developed by Loongson Technology Corporation Limited.
@@ -15,6 +15,8 @@ While the integer base ABI is implied by the machine field, the floating po
| f32 | The base ABI uses 32-bit FPRs for parameter passing. (lp64f)|
| sf | The base ABI uses no FPR for parameter passing. (lp64s) |
+<br>
+
|`ABI type(Base ABI/ABI extension)`| `C library` | `kernel` | `target tuple` |
|----------------------------------|-------------|----------|----------------------------------|
| lp64d/base | glibc | linux | loongarch64-unknown-linux-gnu |
diff --git a/src/doc/rustc/src/platform-support/unknown-uefi.md b/src/doc/rustc/src/platform-support/unknown-uefi.md
index e2bdf73a9..03fa28462 100644
--- a/src/doc/rustc/src/platform-support/unknown-uefi.md
+++ b/src/doc/rustc/src/platform-support/unknown-uefi.md
@@ -123,7 +123,7 @@ There are 3 common ways to compile native C code for UEFI targets:
targets. Be wary of any includes that are not specifically suitable for UEFI
targets (especially the C standard library includes are not always
compatible). Freestanding compilations are recommended to avoid
- incompatibilites.
+ incompatibilities.
## Ecosystem
diff --git a/src/doc/rustc/src/platform-support/x86_64h-apple-darwin.md b/src/doc/rustc/src/platform-support/x86_64h-apple-darwin.md
new file mode 100644
index 000000000..1a6f7bb83
--- /dev/null
+++ b/src/doc/rustc/src/platform-support/x86_64h-apple-darwin.md
@@ -0,0 +1,57 @@
+# `x86_64h-apple-darwin`
+
+**Tier: 3**
+
+Target for macOS on late-generation `x86_64` Apple chips, usable as the
+`x86_64h` entry in universal binaries, and equivalent to LLVM's
+`x86_64h-apple-macosx*` targets.
+
+## Target maintainers
+
+- Thom Chiovoloni `thom@shift.click` <https://github.com/thomcc>
+
+## Requirements
+
+This target is an `x86_64` target that only supports Apple's late-gen
+(Haswell-compatible) Intel chips. It enables a set of target features available
+on these chips (AVX2 and similar), and MachO binaries built with this target may
+be used as the `x86_64h` entry in universal binaries ("fat" MachO binaries), and
+will fail to load on machines that do not support this.
+
+It should support the full standard library (`std` and `alloc` either with
+default or user-defined allocators). This target is probably most useful when
+targetted via cross-compilation (including from `x86_64-apple-darwin`), but if
+built manually, the host tools work.
+
+It is similar to `x86_64-apple-darwin` in nearly all respects, although the
+minimum supported OS version is slightly higher (it requires 10.8 rather than
+`x86_64-apple-darwin`'s 10.7).
+
+## Building the target
+
+Users on Apple targets can build this by adding it to the `target` list in
+`config.toml`, or with `-Zbuild-std`.
+
+## Building Rust programs
+
+Rust does not yet ship pre-compiled artifacts for this target. To compile for
+this target, you will either need to build Rust with the target enabled (see
+"Building the target" above), or build your own copy of `core` by using
+`build-std` or similar.
+
+## Testing
+
+Code built with this target can be run on the set of Intel macOS machines that
+support running `x86_64h` binaries (relatively recent Intel macs). The Rust test
+suite seems to work.
+
+## Cross-compilation toolchains and C code
+
+Cross-compilation to this target from Apple hosts should generally work without
+much configuration, so long as XCode and the CommandLineTools are installed.
+Targetting it from non-Apple hosts is difficult, but no moreso than targetting
+`x86_64-apple-darwin`.
+
+When compiling C code for this target, either the "`x86_64h-apple-macosx*`" LLVM
+targets should be used, or an argument like `-arch x86_64h` should be passed to
+the C compiler.
diff --git a/src/doc/rustdoc/src/SUMMARY.md b/src/doc/rustdoc/src/SUMMARY.md
index 747cc629b..b512135d9 100644
--- a/src/doc/rustdoc/src/SUMMARY.md
+++ b/src/doc/rustdoc/src/SUMMARY.md
@@ -3,6 +3,7 @@
- [What is rustdoc?](what-is-rustdoc.md)
- [Command-line arguments](command-line-arguments.md)
- [How to read rustdoc output](how-to-read-rustdoc.md)
+ - [In-doc settings](read-documentation/in-doc-settings.md)
- [How to write documentation](how-to-write-documentation.md)
- [What to include (and exclude)](write-documentation/what-to-include.md)
- [The `#[doc]` attribute](write-documentation/the-doc-attribute.md)
diff --git a/src/doc/rustdoc/src/how-to-read-rustdoc.md b/src/doc/rustdoc/src/how-to-read-rustdoc.md
index 56342f65d..ccd77fb17 100644
--- a/src/doc/rustdoc/src/how-to-read-rustdoc.md
+++ b/src/doc/rustdoc/src/how-to-read-rustdoc.md
@@ -43,7 +43,7 @@ including automatic and blanket implementations that `rustdoc` knows about.
Subheadings, variants, fields, and many other things in this documentation
are anchors and can be clicked on and deep-linked to,
which is a great way to communicate exactly what you're talking about.
-The typograpical character "§" appears next to lines with anchors on them
+The typographical character "§" appears next to lines with anchors on them
when hovered or given keyboard focus.
## The Navigation Bar
@@ -68,7 +68,7 @@ Typing in the search bar instantly searches the available documentation for
the string entered with a fuzzy matching algorithm that is tolerant of minor
typos.
-By default, the search results give are "In Names",
+By default, the search results given are "In Names",
meaning that the fuzzy match is made against the names of items.
Matching names are shown on the left, and the first few words of their
descriptions are given on the right.
@@ -105,11 +105,6 @@ will match these queries:
But it *does not* match `Result<Vec, u8>` or `Result<u8<Vec>>`.
-### Changing displayed theme
-
-You can change the displayed theme by opening the settings menu (the gear
-icon in the upper right) and then pick a new one from there.
-
### Shortcuts
Pressing `S` while focused elsewhere on the page will move focus to the
diff --git a/src/doc/rustdoc/src/how-to-write-documentation.md b/src/doc/rustdoc/src/how-to-write-documentation.md
index 38fd1db5c..1fa9f8144 100644
--- a/src/doc/rustdoc/src/how-to-write-documentation.md
+++ b/src/doc/rustdoc/src/how-to-write-documentation.md
@@ -165,15 +165,15 @@ extensions:
### Strikethrough
Text may be rendered with a horizontal line through the center by wrapping the
-text with two tilde characters on each side:
+text with one or two tilde characters on each side:
```text
-An example of ~~strikethrough text~~.
+An example of ~~strikethrough text~~. You can also use ~single tildes~.
```
This example will render as:
-> An example of ~~strikethrough text~~.
+> An example of ~~strikethrough text~~. You can also use ~single tildes~.
This follows the [GitHub Strikethrough extension][strikethrough].
diff --git a/src/doc/rustdoc/src/images/collapsed-long-item.png b/src/doc/rustdoc/src/images/collapsed-long-item.png
new file mode 100644
index 000000000..c382870c6
--- /dev/null
+++ b/src/doc/rustdoc/src/images/collapsed-long-item.png
Binary files differ
diff --git a/src/doc/rustdoc/src/images/collapsed-trait-impls.png b/src/doc/rustdoc/src/images/collapsed-trait-impls.png
new file mode 100644
index 000000000..f685656e0
--- /dev/null
+++ b/src/doc/rustdoc/src/images/collapsed-trait-impls.png
Binary files differ
diff --git a/src/doc/rustdoc/src/lints.md b/src/doc/rustdoc/src/lints.md
index 45db3bb9b..fd57b0796 100644
--- a/src/doc/rustdoc/src/lints.md
+++ b/src/doc/rustdoc/src/lints.md
@@ -374,3 +374,41 @@ warning: this URL is not a hyperlink
warning: 2 warnings emitted
```
+
+## `unescaped_backticks`
+
+This lint is **allowed by default**. It detects backticks (\`) that are not escaped.
+This usually means broken inline code. For example:
+
+```rust
+#![warn(rustdoc::unescaped_backticks)]
+
+/// `add(a, b) is the same as `add(b, a)`.
+pub fn add(a: i32, b: i32) -> i32 { a + b }
+```
+
+Which will give:
+
+```text
+warning: unescaped backtick
+ --> src/lib.rs:3:41
+ |
+3 | /// `add(a, b) is the same as `add(b, a)`.
+ | ^
+ |
+note: the lint level is defined here
+ --> src/lib.rs:1:9
+ |
+1 | #![warn(rustdoc::unescaped_backticks)]
+ | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+help: a previous inline code might be longer than expected
+ |
+3 | /// `add(a, b)` is the same as `add(b, a)`.
+ | +
+help: if you meant to use a literal backtick, escape it
+ |
+3 | /// `add(a, b) is the same as `add(b, a)\`.
+ | +
+
+warning: 1 warning emitted
+```
diff --git a/src/doc/rustdoc/src/read-documentation/in-doc-settings.md b/src/doc/rustdoc/src/read-documentation/in-doc-settings.md
new file mode 100644
index 000000000..12928a4f3
--- /dev/null
+++ b/src/doc/rustdoc/src/read-documentation/in-doc-settings.md
@@ -0,0 +1,64 @@
+# Rustdoc in-doc settings
+
+Rustdoc's HTML output includes a settings menu, and this chapter describes what
+each setting in this menu does.
+
+It can be accessed by clicking on the gear button
+(<i class="fa fa-cog" aria-hidden="true"></i>) in the upper right.
+
+## Changing displayed theme
+
+It is possible to change the theme. If you pick the "system preference", you
+will be able to see two new sub-menus: "Preferred light theme" and "Preferred
+dark theme". It means that if your system preference is set to "light", then
+rustdoc will use the theme you selected in "Preferred light theme".
+
+## Auto-hide item contents for large items
+
+If the type definition contains more than 12 items, and this setting is enabled,
+it'll collapse them by default. You can see them by clicking on the `[+]` button
+to expand them.
+
+A good example of this setting in use can be seen in the
+[`Iterator`](https://doc.rust-lang.org/stable/std/iter/trait.Iterator.html) doc
+page:
+
+![Collapsed long item](../images/collapsed-long-item.png)
+
+## Auto-hide item methods' documentation
+
+If enabled, this setting will collapse all trait implementations blocks. It is
+convenient if you just want an overview of all the methods available. You can
+still see a method's documentation by expanding it.
+
+## Auto-hide trait implementation documentation
+
+If enabled, this setting will collapse all trait implementations blocks (you can
+see them in the "Trait Implementations" section). It is convenient if you just
+want an overview of all the trait implemented on a type. You can still see
+a trait implementation's associated items by expanding it.
+
+Example:
+
+![Collapsed trait implementations](../images/collapsed-trait-impls.png)
+
+## Directly go to item in search if there is only one result
+
+If this setting is enabled, you will directly be taken to the result page if
+your search only returned one element. Useful if you know exactly what you're
+looking for and want to be taken there directly and not waste time selecting the
+only search result.
+
+## Show line numbers on code examples
+
+If enabled, this setting will add line numbers to the code examples in the
+documentation. It provides a visual aide for the code reading.
+
+## Disable keyboard shortcuts
+
+If this setting is enabled, the keyboard shortcuts will be disabled. It's useful
+in case some of these shortcuts are already used by a web extension you're
+using.
+
+To see the full list of the rustdoc keyboard shortcuts, you can open the help
+menu (the button with the question mark on the left of the setting menu button).
diff --git a/src/doc/rustdoc/src/references.md b/src/doc/rustdoc/src/references.md
index 45cf4e88e..2e0cb1c0a 100644
--- a/src/doc/rustdoc/src/references.md
+++ b/src/doc/rustdoc/src/references.md
@@ -13,15 +13,15 @@ If you know of other great resources, please submit a pull request!
## Community
- [API Guidelines]
-- [Github tagged RFCs]
-- [Github tagged issues]
+- [GitHub tagged RFCs]
+- [GitHub tagged issues]
- [RFC (stalled) front page styleguide]
- [Guide on how to write documentation for a Rust crate]
[API Guidelines]: https://rust-lang.github.io/api-guidelines/documentation.html
-[Github tagged RFCs]: https://github.com/rust-lang/rfcs/issues?q=label%3AT-rustdoc
-[Github tagged issues]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+label%3AT-rustdoc
+[GitHub tagged RFCs]: https://github.com/rust-lang/rfcs/issues?q=label%3AT-rustdoc
+[GitHub tagged issues]: https://github.com/rust-lang/rust/issues?q=is%3Aissue+is%3Aopen+label%3AT-rustdoc
[Guide on how to write documentation for a Rust crate]: https://blog.guillaume-gomez.fr/articles/2020-03-12+Guide+on+how+to+write+documentation+for+a+Rust+crate
[Learn Rust]: https://doc.rust-lang.org/book/ch14-02-publishing-to-crates-io.html#making-useful-documentation-comments
[RFC 1574: More API Documentation Conventions]: https://rust-lang.github.io/rfcs/1574-more-api-documentation-conventions.html
diff --git a/src/doc/rustdoc/src/scraped-examples.md b/src/doc/rustdoc/src/scraped-examples.md
index d75f6d522..7197e01c8 100644
--- a/src/doc/rustdoc/src/scraped-examples.md
+++ b/src/doc/rustdoc/src/scraped-examples.md
@@ -24,14 +24,14 @@ Then this code snippet will be included in the documentation for `a_func`. This
This feature is unstable, so you can enable it by calling Rustdoc with the unstable `rustdoc-scrape-examples` flag:
```bash
-cargo doc -Zunstable-options -Zrustdoc-scrape-examples=examples
+cargo doc -Zunstable-options -Zrustdoc-scrape-examples
```
To enable this feature on [docs.rs](https://docs.rs), add this to your Cargo.toml:
```toml
[package.metadata.docs.rs]
-cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples=examples"]
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples"]
```
diff --git a/src/doc/rustdoc/src/write-documentation/linking-to-items-by-name.md b/src/doc/rustdoc/src/write-documentation/linking-to-items-by-name.md
index eb2285ef9..72157b5cd 100644
--- a/src/doc/rustdoc/src/write-documentation/linking-to-items-by-name.md
+++ b/src/doc/rustdoc/src/write-documentation/linking-to-items-by-name.md
@@ -88,13 +88,16 @@ fn Foo() {}
```
These prefixes will be stripped when displayed in the documentation, so `[struct@Foo]` will be
-rendered as `Foo`.
+rendered as `Foo`. The following prefixes are available: `struct`, `enum`, `trait`, `union`,
+`mod`, `module`, `const`, `constant`, `fn`, `function`, `method`, `derive`, `type`, `value`,
+`macro`, `prim` or `primitive`.
You can also disambiguate for functions by adding `()` after the function name,
-or for macros by adding `!` after the macro name:
+or for macros by adding `!` after the macro name. The macro `!` can be followed by `()`, `{}`,
+or `[]`. Example:
```rust
-/// This is different from [`foo!`]
+/// This is different from [`foo!()`].
fn foo() {}
/// This is different from [`foo()`]
diff --git a/src/doc/style-guide/src/principles.md b/src/doc/style-guide/src/principles.md
index 216689731..2d203f264 100644
--- a/src/doc/style-guide/src/principles.md
+++ b/src/doc/style-guide/src/principles.md
@@ -6,7 +6,7 @@ following principles (in rough priority order):
* readability
- scan-ability
- avoiding misleading formatting
- - accessibility - readable and editable by users using the the widest
+ - accessibility - readable and editable by users using the widest
variety of hardware, including non-visual accessibility interfaces
- readability of code in contexts without syntax highlighting or IDE
assistance, such as rustc error messages, diffs, grep, and other
diff --git a/src/doc/style-guide/src/statements.md b/src/doc/style-guide/src/statements.md
index 4ab1c36f9..671e6d31a 100644
--- a/src/doc/style-guide/src/statements.md
+++ b/src/doc/style-guide/src/statements.md
@@ -138,18 +138,31 @@ Otherwise, the `else` keyword and opening brace should be placed on the next lin
For example:
```rust
-let Some(x) = abcdef()
- .foo(
- "abc",
- some_really_really_really_long_ident,
- "ident",
- "123456",
- )
- .bar()
- .baz()
- .qux("fffffffffffffffff")
-else {
- foo_bar()
+fn main() {
+ let Some(x) = abcdef()
+ .foo(
+ "abc",
+ some_really_really_really_long_ident,
+ "ident",
+ "123456",
+ )
+ .bar()
+ .baz()
+ .qux("fffffffffffffffff")
+ else {
+ return
+ };
+
+ let Some(x) = some_really_really_really_really_really_really_really_really_really_long_name
+ else {
+ return;
+ };
+
+ let Some(aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa) =
+ bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb
+ else {
+ return;
+ };
}
```
diff --git a/src/doc/style-guide/src/types.md b/src/doc/style-guide/src/types.md
index 25861ddab..ae456ef21 100644
--- a/src/doc/style-guide/src/types.md
+++ b/src/doc/style-guide/src/types.md
@@ -6,7 +6,7 @@
* `[T; expr]`, e.g., `[u32; 42]`, `[Vec<Foo>; 10 * 2 + foo()]` (space after colon, no spaces around square brackets)
* `*const T`, `*mut T` (no space after `*`, space before type)
* `&'a T`, `&T`, `&'a mut T`, `&mut T` (no space after `&`, single spaces separating other words)
-* `unsafe extern "C" fn<'a, 'b, 'c>(T, U, V) -> W` or `fn()` (single spaces around keyowrds and sigils, and after commas, no trailing commas, no spaces around brackets)
+* `unsafe extern "C" fn<'a, 'b, 'c>(T, U, V) -> W` or `fn()` (single spaces around keywords and sigils, and after commas, no trailing commas, no spaces around brackets)
* `!` should be treated like any other type name, `Name`
* `(A, B, C, D)` (spaces after commas, no spaces around parens, no trailing comma unless it is a one-tuple)
* `<Baz<T> as SomeTrait>::Foo::Bar` or `Foo::Bar` or `::Foo::Bar` (no spaces around `::` or angle brackets, single spaces around `as`)
diff --git a/src/doc/unstable-book/src/compiler-flags/check-cfg.md b/src/doc/unstable-book/src/compiler-flags/check-cfg.md
index 321992f7b..10f0fbc50 100644
--- a/src/doc/unstable-book/src/compiler-flags/check-cfg.md
+++ b/src/doc/unstable-book/src/compiler-flags/check-cfg.md
@@ -202,5 +202,5 @@ fn shoot_lasers() {}
#[cfg(feature = "monkeys")] // This is UNEXPECTED, because "monkeys" is not in
// the values(feature) list
-fn write_shakespear() {}
+fn write_shakespeare() {}
```
diff --git a/src/doc/unstable-book/src/compiler-flags/extern-options.md b/src/doc/unstable-book/src/compiler-flags/extern-options.md
index dfc1de77b..087b37dd8 100644
--- a/src/doc/unstable-book/src/compiler-flags/extern-options.md
+++ b/src/doc/unstable-book/src/compiler-flags/extern-options.md
@@ -4,6 +4,7 @@
* Tracking issue for `noprelude`: [#98398](https://github.com/rust-lang/rust/issues/98398)
* Tracking issue for `priv`: [#98399](https://github.com/rust-lang/rust/issues/98399)
* Tracking issue for `nounused`: [#98400](https://github.com/rust-lang/rust/issues/98400)
+* Tracking issue for `force`: [#111302](https://github.com/rust-lang/rust/issues/111302)
The behavior of the `--extern` flag can be modified with `noprelude`, `priv` or `nounused` options.
@@ -25,3 +26,4 @@ To use multiple options, separate them with a comma:
This is used by the [build-std project](https://github.com/rust-lang/wg-cargo-std-aware/) to simulate compatibility with sysroot-only crates.
* `priv`: Mark the crate as a private dependency for the [`exported_private_dependencies`](../../rustc/lints/listing/warn-by-default.html#exported-private-dependencies) lint.
* `nounused`: Suppress [`unused-crate-dependencies`](../../rustc/lints/listing/allowed-by-default.html#unused-crate-dependencies) warnings for the crate.
+* `force`: Resolve the crate as if it is used, even if it is not used. This can be used to satisfy compilation session requirements like the presence of an allocator or panic handler.
diff --git a/src/doc/unstable-book/src/compiler-flags/move-size-limit.md b/src/doc/unstable-book/src/compiler-flags/move-size-limit.md
index 88f022af2..aea054ba9 100644
--- a/src/doc/unstable-book/src/compiler-flags/move-size-limit.md
+++ b/src/doc/unstable-book/src/compiler-flags/move-size-limit.md
@@ -6,5 +6,5 @@ The `-Zmove-size-limit=N` compiler flag enables `large_assignments` lints which
will warn when moving objects whose size exceeds `N` bytes.
Lint warns only about moves in functions that participate in code generation.
-Consequently it will be ineffective for compiler invocatation that emit
+Consequently it will be ineffective for compiler invocation that emit
metadata only, i.e., `cargo check` like workflows.
diff --git a/src/doc/unstable-book/src/compiler-flags/sanitizer.md b/src/doc/unstable-book/src/compiler-flags/sanitizer.md
index b55348b78..aa776daf0 100644
--- a/src/doc/unstable-book/src/compiler-flags/sanitizer.md
+++ b/src/doc/unstable-book/src/compiler-flags/sanitizer.md
@@ -196,18 +196,18 @@ Shadow byte legend (one shadow byte represents 8 application bytes):
# ControlFlowIntegrity
-The LLVM Control Flow Integrity (CFI) support in the Rust compiler initially
-provides forward-edge control flow protection for Rust-compiled code only by
-aggregating function pointers in groups identified by their return and parameter
-types.
-
-Forward-edge control flow protection for C or C++ and Rust -compiled code "mixed
-binaries" (i.e., for when C or C++ and Rust -compiled code share the same
-virtual address space) will be provided in later work by defining and using
-compatible type identifiers (see Type metadata in the design document in the
-tracking issue [#89653](https://github.com/rust-lang/rust/issues/89653)).
-
-LLVM CFI can be enabled with -Zsanitizer=cfi and requires LTO (i.e., -Clto).
+The LLVM Control Flow Integrity (CFI) support in the Rust compiler provides
+forward-edge control flow protection for both Rust-compiled code only and for C
+or C++ and Rust -compiled code mixed-language binaries, also known as “mixed
+binaries” (i.e., for when C or C++ and Rust -compiled code share the same
+virtual address space), by aggregating function pointers in groups identified by
+their return and parameter types.
+
+LLVM CFI can be enabled with `-Zsanitizer=cfi` and requires LTO (i.e., `-Clto`).
+Cross-language LLVM CFI can be enabled with `-Zsanitizer=cfi`, and requires the
+`-Zsanitizer-cfi-normalize-integers` option to be used with Clang
+`-fsanitize-cfi-icall-normalize-integers` for normalizing integer types, and
+proper (i.e., non-rustc) LTO (i.e., `-Clinker-plugin-lto`).
See the [Clang ControlFlowIntegrity documentation][clang-cfi] for more details.
@@ -343,7 +343,7 @@ $
Fig. 5. Build and execution of the modified example with LLVM CFI disabled.
```shell
-$ RUSTFLAGS="-Zsanitizer=cfi -Cembed-bitcode=yes -Clto" cargo run --release
+$ RUSTFLAGS="-Cembed-bitcode=yes -Clto -Zsanitizer=cfi" cargo run --release
Compiling rust-cfi-2 v0.1.0 (/home/rcvalle/rust-cfi-2)
Finished release [optimized] target(s) in 3.38s
Running `target/release/rust-cfi-2`
@@ -392,7 +392,7 @@ Closures][rust-book-ch19-05] chapter of the [The Rust Programming
Language][rust-book] book.
```shell
- cargo run --release
+$ cargo run --release
Compiling rust-cfi-3 v0.1.0 (/home/rcvalle/rust-cfi-3)
Finished release [optimized] target(s) in 0.74s
Running `target/release/rust-cfi-3`
@@ -404,7 +404,7 @@ $
Fig. 8. Build and execution of the modified example with LLVM CFI disabled.
```shell
-$ RUSTFLAGS="-Zsanitizer=cfi -Cembed-bitcode=yes -Clto" cargo run --release
+$ RUSTFLAGS="-Cembed-bitcode=yes -Clto -Zsanitizer=cfi" cargo run --release
Compiling rust-cfi-3 v0.1.0 (/home/rcvalle/rust-cfi-3)
Finished release [optimized] target(s) in 3.40s
Running `target/release/rust-cfi-3`
@@ -420,8 +420,92 @@ flow using an indirect branch/call to a function with different return and
parameter types than the return type expected and arguments intended/passed in
the call/branch site, the execution is also terminated (see Fig. 9).
-[rust-book-ch19-05]: ../../book/ch19-05-advanced-functions-and-closures.html
-[rust-book]: ../../book/title-page.html
+```ignore (cannot-test-this-because-uses-custom-build)
+int
+do_twice(int (*fn)(int), int arg) {
+ return fn(arg) + fn(arg);
+}
+```
+Fig. 10. Example C library.
+
+```ignore (cannot-test-this-because-uses-custom-build)
+use std::mem;
+
+#[link(name = "foo")]
+extern "C" {
+ fn do_twice(f: unsafe extern "C" fn(i32) -> i32, arg: i32) -> i32;
+}
+
+unsafe extern "C" fn add_one(x: i32) -> i32 {
+ x + 1
+}
+
+unsafe extern "C" fn add_two(x: i64) -> i64 {
+ x + 2
+}
+
+fn main() {
+ let answer = unsafe { do_twice(add_one, 5) };
+
+ println!("The answer is: {}", answer);
+
+ println!("With CFI enabled, you should not see the next answer");
+ let f: unsafe extern "C" fn(i32) -> i32 = unsafe {
+ mem::transmute::<*const u8, unsafe extern "C" fn(i32) -> i32>(add_two as *const u8)
+ };
+ let next_answer = unsafe { do_twice(f, 5) };
+
+ println!("The next answer is: {}", next_answer);
+}
+```
+Fig. 11. Another modified example from the [Advanced Functions and
+Closures][rust-book-ch19-05] chapter of the [The Rust Programming
+Language][rust-book] book.
+
+```shell
+$ make
+mkdir -p target/debug
+clang -I. -Isrc -Wall -flto -fvisibility=hidden -c -emit-llvm src/foo.c -o target/debug/libfoo.bc
+llvm-ar rcs target/debug/libfoo.a target/debug/libfoo.bc
+RUSTFLAGS="-L./target/debug -Clinker-plugin-lto -Clinker=clang -Clink-arg=-fuse-ld=lld" cargo build
+ Compiling main v0.1.0 (/home/rcvalle/rust-cross-cfi-1)
+ Finished dev [unoptimized + debuginfo] target(s) in 0.45s
+$ ./target/debug/main
+The answer is: 12
+With CFI enabled, you should not see the next answer
+The next answer is: 14
+$
+```
+Fig. 12. Build and execution of the modified example with LLVM CFI disabled.
+
+```shell
+$ make
+mkdir -p target/debug
+clang -I. -Isrc -Wall -flto -fvisibility=hidden -fsanitize=cfi -fsanitize-cfi-icall-normalize-integers -c -emit-llvm src/foo.c -o target/debug/libfoo.bc
+llvm-ar rcs target/debug/libfoo.a target/debug/libfoo.bc
+RUSTFLAGS="-L./target/debug -Clinker-plugin-lto -Clinker=clang -Clink-arg=-fuse-ld=lld -Zsanitizer=cfi -Zsanitizer-cfi-normalize-integers" cargo build
+ Compiling main v0.1.0 (/home/rcvalle/rust-cross-cfi-1)
+ Finished dev [unoptimized + debuginfo] target(s) in 0.45s
+$ ./target/debug/main
+The answer is: 12
+With CFI enabled, you should not see the next answer
+Illegal instruction
+$
+```
+Fig. 13. Build and execution of the modified example with LLVM CFI enabled.
+
+When LLVM CFI is enabled, if there are any attempts to change/hijack control
+flow using an indirect branch/call to a function with different return and
+parameter types than the return type expected and arguments intended/passed in
+the call/branch site, even across the FFI boundary and for extern "C" function
+types indirectly called (i.e., callbacks/function pointers) across the FFI
+boundary, in C or C++ and Rust -compiled code mixed-language binaries, also
+known as “mixed binaries” (i.e., for when C or C++ and Rust -compiled code share
+the same virtual address space), the execution is also terminated (see Fig. 13).
+
+
+[rust-book-ch19-05]: https://doc.rust-lang.org/book/ch19-05-advanced-functions-and-closures.html
+[rust-book]: https://doc.rust-lang.org/book/title-page.html
# HWAddressSanitizer
diff --git a/src/doc/unstable-book/src/language-features/asm-experimental-arch.md b/src/doc/unstable-book/src/language-features/asm-experimental-arch.md
index 1f52ab750..532cb9eea 100644
--- a/src/doc/unstable-book/src/language-features/asm-experimental-arch.md
+++ b/src/doc/unstable-book/src/language-features/asm-experimental-arch.md
@@ -17,6 +17,8 @@ This feature tracks `asm!` and `global_asm!` support for the following architect
- AVR
- MSP430
- M68k
+- LoongArch
+- s390x
## Register classes
@@ -45,6 +47,10 @@ This feature tracks `asm!` and `global_asm!` support for the following architect
| M68k | `reg` | `d[0-7]`, `a[0-7]` | `r` |
| M68k | `reg_data` | `d[0-7]` | `d` |
| M68k | `reg_addr` | `a[0-3]` | `a` |
+| LoongArch | `reg` | `$r1`, `$r[4-20]`, `$r[23,30]` | `r` |
+| LoongArch | `freg` | `$f[0-31]` | `f` |
+| s390x | `reg` | `r[0-10]`, `r[12-14]` | `r` |
+| s390x | `freg` | `f[0-15]` | `f` |
> **Notes**:
> - NVPTX doesn't have a fixed register set, so named registers are not supported.
@@ -76,6 +82,10 @@ This feature tracks `asm!` and `global_asm!` support for the following architect
| MSP430 | `reg` | None | `i8`, `i16` |
| M68k | `reg`, `reg_addr` | None | `i16`, `i32` |
| M68k | `reg_data` | None | `i8`, `i16`, `i32` |
+| LoongArch64 | `reg` | None | `i8`, `i16`, `i32`, `i64`, `f32`, `f64` |
+| LoongArch64 | `freg` | None | `f32`, `f64` |
+| s390x | `reg` | None | `i8`, `i16`, `i32`, `i64` |
+| s390x | `freg` | None | `f32`, `f64` |
## Register aliases
@@ -97,6 +107,10 @@ This feature tracks `asm!` and `global_asm!` support for the following architect
| M68k | `a5` | `bp` |
| M68k | `a6` | `fp` |
| M68k | `a7` | `sp`, `usp`, `ssp`, `isp` |
+| LoongArch | `$r0` | `zero` |
+| LoongArch | `$r2` | `tp` |
+| LoongArch | `$r3` | `sp` |
+| LoongArch | `$r22` | `fp` |
> **Notes**:
> - TI does not mandate a frame pointer for MSP430, but toolchains are allowed
@@ -106,8 +120,8 @@ This feature tracks `asm!` and `global_asm!` support for the following architect
| Architecture | Unsupported register | Reason |
| ------------ | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| All | `sp` | The stack pointer must be restored to its original value at the end of an asm code block. |
-| All | `fr` (Hexagon), `$fp` (MIPS), `Y` (AVR), `r4` (MSP430), `a6` (M68k) | The frame pointer cannot be used as an input or output. |
+| All | `sp`, `r15` (s390x) | The stack pointer must be restored to its original value at the end of an asm code block. |
+| All | `fr` (Hexagon), `$fp` (MIPS), `Y` (AVR), `r4` (MSP430), `a6` (M68k), `$fp` (LoongArch), `r11` (s390x) | The frame pointer cannot be used as an input or output. |
| All | `r19` (Hexagon) | This is used internally by LLVM as a "base pointer" for functions with complex stack frames. |
| MIPS | `$0` or `$zero` | This is a constant zero register which can't be modified. |
| MIPS | `$1` or `$at` | Reserved for assembler. |
@@ -118,6 +132,10 @@ This feature tracks `asm!` and `global_asm!` support for the following architect
| AVR | `r0`, `r1`, `r1r0` | Due to an issue in LLVM, the `r0` and `r1` registers cannot be used as inputs or outputs. If modified, they must be restored to their original values before the end of the block. |
|MSP430 | `r0`, `r2`, `r3` | These are the program counter, status register, and constant generator respectively. Neither the status register nor constant generator can be written to. |
| M68k | `a4`, `a5` | Used internally by LLVM for the base pointer and global base pointer. |
+| LoongArch | `$r0` or `$zero` | This is a constant zero register which can't be modified. |
+| LoongArch | `$r2` or `$tp` | This is reserved for TLS. |
+| LoongArch | `$r21` | This is reserved by the ABI. |
+| LoongArch | `$r31` or `$s8` | This is used internally by LLVM. |
## Template modifiers
@@ -132,6 +150,10 @@ This feature tracks `asm!` and `global_asm!` support for the following architect
| PowerPC | `reg` | None | `0` | None |
| PowerPC | `reg_nonzero` | None | `3` | `b` |
| PowerPC | `freg` | None | `0` | None |
+| LoongArch | `reg` | None | `$r2` | None |
+| LoongArch | `freg` | None | `$f0` | None |
+| s390x | `reg` | None | `%r0` | None |
+| s390x | `freg` | None | `%f0` | None |
# Flags covered by `preserves_flags`
@@ -142,3 +164,5 @@ These flags registers must be restored upon exiting the asm block if the `preser
- The status register `r2`.
- M68k
- The condition code register `ccr`.
+- s390x
+ - The condition code register `cc`.
diff --git a/src/doc/unstable-book/src/language-features/cfi-encoding.md b/src/doc/unstable-book/src/language-features/cfi-encoding.md
new file mode 100644
index 000000000..f2f74cc17
--- /dev/null
+++ b/src/doc/unstable-book/src/language-features/cfi-encoding.md
@@ -0,0 +1,25 @@
+# `cfi_encoding`
+
+The tracking issue for this feature is: [#89653]
+
+[#89653]: https://github.com/rust-lang/rust/issues/89653
+
+------------------------
+
+The `cfi_encoding` feature allows the user to define a CFI encoding for a type.
+It allows the user to use a different names for types that otherwise would be
+required to have the same name as used in externally defined C functions.
+
+## Examples
+
+```rust
+#![feature(cfi_encoding, extern_types)]
+
+#[cfi_encoding = "3Foo"]
+pub struct Type1(i32);
+
+extern {
+ #[cfi_encoding = "3Bar"]
+ type Type2;
+}
+```
diff --git a/src/doc/unstable-book/src/language-features/debugger-visualizer.md b/src/doc/unstable-book/src/language-features/debugger-visualizer.md
deleted file mode 100644
index c7a0414b6..000000000
--- a/src/doc/unstable-book/src/language-features/debugger-visualizer.md
+++ /dev/null
@@ -1,27 +0,0 @@
-# `debugger_visualizer`
-
-The tracking issue for this feature is: [#95939]
-
-[#95939]: https://github.com/rust-lang/rust/issues/95939
-
-------------------------
-
-The `debugger_visualizer` attribute can be used to instruct the compiler
-to embed a debugger visualizer file into the PDB/ELF generated by `rustc`.
-
-## Examples
-
-``` rust,ignore (partial-example)
-#![feature(debugger_visualizer)]
-#![debugger_visualizer(natvis_file = "foo.natvis")]
-#![debugger_visualizer(gdb_script_file = "foo.py")]
-struct Foo {
-
-}
-```
-
-## Limitations
-
-Currently, this feature only supports embedding Natvis files on `-windows-msvc`
-targets via the `natvis_file` meta item. `-windows-gnu` targets are not currently
-supported.
diff --git a/src/doc/unstable-book/src/language-features/intrinsics.md b/src/doc/unstable-book/src/language-features/intrinsics.md
index a0fb4e743..ea9bace6d 100644
--- a/src/doc/unstable-book/src/language-features/intrinsics.md
+++ b/src/doc/unstable-book/src/language-features/intrinsics.md
@@ -22,7 +22,7 @@ via a declaration like
extern "rust-intrinsic" {
fn transmute<T, U>(x: T) -> U;
- fn offset<T>(dst: *const T, offset: isize) -> *const T;
+ fn arith_offset<T>(dst: *const T, offset: isize) -> *const T;
}
```
diff --git a/src/doc/unstable-book/src/language-features/raw-dylib.md b/src/doc/unstable-book/src/language-features/raw-dylib.md
deleted file mode 100644
index 5fd208ae7..000000000
--- a/src/doc/unstable-book/src/language-features/raw-dylib.md
+++ /dev/null
@@ -1,34 +0,0 @@
-# `raw_dylib`
-
-The tracking issue for this feature is: [#58713]
-
-[#58713]: https://github.com/rust-lang/rust/issues/58713
-
-------------------------
-
-The `raw_dylib` feature allows you to link against the implementations of functions in an `extern`
-block without, on Windows, linking against an import library.
-
-```rust,ignore (partial-example)
-#![feature(raw_dylib)]
-
-#[link(name="library", kind="raw-dylib")]
-extern {
- fn extern_function(x: i32);
-}
-
-fn main() {
- unsafe {
- extern_function(14);
- }
-}
-```
-
-## Limitations
-
-This feature is unstable for the `x86` architecture, and stable for all other architectures.
-
-This feature is only supported on Windows.
-
-On the `x86` architecture, this feature supports only the `cdecl`, `stdcall`, `system`, `fastcall`, and
-`vectorcall` calling conventions.
diff --git a/src/doc/unstable-book/src/language-features/transparent-unions.md b/src/doc/unstable-book/src/language-features/transparent-unions.md
index 9b39b8971..bab88b148 100644
--- a/src/doc/unstable-book/src/language-features/transparent-unions.md
+++ b/src/doc/unstable-book/src/language-features/transparent-unions.md
@@ -65,7 +65,7 @@ pub union GenericUnion<T: Copy> { // Unions with non-`Copy` fields are unstable.
pub const THIS_IS_OKAY: GenericUnion<()> = GenericUnion { field: () };
```
-Like transarent `struct`s, a transparent `union` of type `U` has the same
+Like transparent `struct`s, a transparent `union` of type `U` has the same
layout, size, and ABI as its single non-ZST field. If it is generic over a type
`T`, and all its fields are ZSTs except for exactly one field of type `T`, then
it has the same layout and ABI as `T` (even if `T` is a ZST when monomorphized).
diff --git a/src/doc/unstable-book/src/library-features/libstd-thread-internals.md b/src/doc/unstable-book/src/library-features/libstd-thread-internals.md
deleted file mode 100644
index b682d12e7..000000000
--- a/src/doc/unstable-book/src/library-features/libstd-thread-internals.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# `libstd_thread_internals`
-
-This feature is internal to the Rust compiler and is not intended for general use.
-
-------------------------