Skip to content

doc: improve documentation on using cfg values with build scripts#16671

Merged
arlosi merged 3 commits intorust-lang:masterfrom
Vivekk-11:docs/cfg-values-build-scripts
Feb 24, 2026
Merged

doc: improve documentation on using cfg values with build scripts#16671
arlosi merged 3 commits intorust-lang:masterfrom
Vivekk-11:docs/cfg-values-build-scripts

Conversation

@Vivekk-11
Copy link
Copy Markdown
Contributor

@Vivekk-11 Vivekk-11 commented Feb 24, 2026

What does this PR try to resolve?

Fixes #12198

This PR improves documentation on using cfg values with build scripts. Currently, the docs don't clearly explain how to properly read configuration values in a build script, leading to common mistakes when cross-compiling.

The key issue is that developers often use cfg! or #[cfg] in build scripts to check target configuration, but these actually check the host platform (where the build script runs), not the target platform being compiled for.

Changes:

  • build-scripts.md: Added a note warning about cfg! vs CARGO_CFG_* and recommending the build-rs crate
  • environment-variables.md: Added a tip in the CARGO_CFG_* section about using build-rs and the host/target distinction
  • build-script-examples.md: Added a new "Reading target configuration" section with a practical example

How to test and review this PR?

  1. Build the documentation locally:
   cd src/doc
   mdbook serve --open

  1. Review the following pages:

    • reference/build-scripts.html - Check the new note in "Inputs to the Build Script"
    • reference/environment-variables.html - Check the new tip under CARGO_CFG_*
    • reference/build-script-examples.html - Check the new "Reading target configuration" section

  2. Verify all links work correctly (the build-rs crate links and cross-references)

@rustbot rustbot added A-documenting-cargo-itself Area: Cargo's documentation S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. labels Feb 24, 2026
@rustbot
Copy link
Copy Markdown
Collaborator

rustbot commented Feb 24, 2026

r? @weihanglo

rustbot has assigned @weihanglo.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

Why was this reviewer chosen?

The reviewer was selected based on:

  • Owners of files modified in this PR: @ehuss, @epage, @weihanglo
  • @ehuss, @epage, @weihanglo expanded to ehuss, epage, weihanglo
  • Random selection from ehuss, epage, weihanglo

arlosi
arlosi approved these changes Feb 24, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@arlosi arlosi left a comment •
edited by rustbot
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks!

View changes since this review

@arlosi arlosi added this pull request to the merge queue Feb 24, 2026
Merged via the queue into rust-lang:master with commit 9ef4e96 Feb 24, 2026
29 checks passed
@rustbot rustbot removed the S-waiting-on-review Status: Awaiting review from the assignee but also interested parties. label Feb 24, 2026
arlosi added a commit to arlosi/rust that referenced this pull request Feb 25, 2026
@arlosi
Update cargo submodule
8581df5 
8 commits in 8cc0cb136772b8f54eafe0d163fcb7226a06af0c..f298b8c82da0cba538516b45b04a480fc501d4c0
2026-02-17 12:16:26 +0000 to 2026-02-24 21:59:20 +0000
- fix(host-config): fix panic when cross-compiling with host-config (rust-lang/cargo#16674)
- doc: improve documentation on using cfg values with build scripts (rust-lang/cargo#16671)
- Fix typo in cargo-yank docs (rust-lang/cargo#16656)
- fix(job_queue): Handle Clippy CLI arguments in `fix` message (rust-lang/cargo#16652)
- Add a test for fingerprint checking when a symlink target changes (rust-lang/cargo#16661)
- Fix parallel locking when `-Zfine-grain-locking` is enabled (rust-lang/cargo#16659)
- fix(cli): Remove `--lockfile-path` (rust-lang/cargo#16621)
- test(build-std): Update error message (rust-lang/cargo#16658)
@arlosi arlosi mentioned this pull request Feb 25, 2026
Merged
rust-bors bot pushed a commit to rust-lang/rust that referenced this pull request Feb 26, 2026
@bors
Auto merge of #153067 - arlosi:update-cargo, r=ehuss
69b7853 
Update cargo submodule

8 commits in 8cc0cb136772b8f54eafe0d163fcb7226a06af0c..f298b8c82da0cba538516b45b04a480fc501d4c0 2026-02-17 12:16:26 +0000 to 2026-02-24 21:59:20 +0000
- fix(host-config): fix panic when cross-compiling with host-config (rust-lang/cargo#16674)
- doc: improve documentation on using cfg values with build scripts (rust-lang/cargo#16671)
- Fix typo in cargo-yank docs (rust-lang/cargo#16656)
- fix(job_queue): Handle Clippy CLI arguments in `fix` message (rust-lang/cargo#16652)
- Add a test for fingerprint checking when a symlink target changes (rust-lang/cargo#16661)
- Fix parallel locking when `-Zfine-grain-locking` is enabled (rust-lang/cargo#16659)
- fix(cli): Remove `--lockfile-path` (rust-lang/cargo#16621)
- test(build-std): Update error message (rust-lang/cargo#16658)
@rustbot rustbot added this to the 1.95.0 milestone Feb 26, 2026
RalfJung pushed a commit to RalfJung/miri that referenced this pull request Feb 26, 2026
@bors
Auto merge of #153067 - arlosi:update-cargo, r=ehuss
d6e458c 
Update cargo submodule

8 commits in 8cc0cb136772b8f54eafe0d163fcb7226a06af0c..f298b8c82da0cba538516b45b04a480fc501d4c0 2026-02-17 12:16:26 +0000 to 2026-02-24 21:59:20 +0000
- fix(host-config): fix panic when cross-compiling with host-config (rust-lang/cargo#16674)
- doc: improve documentation on using cfg values with build scripts (rust-lang/cargo#16671)
- Fix typo in cargo-yank docs (rust-lang/cargo#16656)
- fix(job_queue): Handle Clippy CLI arguments in `fix` message (rust-lang/cargo#16652)
- Add a test for fingerprint checking when a symlink target changes (rust-lang/cargo#16661)
- Fix parallel locking when `-Zfine-grain-locking` is enabled (rust-lang/cargo#16659)
- fix(cli): Remove `--lockfile-path` (rust-lang/cargo#16621)
- test(build-std): Update error message (rust-lang/cargo#16658)
github-actions bot pushed a commit to rust-lang/rust-analyzer that referenced this pull request Mar 2, 2026
@bors
Auto merge of #153067 - arlosi:update-cargo, r=ehuss
d5444f5 
Update cargo submodule

8 commits in 8cc0cb136772b8f54eafe0d163fcb7226a06af0c..f298b8c82da0cba538516b45b04a480fc501d4c0 2026-02-17 12:16:26 +0000 to 2026-02-24 21:59:20 +0000
- fix(host-config): fix panic when cross-compiling with host-config (rust-lang/cargo#16674)
- doc: improve documentation on using cfg values with build scripts (rust-lang/cargo#16671)
- Fix typo in cargo-yank docs (rust-lang/cargo#16656)
- fix(job_queue): Handle Clippy CLI arguments in `fix` message (rust-lang/cargo#16652)
- Add a test for fingerprint checking when a symlink target changes (rust-lang/cargo#16661)
- Fix parallel locking when `-Zfine-grain-locking` is enabled (rust-lang/cargo#16659)
- fix(cli): Remove `--lockfile-path` (rust-lang/cargo#16621)
- test(build-std): Update error message (rust-lang/cargo#16658)
makai410 pushed a commit to makai410/rustc_public that referenced this pull request Mar 19, 2026
@bors
Auto merge of #153067 - arlosi:update-cargo, r=ehuss
121becd 
Update cargo submodule

8 commits in 8cc0cb136772b8f54eafe0d163fcb7226a06af0c..f298b8c82da0cba538516b45b04a480fc501d4c0 2026-02-17 12:16:26 +0000 to 2026-02-24 21:59:20 +0000
- fix(host-config): fix panic when cross-compiling with host-config (rust-lang/cargo#16674)
- doc: improve documentation on using cfg values with build scripts (rust-lang/cargo#16671)
- Fix typo in cargo-yank docs (rust-lang/cargo#16656)
- fix(job_queue): Handle Clippy CLI arguments in `fix` message (rust-lang/cargo#16652)
- Add a test for fingerprint checking when a symlink target changes (rust-lang/cargo#16661)
- Fix parallel locking when `-Zfine-grain-locking` is enabled (rust-lang/cargo#16659)
- fix(cli): Remove `--lockfile-path` (rust-lang/cargo#16621)
- test(build-std): Update error message (rust-lang/cargo#16658)
makai410 pushed a commit to makai410/rustc_public that referenced this pull request Mar 19, 2026
@bors
Auto merge of #153067 - arlosi:update-cargo, r=ehuss
628d43a 
Update cargo submodule

8 commits in 8cc0cb136772b8f54eafe0d163fcb7226a06af0c..f298b8c82da0cba538516b45b04a480fc501d4c0 2026-02-17 12:16:26 +0000 to 2026-02-24 21:59:20 +0000
- fix(host-config): fix panic when cross-compiling with host-config (rust-lang/cargo#16674)
- doc: improve documentation on using cfg values with build scripts (rust-lang/cargo#16671)
- Fix typo in cargo-yank docs (rust-lang/cargo#16656)
- fix(job_queue): Handle Clippy CLI arguments in `fix` message (rust-lang/cargo#16652)
- Add a test for fingerprint checking when a symlink target changes (rust-lang/cargo#16661)
- Fix parallel locking when `-Zfine-grain-locking` is enabled (rust-lang/cargo#16659)
- fix(cli): Remove `--lockfile-path` (rust-lang/cargo#16621)
- test(build-std): Update error message (rust-lang/cargo#16658)
makai410 pushed a commit to makai410/rustc_public that referenced this pull request Mar 27, 2026
@bors
Auto merge of #153067 - arlosi:update-cargo, r=ehuss
faeadef 
Update cargo submodule

8 commits in 8cc0cb136772b8f54eafe0d163fcb7226a06af0c..f298b8c82da0cba538516b45b04a480fc501d4c0 2026-02-17 12:16:26 +0000 to 2026-02-24 21:59:20 +0000
- fix(host-config): fix panic when cross-compiling with host-config (rust-lang/cargo#16674)
- doc: improve documentation on using cfg values with build scripts (rust-lang/cargo#16671)
- Fix typo in cargo-yank docs (rust-lang/cargo#16656)
- fix(job_queue): Handle Clippy CLI arguments in `fix` message (rust-lang/cargo#16652)
- Add a test for fingerprint checking when a symlink target changes (rust-lang/cargo#16661)
- Fix parallel locking when `-Zfine-grain-locking` is enabled (rust-lang/cargo#16659)
- fix(cli): Remove `--lockfile-path` (rust-lang/cargo#16621)
- test(build-std): Update error message (rust-lang/cargo#16658)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@arlosi arlosi arlosi approved these changes

Assignees

@weihanglo weihanglo

Labels

A-documenting-cargo-itself Area: Cargo's documentation

Projects

None yet

Milestone

1.95.0

Development

Successfully merging this pull request may close these issues.

Improve documentation on using cfg values with build scripts

4 participants

@Vivekk-11 @rustbot @arlosi @weihanglo