From d882e1a5bd08b6df824373b955421352e41cfc42 Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Sat, 12 Oct 2024 08:35:26 -0700 Subject: [PATCH 1/7] 2024: Add reserved syntax --- src/SUMMARY.md | 1 + src/rust-2024/reserving-syntax.md | 63 +++++++++++++++++++++++++++++++ 2 files changed, 64 insertions(+) create mode 100644 src/rust-2024/reserving-syntax.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 437fee4a..d271ffa9 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -55,3 +55,4 @@ - [Unsafe `extern` blocks](rust-2024/unsafe-extern.md) - [Unsafe attributes](rust-2024/unsafe-attributes.md) - [Rustdoc combined tests](rust-2024/rustdoc-doctests.md) + - [Reserving syntax](rust-2024/reserving-syntax.md) diff --git a/src/rust-2024/reserving-syntax.md b/src/rust-2024/reserving-syntax.md new file mode 100644 index 00000000..d5fccfcf --- /dev/null +++ b/src/rust-2024/reserving-syntax.md @@ -0,0 +1,63 @@ +# Reserving syntax + +🚧 The 2024 Edition has not yet been released and hence this section is still "under construction". +More information may be found in the tracking issue at . + +## Summary + +- Unprefixed guarded strings of the form `#"foo"#` are reserved for future use. +- Two or more `#` characters are reserved for future use. + +## Details + +[RFC 3593] reserved syntax in the 2024 Edition for guarded string literals that do not have a prefix to future-proof against future language changes. The 2021 Edition [reserved syntax][2021] for guarded strings with a prefix, such as `ident##"foo"##`. The 2024 Edition extends that to also reserve strings without the `ident` prefix. + +There are two reserved syntaxes: One or more `#` immediately followed by a [string literal], and two or more `#` characters in a row. + +This reservation is done across an edition boundary because of interactions with tokenization and macros. For example, with the following macro: + +```rust +macro_rules! demo { + ( $a:tt ) => { println!("one token") }; + ( $a:tt $b:tt $c:tt ) => { println!("three tokens") }; +} + +demo!("foo"); +demo!(r#"foo"#); +demo!(#"foo"#); +demo!(###) +``` + +Prior to the 2024 Edition, this produces: + +```text +one token +one token +three tokens +three tokens +``` + +Starting in the 2024 Edition, the `#"foo"#` line and the `###` line now generates a compile error because those forms are now reserved. + +[2021]: ../rust-2021/reserving-syntax.md +[string literal]: ../../reference/tokens.html#string-literals +[RFC 3593]: https://rust-lang.github.io/rfcs/3593-unprefixed-guarded-strings.html + +## Migration + +The [`rust_2024_guarded_string_incompatible_syntax`] lint will identify any tokens that match the reserved syntax, and will suggest a modification to insert spaces where necessary to ensure it continues to be parsed as separate tokens. + +The lint is part of the `rust-2024-compatibility` lint group which is included in the automatic edition migration. In order to migrate your code to be Rust 2024 Edition compatible, run: + +```sh +cargo fix --edition +``` + +Alternatively, you can manually enable the lint to find macro calls where you may need to update the tokens: + +```rust +// Add this to the root of your crate to do a manual migration. +#![warn(rust_2024_guarded_string_incompatible_syntax)] +``` + +[`rust_2024_guarded_string_incompatible_syntax`]: ../../rustc/lints/listing/allowed-by-default.html#rust-2024-guarded-string-incompatible-syntax From 91e1efc3605ddb581ba050d4d3c3ad9523daebc4 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Fri, 18 Oct 2024 19:29:57 +0000 Subject: [PATCH 2/7] Say "reserved" rather than "reserving" in title Since all other chapter titles are either noun phrases (e.g. "additions to...", "X change", etc.) or verb phrases in imperative mood (e.g. "remove...", "reject...", "combine..."), it would be odd to have a stray chapter title in the present continuous tense ("reserving..."). Staying with a noun sounds better to my ear than an imperative verb phrase here, so let's do that. This "reserving..." chapter title was also used in the Rust 2021 guide. For consistency, let's change that title and URL also, and add a redirect. --- book.toml | 1 + src/SUMMARY.md | 4 ++-- src/rust-2021/c-string-literals.md | 2 +- src/rust-2021/{reserving-syntax.md => reserved-syntax.md} | 2 +- src/rust-2024/{reserving-syntax.md => reserved-syntax.md} | 4 ++-- 5 files changed, 7 insertions(+), 6 deletions(-) rename src/rust-2021/{reserving-syntax.md => reserved-syntax.md} (99%) rename src/rust-2024/{reserving-syntax.md => reserved-syntax.md} (97%) diff --git a/book.toml b/book.toml index 77867ae1..998a8177 100644 --- a/book.toml +++ b/book.toml @@ -80,6 +80,7 @@ search.use-boolean-and = true "/rust-2018/platform-and-target-support/msvc-toolchain-support.html" = "../../../rustc/platform-support.html" "/rust-2018/platform-and-target-support/musl-support-for-fully-static-binaries.html" = "../../../rustc/platform-support.html" "/rust-2018/platform-and-target-support/cdylib-crates-for-c-interoperability.html" = "https://github.com/rust-lang/rfcs/blob/master/text/1510-cdylib.md" +"/rust-2021/reserving-syntax.html" = "reserved-syntax.html" "/rust-next/index.html" = "../rust-2021/index.html" "/rust-next/edition-changes.html" = "../rust-2021/index.html" "/rust-next/dbg-macro.html" = "../../std/macro.dbg.html" diff --git a/src/SUMMARY.md b/src/SUMMARY.md index d271ffa9..0d43098d 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -30,7 +30,7 @@ - [IntoIterator for arrays](rust-2021/IntoIterator-for-arrays.md) - [Disjoint capture in closures](rust-2021/disjoint-capture-in-closures.md) - [Panic macro consistency](rust-2021/panic-macro-consistency.md) - - [Reserving syntax](rust-2021/reserving-syntax.md) + - [Reserved syntax](rust-2021/reserved-syntax.md) - [Warnings promoted to errors](rust-2021/warnings-promoted-to-error.md) - [Or patterns in macro-rules](rust-2021/or-patterns-macro-rules.md) - [C-string literals](rust-2021/c-string-literals.md) @@ -55,4 +55,4 @@ - [Unsafe `extern` blocks](rust-2024/unsafe-extern.md) - [Unsafe attributes](rust-2024/unsafe-attributes.md) - [Rustdoc combined tests](rust-2024/rustdoc-doctests.md) - - [Reserving syntax](rust-2024/reserving-syntax.md) + - [Reserved syntax](rust-2024/reserved-syntax.md) diff --git a/src/rust-2021/c-string-literals.md b/src/rust-2021/c-string-literals.md index 570794ac..6a34b32d 100644 --- a/src/rust-2021/c-string-literals.md +++ b/src/rust-2021/c-string-literals.md @@ -69,4 +69,4 @@ Migration is only necessary for macros which may have been assuming a sequence o As part of the [syntax reservation] for the 2021 edition, any macro input which may run into this issue should issue a warning from the `rust_2021_prefixes_incompatible_syntax` migration lint. See that chapter for more detail. -[syntax reservation]: reserving-syntax.md +[syntax reservation]: reserved-syntax.md diff --git a/src/rust-2021/reserving-syntax.md b/src/rust-2021/reserved-syntax.md similarity index 99% rename from src/rust-2021/reserving-syntax.md rename to src/rust-2021/reserved-syntax.md index 15e7b1f5..04c2b21c 100644 --- a/src/rust-2021/reserving-syntax.md +++ b/src/rust-2021/reserved-syntax.md @@ -1,4 +1,4 @@ -# Reserving syntax +# Reserved syntax ## Summary diff --git a/src/rust-2024/reserving-syntax.md b/src/rust-2024/reserved-syntax.md similarity index 97% rename from src/rust-2024/reserving-syntax.md rename to src/rust-2024/reserved-syntax.md index d5fccfcf..a1570b14 100644 --- a/src/rust-2024/reserving-syntax.md +++ b/src/rust-2024/reserved-syntax.md @@ -1,4 +1,4 @@ -# Reserving syntax +# Reserved syntax 🚧 The 2024 Edition has not yet been released and hence this section is still "under construction". More information may be found in the tracking issue at . @@ -39,7 +39,7 @@ three tokens Starting in the 2024 Edition, the `#"foo"#` line and the `###` line now generates a compile error because those forms are now reserved. -[2021]: ../rust-2021/reserving-syntax.md +[2021]: ../rust-2021/reserved-syntax.md [string literal]: ../../reference/tokens.html#string-literals [RFC 3593]: https://rust-lang.github.io/rfcs/3593-unprefixed-guarded-strings.html From dceaaca744d1d68266a70f9ae4d4552583c7fc91 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Fri, 18 Oct 2024 22:04:29 +0000 Subject: [PATCH 3/7] Make some editorial tweaks --- src/rust-2024/reserved-syntax.md | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/src/rust-2024/reserved-syntax.md b/src/rust-2024/reserved-syntax.md index a1570b14..99e77e69 100644 --- a/src/rust-2024/reserved-syntax.md +++ b/src/rust-2024/reserved-syntax.md @@ -10,11 +10,14 @@ More information may be found in the tracking issue at Date: Wed, 23 Oct 2024 14:42:53 -0500 Subject: [PATCH 4/7] docs(cargo): Cover MSRV-aware resolver --- src/SUMMARY.md | 1 + src/rust-2024/cargo-resolver.md | 38 +++++++++++++++++++++++++++++++++ 2 files changed, 39 insertions(+) create mode 100644 src/rust-2024/cargo-resolver.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 8caa6ada..6cf543d2 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -44,6 +44,7 @@ - [`unsafe_op_in_unsafe_fn` warning](rust-2024/unsafe-op-in-unsafe-fn.md) - [RPIT lifetime capture rules](rust-2024/rpit-lifetime-capture.md) - [Disallow references to `static mut`](rust-2024/static-mut-references.md) + - [Cargo: Rust-version aware resolver](rust-2024/cargo-resolver.md) - [Cargo: Table and key name consistency](rust-2024/cargo-table-key-names.md) - [Cargo: Reject unused inherited default-features](rust-2024/cargo-inherited-default-features.md) - [Rustfmt: Combine all delimited exprs as last argument](rust-2024/rustfmt-overflow-delimited-expr.md) diff --git a/src/rust-2024/cargo-resolver.md b/src/rust-2024/cargo-resolver.md new file mode 100644 index 00000000..70e3c2fb --- /dev/null +++ b/src/rust-2024/cargo-resolver.md @@ -0,0 +1,38 @@ +# Cargo: Rust-version aware resolver + +🚧 The 2024 Edition has not yet been released and hence this section is still "under construction". + +## Summary + +- `edition = "2024"` implies `resolver = "3"` in `Cargo.toml` which enables a Rust-version aware dependency resolver. + +## Details + +Since Rust 1.84.0, Cargo has opt-in support for compatibility with +[`package.rust-version`] to be considered when selecting dependency versions +by setting [`resolver.incompatible-rust-version = "fallback"`] in `.cargo/config.toml`. + +Starting in Rust 2024, this will be the default. +That is, writing `edition = "2021"` in `Cargo.toml` will imply `resolver = "3"` +which will imply [`resolver.incompatible-rust-version = "fallback"`]. + +The resolver is a global setting for a [workspace], and the setting is ignored in dependencies. +The setting is only honored for the top-level package of the workspace. +If you are using a [virtual workspace], you will still need to explicitly set the [`resolver` field] +in the `[workspace]` definition if you want to opt-in to the new resolver. + +For more details on how Rust-version aware dependency resolution works, see [the Cargo book](../..//cargo/reference/resolver.html#rust-version). + +[`package.rust-version`]: ../../cargo/reference/rust-version.html +[`resolver.incompatible-rust-version = "fallback"`]: ../../cargo/reference/config.html#resolverincompatible-rust-versions +[workspace]: ../../cargo/reference/workspaces.html +[virtual workspace]: ../../cargo/reference/workspaces.html#virtual-workspace +[`resolver` field]: ../../cargo/reference/resolver.html#resolver-versions + +## Migration + +There are no automated migration tools for updating for the new resolver. + +We recommend projects +[verify against the latest dependencies in CI](../../cargo/guide/continuous-integration.html#verifying-latest-dependencies) +to catch bugs in dependencies as soon as possible. From eb24f96cd34b0339e61ede22f006b74d0a2ab1ac Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Wed, 23 Oct 2024 14:42:11 -0700 Subject: [PATCH 5/7] Fix edition number --- src/rust-2024/cargo-resolver.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/rust-2024/cargo-resolver.md b/src/rust-2024/cargo-resolver.md index 70e3c2fb..45b3663e 100644 --- a/src/rust-2024/cargo-resolver.md +++ b/src/rust-2024/cargo-resolver.md @@ -13,7 +13,7 @@ Since Rust 1.84.0, Cargo has opt-in support for compatibility with by setting [`resolver.incompatible-rust-version = "fallback"`] in `.cargo/config.toml`. Starting in Rust 2024, this will be the default. -That is, writing `edition = "2021"` in `Cargo.toml` will imply `resolver = "3"` +That is, writing `edition = "2024"` in `Cargo.toml` will imply `resolver = "3"` which will imply [`resolver.incompatible-rust-version = "fallback"`]. The resolver is a global setting for a [workspace], and the setting is ignored in dependencies. From d7a41bed24472013083dbbe1bc9487919457bd36 Mon Sep 17 00:00:00 2001 From: Michael Howell Date: Sun, 27 Oct 2024 11:22:21 -0700 Subject: [PATCH 6/7] rustdoc: Fix doctest `include` paths CC https://github.com/rust-lang/rust/issues/132230 --- src/SUMMARY.md | 1 + .../rustdoc-doctests-nested-include-str.md | 64 +++++++++++++++++++ 2 files changed, 65 insertions(+) create mode 100644 src/rust-2024/rustdoc-doctests-nested-include-str.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 6cf543d2..c5b8e4a6 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -57,3 +57,4 @@ - [Unsafe attributes](rust-2024/unsafe-attributes.md) - [Rustdoc combined tests](rust-2024/rustdoc-doctests.md) - [Reserved syntax](rust-2024/reserved-syntax.md) + - [Rustdoc doctest nested `include_str!` change](rust-2024/rustdoc-doctests-nested-include-str.md) diff --git a/src/rust-2024/rustdoc-doctests-nested-include-str.md b/src/rust-2024/rustdoc-doctests-nested-include-str.md new file mode 100644 index 00000000..0ed284ee --- /dev/null +++ b/src/rust-2024/rustdoc-doctests-nested-include-str.md @@ -0,0 +1,64 @@ +# Rustdoc doctest nested `include_str!` change + +🚧 The 2024 Edition has not yet been released and hence this section is still "under construction". +More information may be found at . + +## Summary + +When a doctest is included with `include_str!`, if that doctest itself +also uses `include!` / `include_str!` / `include_bytes!`, the path is +resolved relative to the Markdown file, rather than the Rust +source file. + +## Details + +Prior to the 2024 edition, adding documentation with +`#[doc=include_str!("path/file.md")]` didn't carry span information +into the doctests. As a result, if the Markdown file is in a different +directory than the source, any `include!`ed paths need to be relative +to the Rust file. + +For example, consider a library crate with these files: + +* Cargo.toml +* README.md +* src/ + * lib.rs +* examples/ + * data.bin + +Let `lib.rs` contain this: + +```rust,ignore +#![doc=include_str!("../README.md")] +``` + +And assume this `README.md` file: + +````markdown +``` +let _ = include_bytes!("../examples/data.bin"); +// ^^^ notice this +``` +```` + +Prior to the 2024 edition, the path in `README.md` needed to be +relative to the `lib.rs` file. In 2024 and later, it is now relative +to `README.md` iself. + +## Migration + +After migrating, you'll see the following error: + +```text +error: couldn't read `../examples/data.bin`: No such file or directory (os error 2) + --> src/../README.md:2:24 + | +2 | let _ = include_bytes!("../examples/data.bin"); + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + = note: this error originates in the macro `include_bytes` (in Nightly builds, run with -Z macro-backtrace for more info) +help: there is a file with the same name in a different directory + | +2 | let _ = include_bytes!("examples/data.bin"); + | ~~~~~~~~~~~~~~~~~~~ +``` From 96ea9845bd6b7058d2e3deb74a83204bc5abb1b7 Mon Sep 17 00:00:00 2001 From: Travis Cross Date: Wed, 30 Oct 2024 04:31:26 +0000 Subject: [PATCH 7/7] Prepare PR #329 to be merged We made an editorial pass over this. --- src/SUMMARY.md | 2 +- .../rustdoc-doctests-nested-include-str.md | 64 ------------------- src/rust-2024/rustdoc-nested-includes.md | 63 ++++++++++++++++++ 3 files changed, 64 insertions(+), 65 deletions(-) delete mode 100644 src/rust-2024/rustdoc-doctests-nested-include-str.md create mode 100644 src/rust-2024/rustdoc-nested-includes.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index c5b8e4a6..8e69ec06 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -56,5 +56,5 @@ - [Unsafe `extern` blocks](rust-2024/unsafe-extern.md) - [Unsafe attributes](rust-2024/unsafe-attributes.md) - [Rustdoc combined tests](rust-2024/rustdoc-doctests.md) + - [Rustdoc nested `include!` change](rust-2024/rustdoc-nested-includes.md) - [Reserved syntax](rust-2024/reserved-syntax.md) - - [Rustdoc doctest nested `include_str!` change](rust-2024/rustdoc-doctests-nested-include-str.md) diff --git a/src/rust-2024/rustdoc-doctests-nested-include-str.md b/src/rust-2024/rustdoc-doctests-nested-include-str.md deleted file mode 100644 index 0ed284ee..00000000 --- a/src/rust-2024/rustdoc-doctests-nested-include-str.md +++ /dev/null @@ -1,64 +0,0 @@ -# Rustdoc doctest nested `include_str!` change - -🚧 The 2024 Edition has not yet been released and hence this section is still "under construction". -More information may be found at . - -## Summary - -When a doctest is included with `include_str!`, if that doctest itself -also uses `include!` / `include_str!` / `include_bytes!`, the path is -resolved relative to the Markdown file, rather than the Rust -source file. - -## Details - -Prior to the 2024 edition, adding documentation with -`#[doc=include_str!("path/file.md")]` didn't carry span information -into the doctests. As a result, if the Markdown file is in a different -directory than the source, any `include!`ed paths need to be relative -to the Rust file. - -For example, consider a library crate with these files: - -* Cargo.toml -* README.md -* src/ - * lib.rs -* examples/ - * data.bin - -Let `lib.rs` contain this: - -```rust,ignore -#![doc=include_str!("../README.md")] -``` - -And assume this `README.md` file: - -````markdown -``` -let _ = include_bytes!("../examples/data.bin"); -// ^^^ notice this -``` -```` - -Prior to the 2024 edition, the path in `README.md` needed to be -relative to the `lib.rs` file. In 2024 and later, it is now relative -to `README.md` iself. - -## Migration - -After migrating, you'll see the following error: - -```text -error: couldn't read `../examples/data.bin`: No such file or directory (os error 2) - --> src/../README.md:2:24 - | -2 | let _ = include_bytes!("../examples/data.bin"); - | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - = note: this error originates in the macro `include_bytes` (in Nightly builds, run with -Z macro-backtrace for more info) -help: there is a file with the same name in a different directory - | -2 | let _ = include_bytes!("examples/data.bin"); - | ~~~~~~~~~~~~~~~~~~~ -``` diff --git a/src/rust-2024/rustdoc-nested-includes.md b/src/rust-2024/rustdoc-nested-includes.md new file mode 100644 index 00000000..301e3745 --- /dev/null +++ b/src/rust-2024/rustdoc-nested-includes.md @@ -0,0 +1,63 @@ +# Rustdoc nested `include!` change + +🚧 The 2024 Edition has not yet been released and hence this section is still "under construction". +More information may be found in the tracking issue at . + +## Summary + +When a doctest is included with `include_str!`, if that doctest itself also uses `include!`, `include_str!`, or `include_bytes!`, the path is resolved relative to the Markdown file, rather than to the Rust source file. + +## Details + +Prior to the 2024 edition, adding documentation with `#[doc=include_str!("path/file.md")]` didn't carry span information into any doctests in that file. As a result, if the Markdown file was in a different directory than the source, any paths included had to be specified relative to the source file. + +For example, consider a library crate with these files: + +- `Cargo.toml` +- `README.md` +- `src/` + - `lib.rs` +- `examples/` + - `data.bin` + +Let's say that `lib.rs` contains this: + +```rust,ignore +#![doc=include_str!("../README.md")] +``` + +And assume this `README.md` file: + +````markdown +``` +let _ = include_bytes!("../examples/data.bin"); +// ^^^ notice this +``` +```` + +Prior to the 2024 edition, the path in `README.md` needed to be relative to the `lib.rs` file. In 2024 and later, it is now relative to `README.md` itself, so we would update `README.md` to: + +````markdown +``` +let _ = include_bytes!("examples/data.bin"); +``` +```` + +## Migration + +There is no automatic migration to convert the paths in affected doctests. If one of your doctests is affected, you'll see an error like this after migrating to the new edition when building your tests: + +```text +error: couldn't read `../examples/data.bin`: No such file or directory (os error 2) + --> src/../README.md:2:24 + | +2 | let _ = include_bytes!("../examples/data.bin"); + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + = note: this error originates in the macro `include_bytes` (in Nightly builds, run with -Z macro-backtrace for more info) +help: there is a file with the same name in a different directory + | +2 | let _ = include_bytes!("examples/data.bin"); + | ~~~~~~~~~~~~~~~~~~~ +``` + +To migrate your doctests to Rust 2024, update any affected paths to be relative to the file containing the doctests.