shadow-rs: Build-time information stored in your Rust project (binary, lib, cdylib, dylib).

shadow-rs allows you to access properties of the build process and environment at runtime, including:

• Cargo.toml information, such as the project version
• Dependency information
• Git information, such as the commit that produced the build artifact
• What version of the Rust toolchain was used in compilation
• The build variant, e.g. debug or release
• ... And more!

You can use this crate to programmatically check where a binary came from and how it was built.

Currently, integration into wasm is also supported. For detailed settings, please refer to the link example_wasm.

Note on Caching

shadow-rs build information is not always rebuilt when you build a project. shadow-rs outputs several hints to Cargo in order to force rebuilds when required, but this does not always work. You can enforce up-to-date build information by running cargo clean before the build, or use a CI/CD pipeline tool. For more details, see https://github.com/baoyachi/shadow-rs/issues/95.

Examples

• Check out the example_shadow for a simple demonstration of how shadow-rs might be used to provide build-time information at run-time.
• Check out the example_shadow_hook for a demonstration of how custom hooks can be used to add extra information to shadow-rs's output.
• Check out the builtin_fn example for a simple demonstration of the built-in functions that shadow-rs provides.

Setup

1) Modify Cargo.toml fields

Modify your Cargo.toml like so:

[package]
build = "build.rs"

[dependencies]
shadow-rs = "{latest version}"

[build-dependencies]
shadow-rs = "{latest version}"

About build = "build.rs",this is an optional addition where, by default, build points to the build.rs file. It is recommended to use it as such. However, if your build script file is not named build.rs, please manually specify it. For example: build = "gen.rs".

2) Create build.rs file

Now in the root of your project (same directory as Cargo.toml) add a file build.rs:

fn main() -> shadow_rs::SdResult<()> {
    shadow_rs::new()
}

If you want to exclude some build constants, you can use [new_deny] instead of [new].

3) Integrate Shadow

In your main Rust file (usually main.rs or lib.rs), add this:

use shadow_rs::shadow;

shadow!(build);

The shadow! macro uses the given identifier to create a module with that name.

4) Use Shadow Constants

You can now use the module defined with shadow! to access build-time information.

fn main() {
    println!("debug:{}", shadow_rs::is_debug()); // check if this is a debug build. e.g 'true/false'
    println!("branch:{}", shadow_rs::branch()); // get current project branch. e.g 'master/develop'
    println!("tag:{}", shadow_rs::tag()); // get current project tag. e.g 'v1.3.5'
    println!("git_clean:{}", shadow_rs::git_clean()); // get current project clean. e.g 'true/false'
    println!("git_status_file:{}", shadow_rs::git_status_file()); // get current project statue file. e.g '  * examples/builtin_fn.rs (dirty)'

    println!("{}", build::VERSION); //print version const
    println!("{}", build::CLAP_LONG_VERSION); //print CLAP_LONG_VERSION const
    println!("{}", build::BRANCH); //master
    println!("{}", build::SHORT_COMMIT); //8405e28e
    println!("{}", build::COMMIT_HASH); //8405e28e64080a09525a6cf1b07c22fcaf71a5c5
    println!("{}", build::COMMIT_DATE); //2021-08-04 12:34:03 +00:00
    println!("{}", build::COMMIT_AUTHOR); //baoyachi
    println!("{}", build::COMMIT_EMAIL); //xxx@gmail.com

    println!("{}", build::BUILD_OS); //macos-x86_64
    println!("{}", build::RUST_VERSION); //rustc 1.45.0 (5c1f21c3b 2020-07-13)
    println!("{}", build::RUST_CHANNEL); //stable-x86_64-apple-darwin (default)
    println!("{}", build::CARGO_VERSION); //cargo 1.45.0 (744bd1fbb 2020-06-15)
    println!("{}", build::PKG_VERSION); //0.3.13
    println!("{}", build::CARGO_TREE); //like command:cargo tree
    println!("{}", build::CARGO_MANIFEST_DIR); // /User/baoyachi/shadow-rs/ |

    println!("{}", build::PROJECT_NAME); //shadow-rs
    println!("{}", build::BUILD_TIME); //2020-08-16 14:50:25
    println!("{}", build::BUILD_RUST_CHANNEL); //debug
    println!("{}", build::GIT_CLEAN); //false
    println!("{}", build::GIT_STATUS_FILE); //* src/lib.rs (dirty)
}

Reproducibility

This tool includes the current time in the binary which would normally make it non-reproducible. However, it respects the SOURCE_DATE_EPOCH variable - if set to a Unix timestamp it will override the value of build time.

Clap

You can also use shadow-rs to provide information to command-line interface crates such as clap. An example of this can be found in example_shadow.

List of Constants and Functions

Functions

Constants

If you have any questions, please create an issue so we may improve the documentation where it may be unclear.

People using shadow-rs

If you are using shadow-rs, please tell me! Or instead, consider making a note here: Shadow Users Collection.