#build-script #build #script #compile #shadow

shadow-rs

A build-time information stored in your rust project

51 releases (4 breaking)

0.5.25 Mar 31, 2021
0.5.3 Dec 31, 2020
0.3.19 Nov 29, 2020

#5 in Build Utils

Download history 491/week @ 2020-12-22 1048/week @ 2020-12-29 1834/week @ 2021-01-05 1451/week @ 2021-01-12 2208/week @ 2021-01-19 3949/week @ 2021-01-26 4277/week @ 2021-02-02 4276/week @ 2021-02-09 4275/week @ 2021-02-16 3019/week @ 2021-02-23 2855/week @ 2021-03-02 3132/week @ 2021-03-09 2437/week @ 2021-03-16 3172/week @ 2021-03-23 4616/week @ 2021-03-30 3954/week @ 2021-04-06

12,756 downloads per month
Used in 5 crates (3 directly)

MIT AND Apache-2.0

48KB
909 lines

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

shadow-rs build tool

Chrono GitHub Actions Crates.io Docs.rs Download DepStatus Gitter

shadow-rs 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:examples.

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.

fn main() {

    //shadow-rs built in function  
    println!("{}", shadow_rs::is_debug());      // check if this is a debug build
    println!("{}", shadow_rs::branch());        // get current project git branch. e.g.'master'
    println!("{}", shadow_rs::tag());        // get current project git head tag. e.g.'v1.5.3'

    //shadow-rs built in const   
    println!("{}", build::version());           // the version (description binary detail information)
    println!("{}", build::clap_version());      // usually used by clap crates version() (description binary detail information)
    println!("{}", build::PKG_VERSION);         // current package version. e.g. '1.3.15-beta2'  
    println!("{}", build::PKG_VERSION_MAJOR);   //current package major version. e.g. '1'  
    println!("{}", build::PKG_VERSION_MINOR);   //current package minor version. e.g. '3'  
    println!("{}", build::PKG_VERSION_PATCH);   //current package minor version. e.g. '15'  
    println!("{}", build::PKG_VERSION_PRE);   //current package minor version. e.g. 'beta2'  
    println!("{}", build::BRANCH);              // the branch, e.g. 'master'
    println!("{}", build::TAG);                 // the tag, e.g. 'v1.0.0'
    println!("{}", build::SHORT_COMMIT);        // short commit hash, e.g. '8405e28e'
    println!("{}", build::COMMIT_HASH);         // full commit hash, e.g. '8405e28e64080a09525a6cf1b07c22fcaf71a5c5'
    println!("{}", build::COMMIT_DATE);         // commit date, e.g. '2020-08-16 11:52:47'
    println!("{}", build::COMMIT_AUTHOR);       // commit author, e.g. 'baoyachi'
    println!("{}", build::COMMIT_EMAIL);        // commit email, e.g. 'example@gmail.com'

    println!("{}", build::BUILD_OS);            // the OS that built the binary, e.g. 'macos-x86_64'
    println!("{}", build::RUST_VERSION);        // rustc version e.g. 'rustc 1.45.0 (5c1f21c3b 2020-07-13)'
    println!("{}", build::RUST_CHANNEL);        // rust toolchain e.g. 'stable-x86_64-apple-darwin (default)'
    println!("{}", build::CARGO_VERSION);       // cargo version e.g. 'cargo 1.45.0 (744bd1fbb 2020-06-15)'
    println!("{}", build::CARGO_TREE);          // e.g. the output of '$ cargo tree'

    println!("{}", build::PROJECT_NAME);        // your project name, e.g. 'shadow-rs'
    println!("{}", build::BUILD_TIME);          // time when start build occurred, e.g. '2020-08-16 14:50:25'
    println!("{}", build::BUILD_RUST_CHANNEL);  // e.g. 'debug'
}

Clap Example

And you can also use shadow-rs with clap.

Support const,function in table

shadow-rs built in function.

function desc
is_debug() check if this is a debug build.e.g.'true/false'
branch() get current project branch.e.g.'master/develop'
tag() get current project tag.e.g.'v1.3.5'

shadow-rs support build const,function.

const/fn example
version() support mini version information.It's use easy.
clap_version() support mini version information for clap.It's use easy.
BRANCH master/develop
TAG v1.0.0
SHORT_COMMIT 8405e28e
COMMIT_HASH 8405e28e64080a09525a6cf1b07c22fcaf71a5c5
COMMIT_DATE 2020-08-16 13:12:52
COMMIT_AUTHOR baoyachi
COMMIT_EMAIL xxx@gmail.com
BUILD_OS macos-x86_64
RUST_VERSION rustc 1.45.0 (5c1f21c3b 2020-07-13)
RUST_CHANNEL stable-x86_64-apple-darwin (default)
CARGO_VERSION cargo 1.45.0 (744bd1fbb 2020-06-15)
PKG_VERSION 0.3.13
CARGO_TREE cargo tree
PROJECT_NAME shadow-rs
BUILD_TIME 2020-08-16 14:50:25
BUILD_RUST_CHANNEL debug/release

If you have any questions, please create an issue so we may improve the documentation where it may be unclear.

People using shadow-rs

If you are using shadow-rs, please tell me! Or instead, consider making a note here: Shadow Users Collection.

nushell
nushell

starship
starship

kime
kime

alexandrie

alexandrie

Dependencies

~11MB
~260K SLoC