diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md index c7e3293e35a..cfe4dfeb59c 100644 --- a/src/doc/rustc/src/SUMMARY.md +++ b/src/doc/rustc/src/SUMMARY.md @@ -84,7 +84,8 @@ - [Profile-guided Optimization](profile-guided-optimization.md) - [Instrumentation-based Code Coverage](instrument-coverage.md) - [Linker-plugin-based LTO](linker-plugin-lto.md) -- [Checking conditional configurations](check-cfg.md) +- [Checking Conditional Configurations](check-cfg.md) + - [Cargo Specifics](check-cfg/cargo-specifics.md) - [Exploit Mitigations](exploit-mitigations.md) - [Symbol Mangling](symbol-mangling/index.md) - [v0 Symbol Format](symbol-mangling/v0.md) diff --git a/src/doc/rustc/src/check-cfg/cargo-specifics.md b/src/doc/rustc/src/check-cfg/cargo-specifics.md new file mode 100644 index 00000000000..bfa60161926 --- /dev/null +++ b/src/doc/rustc/src/check-cfg/cargo-specifics.md @@ -0,0 +1,73 @@ +# Cargo Specifics - Checking Conditional Configurations + + + +This document is intented to summarize the principal ways Cargo interacts with +the `unexpected_cfgs` lint and `--check-cfg` flag. It is not intended to provide +individual details, for that refer to the [`--check-cfg` documentation](../check-cfg.md) and +to the [Cargo book](../../cargo/index.html). + +## Cargo feature + +*See the [`[features]` section in the Cargo book][cargo-features] for more details.* + +With the `[features]` table Cargo provides a mechanism to express conditional compilation and +optional dependencies. Cargo *automatically* declares corresponding cfgs for every feature as +expected. + +`Cargo.toml`: +```toml +[features] +serde = ["dep:serde"] +my_feature = [] +``` + +[cargo-features]: ../../cargo/reference/features.html + +## `check-cfg` in `[lints.rust]` table + + + +*See the [`[lints]` section in the Cargo book][cargo-lints-table] for more details.* + +When using a staticlly known custom config (ie. not dependant on a build-script), Cargo provides +the custom lint config `check-cfg` under `[lints.rust.unexpected_cfgs]`. + +It can be used to set custom static [`--check-cfg`](../check-cfg.md) args, it is mainly useful when +the list of expected cfgs is known is advance. + +`Cargo.toml`: +```toml +[lints.rust] +unexpected_cfgs = { level = "warn", check-cfg = ['cfg(has_foo)'] } +``` + +[cargo-lints-table]: ../../cargo/reference/manifest.html#the-lints-section + +## `cargo::rustc-check-cfg` for `build.rs`/build-script + +*See the [`cargo::rustc-check-cfg` section in the Cargo book][cargo-rustc-check-cfg] for more details.* + +When setting a custom config with [`cargo::rustc-cfg`][cargo-rustc-cfg], Cargo provides the +corollary instruction: [`cargo::rustc-check-cfg`][cargo-rustc-check-cfg] to expect custom configs. + +`build.rs`: +```rust,ignore (cannot-test-this-because-has_foo-isnt-declared) +fn main() { + println!("cargo::rustc-check-cfg=cfg(has_foo)"); + // ^^^^^^^^^^^^^^^^^^^^^^ new with Cargo 1.80 + if has_foo() { + println!("cargo::rustc-cfg=has_foo"); + } +} +``` + +[cargo-rustc-cfg]: ../../cargo/reference/build-scripts.html#rustc-cfg +[cargo-rustc-check-cfg]: ../../cargo/reference/build-scripts.html#rustc-check-cfg