Auto merge of #13884 - Urgau:check-cfg-local-build-scripts, r=epage

Add local-only build scripts example in check-cfg docs

This PR adds an example about creating/having "local-only" build scripts in the check-cfg docs.

r? `@weihanglo`
cc `@epage`
This commit is contained in:
bors 2024-05-08 13:40:59 +00:00
commit 6914ead3bf
1 changed files with 26 additions and 0 deletions

View File

@ -292,6 +292,32 @@ if foo_bar_condition {
}
```
##### Example of local-only `build.rs`/build script
Build scripts can impose costs on downstream users, and crate authors who wish to avoid
this can use "local-only" build scripts, which are active locally but not packaged in the
distributed package. Completly removing the cost from downstream users.
The way to achieved this, is by excluding the `build.rs` in the `Cargo.toml` with the
`exclude` key:
```diff
[package]
name = "foo"
version = "0.1.0"
+ exclude = ["build.rs"]
```
*`build.rs`:*
```rust
fn main() {
// Warning: build.rs is not published to crates.io.
println!("cargo::rerun-if-changed=build.rs");
println!("cargo::rustc-check-cfg=cfg(foo)");
}
```
For a more complete example see in the [build script examples][build-script-examples] page
the [conditional compilation][conditional-compilation-example] example.