Crate shadow_rs

Source

Expand description

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 = { version = "{latest version}", default-features = false }

[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() {
    ShadowBuilder::builder()
        .build_pattern(BuildPattern::RealTime)
        .build().unwrap();
}

§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)";

Re-exports§

pub extern crate cargo_metadata;
pub extern crate serde_json;

Modules§

fmt: Re-exported from the is_debug crate Utilities for formatting and printing Strings.
git2_mod
rust_2015: Re-exported from the is_debug crate The 2015 version of the prelude of The Rust Standard Library.
rust_2018: Re-exported from the is_debug crate The 2018 version of the prelude of The Rust Standard Library.
rust_2021: Re-exported from the is_debug crate The 2021 version of the prelude of The Rust Standard Library.
rust_2024: Re-exported from the is_debug crate The 2024 version of the prelude of The Rust Standard Library.
v1: Re-exported from the is_debug crate The first version of the prelude of The Rust Standard Library.

Macros§

cfg: Re-exported from the is_debug crate Evaluates boolean combinations of configuration flags at compile-time.
concatcp: Re-exported from the const_format crate Concatenates constants of primitive types into a &'static str.
formatcp: Re-exported from the const_format crate Formats constants of primitive types into a &'static str
map_ascii_case: Re-exported from the const_format crate Converts the casing style of a &'static str constant, ignoring non-ascii unicode characters.
matches: Re-exported from the is_debug crate Returns whether the given expression matches the provided pattern.
shadow: Add a module with the provided name which contains the build information generated by shadow-rs.
str_get: Re-exported from the const_format crate Indexes a &'static str constant, returning None when the index is not on a character boundary.
str_index: Re-exported from the const_format crate Indexes a &'static str constant.
str_repeat: Re-exported from the const_format crate Creates a &'static str by repeating a &'static str constant times times
str_replace: Re-exported from the const_format crate Replaces all the instances of $pattern in $input (a &'static str constant) with $replace_with (a &'static str constant).
str_splice: Re-exported from the const_format crate Replaces a substring in a &'static str constant. Returns both the new resulting &'static str, and the replaced substring.
str_splice_out: Re-exported from the const_format crate Alternative version of str_splice which only returns the string with the applied replacement.

Structs§

Git
PWrapper: Re-exported from the const_format crate Wrapper for many std types, which implements the const_debug_fmt and/or const_display_fmt methods for them.
Project
Shadow: shadow-rs configuration.
ShadowBuilder: A builder pattern structure to construct a Shadow instance.
SplicedStr: Re-exported from the const_format crate The return value of str_splice
SystemEnv

Enums§

BuildModel: Re-exported from the is_debug crate
BuildPattern: The BuildPattern enum defines strategies for triggering package rebuilding.
Case: Re-exported from the const_format crate 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§

Traits§

Debug: Re-exported from the is_debug crate ? formatting.
Format
PartialEq: Re-exported from the is_debug crate Trait for comparisons using the equality operator.

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
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.

Derive Macros§

Debug: Re-exported from the is_debug crate Derive macro generating an impl of the trait Debug.
PartialEq: Re-exported from the is_debug crate Derive macro generating an impl of the trait PartialEq. The behavior of this macro is described in detail here.

Crate shadow_rs

Crate shadow_rs Copy item path

§Examples

§Setup

§1) Modify Cargo.toml fields

§2) Create build.rs file

§3) Integrate Shadow

§4) Use Shadow Constants

§Clap

§List of Generated Output Constants

Re-exports§

Modules§

Macros§

Structs§

Enums§

Constants§

Traits§

Functions§

Type Aliases§

Derive Macros§

Crate shadow_rs

§1) Modify `Cargo.toml` fields

§2) Create `build.rs` file