From 3c809b291a88347ea5b9e185e0306e2b28c085ea Mon Sep 17 00:00:00 2001 From: Urgau Date: Wed, 8 May 2024 15:08:45 +0200 Subject: [PATCH] Add local-only build scripts example in check-cfg docs --- src/doc/src/reference/build-scripts.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/src/doc/src/reference/build-scripts.md b/src/doc/src/reference/build-scripts.md index 1f1fd0041dc..a540de7a373 100644 --- a/src/doc/src/reference/build-scripts.md +++ b/src/doc/src/reference/build-scripts.md @@ -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.