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.

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}"

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.