From 1cf18a77bb9af8bc35f2605b733d6db0cf68dfd0 Mon Sep 17 00:00:00 2001
From: Urgau <urgau@numericable.fr>
Date: Thu, 16 May 2024 21:40:01 +0200
Subject: [PATCH] Add Cargo specific doc regarding his interaction with
 `--check-cfg`

---
 src/doc/rustc/src/SUMMARY.md                  |  1 +
 .../rustc/src/check-cfg/cargo-specifics.md    | 96 +++++++++++++++++++
 2 files changed, 97 insertions(+)
 create mode 100644 src/doc/rustc/src/check-cfg/cargo-specifics.md

diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md
index c7e3293e35ade..c4dffdc0b8c91 100644
--- a/src/doc/rustc/src/SUMMARY.md
+++ b/src/doc/rustc/src/SUMMARY.md
@@ -85,6 +85,7 @@
 - [Instrumentation-based Code Coverage](instrument-coverage.md)
 - [Linker-plugin-based LTO](linker-plugin-lto.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 0000000000000..c3cb113e20733
--- /dev/null
+++ b/src/doc/rustc/src/check-cfg/cargo-specifics.md
@@ -0,0 +1,96 @@
+# Cargo specifics - Checking conditional configurations
+
+<!--
+This page is the canonical place for describing the interaction between Cargo
+and --check-cfg, it is placed in the rustc book because --check-cfg and the
+unexpected_cfgs are owned by rustc, not Cargo. T-Cargo also considers
+`[lints.rust.unexpected_cfgs.check-cfg]` to be an implementation detail and
+is therefor not documented in Cargo.
+-->
+
+*See the Cargo announcement [blog post][check-cfg-blog-post] for more a global view of the feature.*
+
+> 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 always enables [checking conditional configurations](../check-cfg.md) with Rust 1.80 and upper.
+
+This is to help with verifying that the crate is correctly handling conditional compilation for
+different target platforms or features. It ensures that the cfg settings are consistent between
+what is intended and what is used, helping to catch potential bugs or errors early in the
+development process.
+
+This document express different ways users can declare expected cfgs, and in particular for
+custom configs[^1] with Cargo as the build system.
+
+[^1]: In Cargo point-of-view: a custom cfg is one that is neither defined by `rustc` nor by a Cargo
+feature. Think of `tokio_unstable`, `has_foo`, ... but not `feature = "lasers"`, `unix` or
+`debug_assertions`
+
+[check-cfg-blog-post]: https://blog.rust-lang.org/2024/05/06/check-cfg.html
+
+## Cargo feature
+
+*See the [`[features]` section in the Cargo book][cargo-features] for more details.*
+
+With the `[features]` table Cargo provide a mechanism to express conditional compilation and
+optional dependencies. Cargo *automatically* declares 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 custom config not set via 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)'] }
+
+# or
+
+[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
+corrolary instruction: [`cargo::rustc-check-cfg`][cargo-rustc-check-cfg] to expect custom configs.
+
+`build.rs`:
+```rust
+fn main() {
+    println!("cargo::rustc-check-cfg=cfg(has_foo)");
+    //        ^^^^^^^^^^^^^^^^^^^^^^ new with Cargo 1.80
+    if has_foo() {
+        println!("cargo::rustc-cfg=has_foo");
+    }
+}
+```
+
+> Each `cargo::rustc-cfg` should have an accompanying **unconditional** `cargo::rustc-check-cfg`
+> directive to avoid warnings like this: `unexpected cfg condition name: has_foo`.
+
+[cargo-rustc-cfg]: ../../../cargo/reference/build-scripts.html#rustc-cfg
+[cargo-rustc-check-cfg]: ../../../cargo/reference/build-scripts.html#rustc-check-cfg