logo
Expand description

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

It’s 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.

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

Built in function

  • Check out the examples for a simple demonstration of how shadow-rs might be used to provide build in function.

Example

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

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

Optional Dependencies:

  • git2 (enabled by default) — Use libgit2 as a backend for git operations

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

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.

Then you can use const that’s shadow build it(main.rs).

The build mod just we use shadow!(build) generated.

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::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 example

And you can also use shadow-rs with clap.

For the user guide and futher documentation, please read The shadow-rs document.

Macros

Concatenates constants of primitive types into a &'static str.

Formats constants of primitive types into a &'static str

Add a mod in project with $build_mod.

Indexes a &'static str constant, returning None when the index is not on a character boundary.

Indexes a &'static str constant.

Creates a &'static str by repeating a &'static str constant times times

Replaces a substring in a &'static str constant. Returns both the new resulting &'static str, and the replaced substring.

Structs

Wrapper for many std types, which implements the const_debug_fmt and/or const_display_fmt methods for them.

The return value of str_splice

Enums

Functions

get current repository git branch.

get std::env:vars

Check current git Repository status without nothing(dirty or stage)

List current git Repository statue(dirty or stage) contain file changed

It’s shadow-rs Initialization entry.

It’s shadow-rs Initialization entry with add custom hook.

get current repository git tag.

Type Definitions