Crate shadow_rs

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.

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

Optional Dependencies:

• git2 (enabled by default) — Use libgit2 as a backend for git operations
• tzdb (enabled by default) — Better support for querying the local system time

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

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.

For the user guide and further documentation, see the README of shadow-rs.

List of Generated Output Constants

All constants produced by shadow-rs are documented in the module created with shadow!, so rustdoc and your IDE will pick it up.

pub const PKG_VERSION: &str = "1.3.8-beta3";
pub const PKG_VERSION_MAJOR: &str = "1";
pub const PKG_VERSION_MINOR: &str = "3";
pub const PKG_VERSION_PATCH: &str = "8";
pub const PKG_VERSION_PRE: &str = "beta3";
pub const RUST_VERSION: &str = "rustc 1.45.0 (5c1f21c3b 2020-07-13)";
pub const BUILD_RUST_CHANNEL: &str = "debug";
pub const COMMIT_AUTHOR: &str = "baoyachi";
pub const BUILD_TIME: &str = "2020-08-16 13:48:52";
pub const BUILD_TIME_2822: &str = "Thu, 24 Jun 2021 21:44:14 +0800";
pub const BUILD_TIME_3339: &str = "2021-06-24T15:53:55+08:00";
pub const COMMIT_DATE: &str = "2021-08-04 12:34:03 +00:00";
pub const COMMIT_DATE_2822: &str = "Thu, 24 Jun 2021 21:44:14 +0800";
pub const COMMIT_DATE_3339: &str = "2021-06-24T21:44:14.473058+08:00";
pub const COMMIT_EMAIL: &str = "xxx@gmail.com";
pub const PROJECT_NAME: &str = "shadow-rs";
pub const RUST_CHANNEL: &str = "stable-x86_64-apple-darwin (default)";
pub const BRANCH: &str = "master";
pub const CARGO_LOCK: &str = r#"
├── chrono v0.4.19
│   ├── libc v0.2.80
│   ├── num-integer v0.1.44
│   │   └── num-traits v0.2.14
│   │       [build-dependencies]
│   │       └── autocfg v1.0.1
│   ├── num-traits v0.2.14 (*)
│   └── time v0.1.44
│       └── libc v0.2.80
└── git2 v0.13.12
├── log v0.4.11
│   └── cfg-if v0.1.10
└── url v2.2.0
├── form_urlencoded v1.0.0
│   └── percent-encoding v2.1.0
└── percent-encoding v2.1.0"#;
pub const CARGO_VERSION: &str = "cargo 1.45.0 (744bd1fbb 2020-06-15)";
pub const BUILD_OS: &str = "macos-x86_64";
pub const COMMIT_HASH: &str = "386741540d73c194a3028b96b92fdeb53ca2788a";
pub const GIT_CLEAN: bool = true;
pub const GIT_STATUS_FILE: &str = "* src/lib.rs (dirty)";

Modules

• git2_mod

Macros

• concatcp
  Concatenates constants of primitive types into a &'static str.
• formatcp
  Formats constants of primitive types into a &'static str
• map_ascii_case
  Converts the casing style of a &'static str constant, ignoring non-ascii unicode characters.
• shadow
  Add a module with the provided name which contains the build information generated by shadow-rs.
• str_get
  Indexes a &'static str constant, returning None when the index is not on a character boundary.
• str_index
  Indexes a &'static str constant.
• str_repeat
  Creates a &'static str by repeating a &'static str constant times times
• str_replace
  Replaces all the instances of $pattern in $input (a &'static str constant) with $replace_with (a &'static str constant).
• str_splice
  Replaces a substring in a &'static str constant. Returns both the new resulting &'static str, and the replaced substring.

Structs

• Git
• PWrapper
  Wrapper for many std types, which implements the const_debug_fmt and/or const_display_fmt methods for them.
• Project
• Shadow
  shadow-rs configuration.
• SplicedStr
  The return value of str_splice
• SystemEnv

Enums

• BuildModel
  Re-exported from the is_debug crate
• Case
  The casing style of a string.
• DateTime
• ShadowError
  shadow-rs build process errors. This type wraps multiple kinds of underlying errors that can occur downstream of shadow-rs, such as std::io::Error.

Constants

• BRANCH
• BUILD_OS
• BUILD_TARGET
• BUILD_TARGET_ARCH
• CARGO_MANIFEST_DIR
• CARGO_METADATA
• CARGO_TREE
• CARGO_VERSION
• COMMIT_AUTHOR
• COMMIT_DATE
• COMMIT_DATE_2822
• COMMIT_DATE_3339
• COMMIT_EMAIL
• COMMIT_HASH
• GIT_CLEAN
• GIT_STATUS_FILE
• LAST_TAG
• PKG_DESCRIPTION
• PKG_VERSION
• PKG_VERSION_MAJOR
• PKG_VERSION_MINOR
• PKG_VERSION_PATCH
• PKG_VERSION_PRE
• RUST_CHANNEL
• RUST_VERSION
• SHORT_COMMIT
• TAG

Traits

• Format

Functions

• branch
  get current repository git branch.
• build_channel
  Re-exported from the is_debug crate
• default_deny
  Since cargo metadata details about workspace membership and resolved dependencies for the current package, storing this data can result in significantly larger crate sizes. As such, the CARGO_METADATA const is disabled by default.
• git_clean
  Check current git Repository status without nothing(dirty or stage)
• git_status_file
  List current git Repository statue(dirty or stage) contain file changed
• is_debug
  Re-exported from the is_debug crate
• is_release
  Re-exported from the is_debug crate
• new
  Generates build information for the current project. This function must be called from build.rs.
• new_deny
  Identical to new, but additionally accepts a build output denylist. This list determines constants to be excluded in the build output.
• new_hook
  Identical to new, but additionally accepts an output hook. The hook receives the output file of shadow-rs, and it can add additional entries to the output of shadow-rs by writing to this file. Note that since the output will be compiled as a Rust module, inserting invalid Rust code will lead to a compile error later on.
• tag
  get current repository git tag.

Type Aliases

• SdResult
  Results returned by the shadow-rs build process. For more information see ShadowError.
• ShadowConst
  shadow-rs build constant identifiers.