diff --git a/doc/book/src/reference/cargo-targets.md b/doc/book/src/reference/cargo-targets.md index 2675bf1956b..54cccbca40f 100644 --- a/doc/book/src/reference/cargo-targets.md +++ b/doc/book/src/reference/cargo-targets.md @@ -300,9 +300,9 @@ target will be skipped. This is only relevant for the `[[bin]]`, `[[bench]]`, ```toml [features] # ... -postgres = [] -sqlite = [] -tools = [] +postgres = { enables = [] } +sqlite = { enables = [] } +tools = { enables = [] } [[bin]] name = "my-pg-tool" diff --git a/doc/book/src/reference/features.md b/doc/book/src/reference/features.md index 8d29952e95b..3e833d0f233 100644 --- a/doc/book/src/reference/features.md +++ b/doc/book/src/reference/features.md @@ -32,9 +32,19 @@ included: ```toml [features] # Defines a feature named `webp` that does not enable any other features. -webp = [] +webp = { enables = [] } ``` +> [!TIP] +> If only the `enables` key is used, the array syntax can be used instead: +> +> ```toml +> [features] +> webp = [] +> ``` +> +> The table syntax is newer and only available starting with Rust TODO. + With this feature defined, [`cfg` expressions] can be used to conditionally include code to support the requested feature at compile time. For example, inside `lib.rs` of the package could include this: @@ -54,10 +64,10 @@ those other features are enabled, too: ```toml [features] -bmp = [] -png = [] -ico = ["bmp", "png"] -webp = [] +bmp = { enables = [] } +png = { enables = [] } +ico = { enables = ["bmp", "png"] } +webp = { enables = [] } ``` Feature names may include characters from the [Unicode XID standard] (which @@ -84,11 +94,11 @@ changed by specifying the `default` feature: ```toml [features] -default = ["ico", "webp"] -bmp = [] -png = [] -ico = ["bmp", "png"] -webp = [] +default = { enables = ["ico", "webp"] } +bmp = { enables = [] } +png = { enables = [] } +ico = { enables = ["bmp", "png"] } +webp = { enables = [] } ``` When the package is built, the `default` feature is enabled which in turn @@ -131,7 +141,7 @@ like this: ```toml [features] -gif = ["dep:gif"] +gif = { enables = ["dep:gif"] } ``` This means that this dependency will only be included if the `gif` @@ -161,7 +171,7 @@ ravif = { version = "0.6.3", optional = true } rgb = { version = "0.8.25", optional = true } [features] -avif = ["dep:ravif", "dep:rgb"] +avif = { enables = ["dep:ravif", "dep:rgb"] } ``` In this example, the `avif` feature will enable the two listed dependencies. @@ -210,7 +220,7 @@ jpeg-decoder = { version = "0.1.20", default-features = false } [features] # Enables parallel processing support by enabling the "rayon" feature of jpeg-decoder. -parallel = ["jpeg-decoder/rayon"] +parallel = { enables = ["jpeg-decoder/rayon"] } ``` The `"package-name/feature-name"` syntax will also enable `package-name` @@ -232,7 +242,7 @@ serde = { version = "1.0.133", optional = true } rgb = { version = "0.8.25", optional = true } [features] -serde = ["dep:serde", "rgb?/serde"] +serde = { enables = ["dep:serde", "rgb?/serde"] } ``` In this example, enabling the `serde` feature will enable the serde diff --git a/doc/book/src/reference/lints.md b/doc/book/src/reference/lints.md index 82e0d3fb22a..d817ee22e9f 100644 --- a/doc/book/src/reference/lints.md +++ b/doc/book/src/reference/lints.md @@ -230,14 +230,14 @@ Users would expect that a feature tightly coupled to a dependency would match th ```toml [features] -foo_bar = [] +foo_bar = { enables = [] } ``` Should be written as: ```toml [features] -foo-bar = [] +foo-bar = { enables = [] } ``` @@ -296,14 +296,14 @@ Users would expect that a feature tightly coupled to a dependency would match th ```toml [features] -foo-bar = [] +foo-bar = { enables = [] } ``` Should be written as: ```toml [features] -foo_bar = [] +foo_bar = { enables = [] } ``` diff --git a/doc/book/src/reference/semver.md b/doc/book/src/reference/semver.md index 94a80898040..1dc86b176d1 100644 --- a/doc/book/src/reference/semver.md +++ b/doc/book/src/reference/semver.md @@ -2132,7 +2132,7 @@ consequences of enabling the feature. ########################################################### # After [features] -std = [] +std = { enables = [] } ``` #### Major: removing a Cargo feature {#cargo-feature-remove} @@ -2146,7 +2146,7 @@ an error for any project that enabled the feature. ########################################################### # Before [features] -logging = [] +logging = { enables = [] } ########################################################### # After @@ -2172,14 +2172,14 @@ they are expecting that functionality to be available through that feature. ########################################################### # Before [features] -default = ["std"] -std = [] +default = { enables = ["std"] } +std = { enables = [] } ########################################################### # After [features] -default = [] # This may cause packages to fail if they are expecting std to be enabled. -std = [] +default = { enables = [] } # This may cause packages to fail if they are expecting std to be enabled. +std = { enables = [] } ``` #### Possibly-breaking: removing an optional dependency {#cargo-remove-opt-dep} @@ -2219,7 +2219,7 @@ curl = { version = "0.4.31", optional = true } curl = { version = "0.4.31", optional = true } [features] -networking = ["dep:curl"] +networking = { enables = ["dep:curl"] } ########################################################### # After @@ -2228,7 +2228,7 @@ networking = ["dep:curl"] hyper = { version = "0.14.27", optional = true } [features] -networking = ["dep:hyper"] +networking = { enables = ["dep:hyper"] } ``` Mitigation strategies: diff --git a/doc/book/src/reference/specifying-dependencies.md b/doc/book/src/reference/specifying-dependencies.md index 7d2e8146fe7..041fbd1f5ce 100644 --- a/doc/book/src/reference/specifying-dependencies.md +++ b/doc/book/src/reference/specifying-dependencies.md @@ -461,7 +461,7 @@ foo = { version = "1.0", optional = true } bar = { version = "1.0", optional = true } [features] -fancy-feature = ["foo", "bar"] +fancy-feature = { enables = ["foo", "bar"] } ``` The same applies to `cfg(debug_assertions)`, `cfg(test)` and `cfg(proc_macro)`. @@ -634,7 +634,7 @@ following to the above manifest: ```toml [features] -log-debug = ['bar/log-debug'] # using 'foo/log-debug' would be an error! +log-debug = { enables = ['bar/log-debug'] } # using 'foo/log-debug' would be an error! ``` ## Inheriting a dependency from a workspace diff --git a/src/diagnostics/rules/non_kebab_case_features.rs b/src/diagnostics/rules/non_kebab_case_features.rs index f49f7f91b27..2e378d3545f 100644 --- a/src/diagnostics/rules/non_kebab_case_features.rs +++ b/src/diagnostics/rules/non_kebab_case_features.rs @@ -44,14 +44,14 @@ Users would expect that a feature tightly coupled to a dependency would match th ```toml [features] -foo_bar = [] +foo_bar = { enables = [] } ``` Should be written as: ```toml [features] -foo-bar = [] +foo-bar = { enables = [] } ``` "#, ), diff --git a/src/diagnostics/rules/non_snake_case_features.rs b/src/diagnostics/rules/non_snake_case_features.rs index ea6f75f8f57..89584182ecc 100644 --- a/src/diagnostics/rules/non_snake_case_features.rs +++ b/src/diagnostics/rules/non_snake_case_features.rs @@ -44,14 +44,14 @@ Users would expect that a feature tightly coupled to a dependency would match th ```toml [features] -foo-bar = [] +foo-bar = { enables = [] } ``` Should be written as: ```toml [features] -foo_bar = [] +foo_bar = { enables = [] } ``` "#, ),