shadow-rs: build-time information stored in your rust project. (binary, lib, cdylib and dylib)

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

• Cargo.toml project version
• Dependency information
• The Git commit that produced the build artifact (binary)
• What version of the rust toolchain was used in compilation
• The build variant, e.g. debug or release

And more!

You can use this tool to check in production exactly where a binary came from and how it was built.

Notice ⚠️

The build.rs is not rebuilt every-time if the repository has been history builld. The recommended way is to run cargo clean first, then execute cargo build, or use a CI/CD pipeline tool to help you perform this operation. For more details, see https://github.com/baoyachi/shadow-rs/issues/95.

Full 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 simple demonstration of how shadow-rs might be used to provide build-time information at run-time and add a custom hook.
• Built-in function:examples.

Setup Guide

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:

• with add custom const or fn see:example_shadow_hook

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

3) Integrate shadow

In your rust file (e.g. *.rs):

use shadow_rs::shadow;

shadow!(build);

Notice that the shadow! macro is provided the identifier build. You can now use this identifier to access build-time information.

4) Done. Use shadow.

fn main() {

    //shadow-rs built in function  
    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)'

    //shadow-rs built in const   
    println!("{}", build::VERSION);           // the version (description binary detail information)
    println!("{}", build::CLAP_LONG_VERSION); // usually used by clap crates version() (description binary detail information)
    println!("{}", build::PKG_VERSION);         // current package version. e.g. '1.3.15-beta2'  
    println!("{}", build::PKG_VERSION_MAJOR);   //current package major version. e.g. '1'  
    println!("{}", build::PKG_VERSION_MINOR);   //current package minor version. e.g. '3'  
    println!("{}", build::PKG_VERSION_PATCH);   //current package minor version. e.g. '15'  
    println!("{}", build::PKG_VERSION_PRE);     //current package minor version. e.g. 'beta2'  
    println!("{}", build::BRANCH);              // the branch, e.g. 'master'
    println!("{}", build::TAG);                 // the tag, e.g. 'v1.0.0'
    println!("{}", build::SHORT_COMMIT);        // short commit hash, e.g. '8405e28e'
    println!("{}", build::COMMIT_HASH);         // full commit hash, e.g. '8405e28e64080a09525a6cf1b07c22fcaf71a5c5'
    println!("{}", build::COMMIT_DATE);         // commit date, e.g. '2021-08-04 12:34:03 +00:00'
    println!("{}", build::COMMIT_DATE_2822);    // commit date, e.g. 'Thu, 24 Jun 2021 21:33:59 +0800'
    println!("{}", build::COMMIT_DATE_3339);    // commit date, e.g. '2021-06-24T21:33:59.972494+08:00'
    println!("{}", build::COMMIT_AUTHOR);       // commit author, e.g. 'baoyachi'
    println!("{}", build::COMMIT_EMAIL);        // commit email, e.g. 'example@gmail.com'

    println!("{}", build::BUILD_OS);            // the OS that built the binary, e.g. 'macos-x86_64'
    println!("{}", build::BUILD_TARGET);        // the OS target that built the binary, e.g. 'x86_64-apple-darwin'
    println!("{}", build::BUILD_TARGET_ARCH);   // the OS target arch that built the binary, e.g. 'x86_64'
    println!("{}", build::RUST_VERSION);        // rustc version e.g. 'rustc 1.45.0 (5c1f21c3b 2020-07-13)'
    println!("{}", build::RUST_CHANNEL);        // rust toolchain e.g. 'stable-x86_64-apple-darwin (default)'
    println!("{}", build::CARGO_VERSION);       // cargo version e.g. 'cargo 1.45.0 (744bd1fbb 2020-06-15)'
    println!("{}", build::CARGO_TREE);          // e.g. the output of '$ cargo tree'
    println!("{}", build::CARGO_MANIFEST_DIR);  // e.g. /User/baoyachi/shadow-rs/

    println!("{}", build::PROJECT_NAME);        // your project name, e.g. 'shadow-rs'
    // Time respects SOURCE_DATE_EPOCH environment variable - see below
    println!("{}", build::BUILD_TIME);          // time when start build occurred, e.g. '2020-08-16 14:50:25'
    println!("{}", build::BUILD_TIME_2822);     // time when start build occurred by rfc2822, e.g. 'Thu, 24 Jun 2021 21:33:59 +0800'
    println!("{}", build::BUILD_TIME_3339);     // time when start build occurred by rfc3339, e.g. '2021-06-24T21:33:59.972494+08:00'
    println!("{}", build::BUILD_RUST_CHANNEL);  // e.g. 'debug'
    println!("{}", build::GIT_CLEAN);           // e.g. 'true'
    println!("{}", build::GIT_STATUS_FILE);     // e.g. '* 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 Example

You also can use shadow-rs with clap.

Constants and functions in table

shadow-rs built in function.

• how to use 👉 : examples

shadow-rs support build const,function.

• how to use 👉 : shadow_example

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.