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§

Modules§

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§

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§

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§