From f703262abc36663d7b9452311cd2767b7710093d Mon Sep 17 00:00:00 2001 From: Eric Huss Date: Tue, 21 May 2024 10:17:08 -0700 Subject: [PATCH] 2024: Document cargo changes --- src/SUMMARY.md | 2 + .../cargo-inherited-default-features.md | 52 +++++++++++++++++++ .../cargo-remove-implicit-features.md | 41 +++++++++++++-- src/rust-2024/cargo-table-key-names.md | 43 +++++++++++++++ 4 files changed, 135 insertions(+), 3 deletions(-) create mode 100644 src/rust-2024/cargo-inherited-default-features.md create mode 100644 src/rust-2024/cargo-table-key-names.md diff --git a/src/SUMMARY.md b/src/SUMMARY.md index e9e9e51f..33c3ac51 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -44,4 +44,6 @@ - [Disallow references to `static mut`](rust-2024/static-mut-reference.md) - [Public/private dependencies](rust-2024/public-private-dependencies.md) - [Cargo: Remove implicit features](rust-2024/cargo-remove-implicit-features.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-inherited-default-features.md b/src/rust-2024/cargo-inherited-default-features.md new file mode 100644 index 00000000..61a9b860 --- /dev/null +++ b/src/rust-2024/cargo-inherited-default-features.md @@ -0,0 +1,52 @@ +# Cargo: Reject unused inherited default-features + +🚧 The 2024 Edition has not yet been released and hence this section is still "under construction". + +## 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 diff --git a/src/rust-2024/cargo-remove-implicit-features.md b/src/rust-2024/cargo-remove-implicit-features.md index f6898354..892528e5 100644 --- a/src/rust-2024/cargo-remove-implicit-features.md +++ b/src/rust-2024/cargo-remove-implicit-features.md @@ -2,11 +2,46 @@ 🚧 The 2024 Edition has not yet been released and hence this section is still "under construction". -This feature has not yet been implemented. -More information may be found in the tracking issue at . - ## Summary +- Optional dependencies must now be explicitly specified in the `[features]` table. + ## Details +In previous editions, when an [optional dependency] is specified, Cargo would automatically add an implicit [feature] of the same name as the dependency. For example: + +```toml +[dependencies] +jpeg-decoder = { version = "0.3.1", optional = true } +``` + +This would automatically add a feature `jpeg-decoder = ["dep:jpeg-decoder"]` to provide a way to enable the dependency. +The `dep:` entries are specific syntax for referring to optional dependencies. +This implicit feature is only added if `"dep:jpeg-decoder"` is not specified in any other feature. + +In the 2024 Edition, this implicit feature is no longer added, and you are required to explicitly specify the dependency in the `[features]` table. +For example, instead of exposing the particular internal name of some dependency, you may consider using a more general term for the feature name: + +```toml +[features] +graphics = ["dep:jpeg-decoder"] +``` + +`cargo add --optional ` automatically adds a feature for the dependency to the `[features]` table if it isn't already there. + +### Motivation + +A reason for requiring this to be explicit is that it encourages a conscious decision about the public exposure of the feature name, and makes it clearer when reading the `[features]` table which features exist. +This can help avoid tying the implementation details (the dependency names) to the public set of feature names. + +Also, removing features is a [SemVer incompatible change][semver], which may not be obvious when removing an optional dependency that you thought was private. + ## Migration + +When using `cargo fix --edition`, Cargo will automatically update your `Cargo.toml` file to include the implicit features if necessary. + +If you would prefer to update your `Cargo.toml` manually, add a `foo = ["dep:foo"]` entry for each optional dependency named *foo* if `dep:foo` is not already specified anywhere in the `[features]` table. + +[optional dependency]: ../../cargo/reference/features.html#optional-dependencies +[feature]: ../../cargo/reference/features.html +[semver]: ../../cargo/reference/semver.html#cargo-feature-remove diff --git a/src/rust-2024/cargo-table-key-names.md b/src/rust-2024/cargo-table-key-names.md new file mode 100644 index 00000000..4c8e93bf --- /dev/null +++ b/src/rust-2024/cargo-table-key-names.md @@ -0,0 +1,43 @@ +# Cargo: Table and key name consistency + +🚧 The 2024 Edition has not yet been released and hence this section is still "under construction". + +## Summary + +- Several table and key names in `Cargo.toml` have been removed where there was previously two ways to specify it. + - 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.