Merge branch 'summary' into 2024/index

Author: TonalidadeHidrica

src/rust-2021/c-string-literals.md

@@ -0,0 +1,74 @@
+> **Rust Edition Guide は現在 Rust 2024 のアップデート作業に向けて翻訳作業中です。本ページは英語版をコピーしていますが、一部のリンクが動作しないなどの問題が発生する場合があります。問題が発生した場合は、[原文（英語版）](https://doc.rust-lang.org/nightly/edition-guide/introduction.html)をご参照ください。**
+
+# C-string literals
+
+## Summary
+
+- Literals of the form `c"foo"` or `cr"foo"` represent a string of type [`&core::ffi::CStr`][CStr].
+
+[CStr]: ../../core/ffi/struct.CStr.html
+
+## Details
+
+Starting with Rust 1.77, C-strings can be written using C-string literal syntax with the `c` or `cr` prefix.
+
+Previously, it was challenging to properly produce a valid string literal that could interoperate with C APIs which terminate with a NUL byte.
+The [`cstr`] crate was a popular solution, but that required compiling a proc-macro which was quite expensive.
+Now, C-strings can be written directly using literal syntax notation, which will generate a value of type [`&core::ffi::CStr`][CStr] which is automatically terminated with a NUL byte.
+
+```rust,edition2021
+# use core::ffi::CStr;
+
+assert_eq!(c"hello", CStr::from_bytes_with_nul(b"hello\0").unwrap());
+assert_eq!(
+    c"byte escapes \xff work",
+    CStr::from_bytes_with_nul(b"byte escapes \xff work\0").unwrap()
+);
+assert_eq!(
+    c"unicode escapes \u{00E6} work",
+    CStr::from_bytes_with_nul(b"unicode escapes \xc3\xa6 work\0").unwrap()
+);
+assert_eq!(
+    c"unicode characters αβγ encoded as UTF-8",
+    CStr::from_bytes_with_nul(
+        b"unicode characters \xce\xb1\xce\xb2\xce\xb3 encoded as UTF-8\0"
+    )
+    .unwrap()
+);
+assert_eq!(
+    c"strings can continue \
+        on multiple lines",
+    CStr::from_bytes_with_nul(b"strings can continue on multiple lines\0").unwrap()
+);
+```
+
+C-strings do not allow interior NUL bytes (such as with a `\0` escape).
+
+Similar to regular strings, C-strings also support "raw" syntax with the `cr` prefix.
+These raw C-strings do not process backslash escapes which can make it easier to write strings that contain backslashes.
+Double-quotes can be included by surrounding the quotes with the `#` character.
+Multiple `#` characters can be used to avoid ambiguity with internal `"#` sequences.
+
+```rust,edition2021
+assert_eq!(cr"foo", c"foo");
+// Number signs can be used to embed interior double quotes.
+assert_eq!(cr#""foo""#, c"\"foo\"");
+// This requires two #.
+assert_eq!(cr##""foo"#"##, c"\"foo\"#");
+// Escapes are not processed.
+assert_eq!(cr"C:\foo", c"C:\\foo");
+```
+
+See [The Reference] for more details.
+
+[`cstr`]: https://crates.io/crates/cstr
+[The Reference]: ../../reference/tokens.html#c-string-and-raw-c-string-literals
+
+## Migration
+
+Migration is only necessary for macros which may have been assuming a sequence of tokens that looks similar to `c"…"` or `cr"…"`, which previous to the 2021 edition would tokenize as two separate tokens, but in 2021 appears as a single token.
+
+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]: reserved-syntax.md

src/rust-2021/raw-lifetimes.md

@@ -0,0 +1,49 @@
+> **Rust Edition Guide は現在 Rust 2024 のアップデート作業に向けて翻訳作業中です。本ページは英語版をコピーしていますが、一部のリンクが動作しないなどの問題が発生する場合があります。問題が発生した場合は、[原文（英語版）](https://doc.rust-lang.org/nightly/edition-guide/introduction.html)をご参照ください。**
+
+# Raw lifetimes
+
+## Summary
+
+- `'r#ident_or_keyword` is now allowed as a lifetime, which allows using keywords such as `'r#fn`.
+
+## Details
+
+Raw lifetimes are introduced in the 2021 edition to support the ability to migrate to newer editions that introduce new keywords. This is analogous to [raw identifiers] which provide the same functionality for identifiers. For example, the 2024 edition introduced the `gen` keyword. Since lifetimes cannot be keywords, this would cause code that use a lifetime `'gen` to fail to compile. Raw lifetimes allow the migration lint to modify those lifetimes to `'r#gen` which do allow keywords.
+
+In editions prior to 2021, raw lifetimes are parsed as separate tokens. For example `'r#foo` is parsed as three tokens: `'r`, `#`, and `foo`.
+
+[raw identifiers]: ../../reference/identifiers.html#raw-identifiers
+
+## Migration
+
+As a part of the 2021 edition a migration lint, [`rust_2021_prefixes_incompatible_syntax`], has been added in order to aid in automatic migration of Rust 2018 codebases to Rust 2021.
+
+In order to migrate your code to be Rust 2021 Edition compatible, run:
+
+```sh
+cargo fix --edition
+```
+
+Should you want or need to manually migrate your code, migration is fairly straight-forward.
+
+Let's say you have a macro that is defined like so:
+
+```rust
+macro_rules! my_macro {
+    ($a:tt $b:tt $c:tt) => {};
+}
+```
+
+In Rust 2015 and 2018 it's legal for this macro to be called like so with no space between the tokens:
+
+```rust,ignore
+my_macro!('r#foo);
+```
+
+In the 2021 edition, this is now parsed as a single token. In order to call this macro, you must add a space before the identifier like so:
+
+```rust,ignore
+my_macro!('r# foo);
+```
+
+[`rust_2021_prefixes_incompatible_syntax`]: ../../rustc/lints/listing/allowed-by-default.html#rust-2021-prefixes-incompatible-syntax

src/rust-2024/cargo-inherited-default-features.md

@@ -0,0 +1,52 @@
+> **Rust Edition Guide は現在 Rust 2024 のアップデート作業に向けて翻訳作業中です。本ページは英語版をコピーしていますが、一部のリンクが動作しないなどの問題が発生する場合があります。問題が発生した場合は、[原文（英語版）](https://doc.rust-lang.org/nightly/edition-guide/introduction.html)をご参照ください。**
+
+# Cargo: Reject unused inherited default-features
+
+## Summary
+
+- `default-features = false` is no longer allowed in an inherited workspace dependency if the workspace dependency specifies `default-features = true` (or does not specify `default-features`).
+
+## Details
+
+[Workspace inheritance] allows you to specify dependencies in one place (the workspace), and then to refer to those workspace dependencies from within a package.
+There was an inadvertent interaction with how `default-features` is specified that is no longer allowed in the 2024 Edition.
+
+Unless the workspace specifies `default-features = false`, it is no longer allowed to specify `default-features = false` in an inherited package dependency.
+For example, with a workspace that specifies:
+
+```toml
+[workspace.dependencies]
+regex = "1.10.4"
+```
+
+The following is now an error:
+
+```toml
+[package]
+name = "foo"
+version = "1.0.0"
+edition = "2024"
+
+[dependencies]
+regex = { workspace = true, default-features = false }  # ERROR
+```
+
+The reason for this change is to avoid confusion when specifying `default-features = false` when the default feature is already enabled, since it has no effect.
+
+If you want the flexibility of deciding whether or not a dependency enables the default-features of a dependency, be sure to set `default-features = false` in the workspace definition.
+Just beware that if you build multiple workspace members at the same time, the features will be unified so that if one member sets `default-features = true` (which is the default if not explicitly set), the default-features will be enabled for all members using that dependency.
+
+## Migration
+
+When using `cargo fix --edition`, Cargo will automatically update your `Cargo.toml` file to remove `default-features = false` in this situation.
+
+If you would prefer to update your `Cargo.toml` manually, check for any warnings when running a build and remove the corresponding entries.
+Previous editions should display something like:
+
+```text
+warning: /home/project/Cargo.toml: `default-features` is ignored for regex,
+since `default-features` was not specified for `workspace.dependencies.regex`,
+this could become a hard error in the future
+```
+
+[workspace inheritance]: ../../cargo/reference/specifying-dependencies.html#inheriting-a-dependency-from-a-workspace

src/rust-2024/cargo-resolver.md

@@ -0,0 +1,38 @@
+> **Rust Edition Guide は現在 Rust 2024 のアップデート作業に向けて翻訳作業中です。本ページは英語版をコピーしていますが、一部のリンクが動作しないなどの問題が発生する場合があります。問題が発生した場合は、[原文（英語版）](https://doc.rust-lang.org/nightly/edition-guide/introduction.html)をご参照ください。**
+
+# Cargo: Rust-version aware resolver
+
+## 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 = "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.
+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.

src/rust-2024/cargo-table-key-names.md

@@ -0,0 +1,43 @@
+> **Rust Edition Guide は現在 Rust 2024 のアップデート作業に向けて翻訳作業中です。本ページは英語版をコピーしていますが、一部のリンクが動作しないなどの問題が発生する場合があります。問題が発生した場合は、[原文（英語版）](https://doc.rust-lang.org/nightly/edition-guide/introduction.html)をご参照ください。**
+
+# Cargo: Table and key name consistency
+
+## Summary
+
+- Several table and key names in `Cargo.toml` have been removed where there were previously two ways to specify the same thing.
+    - Removed `[project]`; use `[package]` instead.
+    - Removed `default_features`; use `default-features` instead.
+    - Removed `crate_type`; use `crate-type` instead.
+    - Removed `proc_macro`; use `proc-macro` instead.
+    - Removed `dev_dependencies`; use `dev-dependencies` instead.
+    - Removed `build_dependencies`; use `build-dependencies` instead.
+
+## Details
+
+Several table and keys names are no longer allowed in the 2024 Edition.
+There were two ways to specify these tables or keys, and this helps ensure there is only one way to specify them.
+
+Some were due to a change in decisions over time, and some were inadvertent implementation artifacts.
+In order to avoid confusion, and to enforce a single style for specifying these tables and keys, only one variant is now allowed.
+
+For example:
+
+```toml
+[dev_dependencies]
+rand = { version = "0.8.5", default_features = false }
+```
+
+Should be changed to:
+
+```toml
+[dev-dependencies]
+rand = { version = "0.8.5", default-features = false }
+```
+
+Notice that the underscores were changed to dashes for `dev_dependencies` and `default_features`.
+
+## Migration
+
+When using `cargo fix --edition`, Cargo will automatically update your `Cargo.toml` file to use the preferred table and key names.
+
+If you would prefer to update your `Cargo.toml` manually, be sure to go through the list above and make sure only the new forms are used.

src/rust-2024/gen-keyword.md

@@ -0,0 +1,59 @@
+> **Rust Edition Guide は現在 Rust 2024 のアップデート作業に向けて翻訳作業中です。本ページは英語版をコピーしていますが、一部のリンクが動作しないなどの問題が発生する場合があります。問題が発生した場合は、[原文（英語版）](https://doc.rust-lang.org/nightly/edition-guide/introduction.html)をご参照ください。**
+
+# `gen` keyword
+
+## Summary
+
+- `gen` is a [reserved keyword].
+
+[reserved keyword]: ../../reference/keywords.html#reserved-keywords
+
+## Details
+
+The `gen` keyword has been reserved as part of [RFC #3513] to introduce "gen blocks" in a future release of Rust. `gen` blocks will provide a way to make it easier to write certain kinds of iterators. Reserving the keyword now will make it easier to stabilize `gen` blocks before the next edition.
+
+[RFC #3513]: https://rust-lang.github.io/rfcs/3513-gen-blocks.html
+
+## Migration
+
+Introducing the `gen` keyword can cause a problem for any identifiers that are already called `gen`. For example, any variable or function name called `gen` would clash with the new keyword. To overcome this, Rust supports the `r#` prefix for a [raw identifier], which allows identifiers to overlap with keywords.
+
+The [`keyword_idents_2024`] lint will automatically modify any identifier named `gen` to be `r#gen` so that code continues to work on both editions. This lint is part of the `rust-2024-compatibility` lint group, which will automatically be applied when running `cargo fix --edition`. To migrate your code to be Rust 2024 Edition compatible, run:
+
+```sh
+cargo fix --edition
+```
+
+For example, this will change:
+
+```rust
+fn gen() {
+    println!("generating!");
+}
+
+fn main() {
+    gen();
+}
+```
+
+to be:
+
+```rust
+fn r#gen() {
+    println!("generating!");
+}
+
+fn main() {
+    r#gen();
+}
+```
+
+Alternatively, you can manually enable the lint to find places where `gen` identifiers need to be modified to `r#gen`:
+
+```rust
+// Add this to the root of your crate to do a manual migration.
+#![warn(keyword_idents_2024)]
+```
+
+[raw identifier]: ../../reference/identifiers.html#raw-identifiers
+[`keyword_idents_2024`]: ../../rustc/lints/listing/allowed-by-default.html#keyword-idents-2024