Crate shadow_rs

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-24T21:44:14.473058+08:00";
pub const COMMIT_DATE :&str = "2020-08-16 13:12:52";
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";

Setup Guide

1) Modify Cargo.toml fields

Modify your Cargo.toml like so:

[package]
build = "build.rs"

[dependencies]
shadow-rs = "0.5"

[build-dependencies]
shadow-rs = "0.5"

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!("{}",shadow_rs::is_debug());//get build mode. cargo build --release return false.normally return true.

   println!("{}",build::version()); //print version() function
   println!("{}",build::BRANCH); //master
   println!("{}",build::SHORT_COMMIT);//8405e28e
   println!("{}",build::COMMIT_HASH);//8405e28e64080a09525a6cf1b07c22fcaf71a5c5
   println!("{}",build::COMMIT_DATE);//2020-08-16T06:22:24+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
}

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

shadow

Add a mod in project with $build_mod.

Enums

BuildRustChannel
ShadowError

Functions

branch	get current repository git branch.
is_debug	Get current project build mode.
new	It’s shadow-rs Initialization entry.
new_hook	It’s shadow-rs Initialization entry with add custom hook.
tag	get current repository git tag.

Type Definitions

SdResult