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 = "{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)";

Re-exports§

pub extern crate cargo_metadata;
pub extern crate serde_json;

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§

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

Crate shadow_rsCopy item path