shadow-rs: build-time information stored in your rust project. (binary, lib, cdylib and dylib)
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
orrelease
And more!
You can use this tool to check in production exactly where a binary came from and how it was built.
⚠️
Notice The build.rs is not rebuilt every-time if the repository has been history builld. The recommended way is to run
cargo clean
first, then executecargo build
, or use a CI/CD pipeline tool to help you perform this operation. For more details, see baoyachi#95.
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 a custom hook. - Built-in function:examples.
Setup Guide
Cargo.toml
fields
1) Modify Modify your Cargo.toml
like so:
[package]
build = "build.rs"
[dependencies]
shadow-rs = "{latest version}"
[build-dependencies]
shadow-rs = "{latest version}"
build.rs
file
2) Create Now in the root of your project (same directory as Cargo.toml
) add a file build.rs
:
- with add custom
const
orfn
see:example_shadow_hook
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!("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)'
//shadow-rs built in const
println!("{}", build::VERSION); // the version (description binary detail information)
println!("{}", build::CLAP_LONG_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. '2021-08-04 12:34:03 +00:00'
println!("{}", build::COMMIT_DATE_2822); // commit date, e.g. 'Thu, 24 Jun 2021 21:33:59 +0800'
println!("{}", build::COMMIT_DATE_3339); // commit date, e.g. '2021-06-24T21:33:59.972494+08:00'
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::BUILD_TARGET); // the OS target that built the binary, e.g. 'x86_64-apple-darwin'
println!("{}", build::BUILD_TARGET_ARCH); // the OS target arch that built the binary, e.g. '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::CARGO_MANIFEST_DIR); // e.g. /User/baoyachi/shadow-rs/
println!("{}", build::PROJECT_NAME); // your project name, e.g. 'shadow-rs'
// Time respects SOURCE_DATE_EPOCH environment variable - see below
println!("{}", build::BUILD_TIME); // time when start build occurred, e.g. '2020-08-16 14:50:25'
println!("{}", build::BUILD_TIME_2822); // time when start build occurred by rfc2822, e.g. 'Thu, 24 Jun 2021 21:33:59 +0800'
println!("{}", build::BUILD_TIME_3339); // time when start build occurred by rfc3339, e.g. '2021-06-24T21:33:59.972494+08:00'
println!("{}", build::BUILD_RUST_CHANNEL); // e.g. 'debug'
println!("{}", build::GIT_CLEAN); // e.g. 'true'
println!("{}", build::GIT_STATUS_FILE); // e.g. '* src/lib.rs (dirty)'
}
Reproducibility
This tool includes the current time in the binary which would normally make it non-reproducible.
However, it respects the SOURCE_DATE_EPOCH
variable - if
set to a Unix timestamp it will override the value of build time.
Clap Example
You also can use shadow-rs with clap
.
Constants and functions in table
shadow-rs built in function.
- how to use 👉 : examples
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' |
git_clean() | get current project clean. e.g 'true/false' |
git_status_file() | get current project statue file. e.g ' * examples/builtin_fn.rs (dirty)' |
shadow-rs support build const,function.
- how to use 👉 : shadow_example
const/fn | example |
---|---|
VERSION | support mini version information.It's use easy. |
CLAP_LONG_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 | 2021-08-04 12:34:03 +00:00 |
COMMIT_DATE_2822 | Thu, 24 Jun 2021 21:33:59 +0800 |
COMMIT_DATE_3339 | 2021-06-24T21:33:59.972494+08:00 |
COMMIT_AUTHOR | baoyachi |
COMMIT_EMAIL | xxx@gmail.com |
BUILD_OS | macos-x86_64 |
BUILD_TARGET | x86_64-apple-darwin |
BUILD_TARGET_ARCH | 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 |
CARGO_MANIFEST_DIR | /User/baoyachi/shadow-rs/ |
PROJECT_NAME | shadow-rs |
BUILD_TIME | 2021-06-24 21:33:59 |
BUILD_TIME_2822 | Thu, 24 Jun 2021 21:33:59 +0800 |
BUILD_TIME_3339 | 2021-06-24T15:53:55+08:00 |
BUILD_RUST_CHANNEL | debug/release |
GIT_CLEAN | true/false |
GIT_STATUS_FILE | * src/lib.rs (dirty) |
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 |
![]() starship |
exocore exocore |
bagua-core |
inclavare-containers |