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
orrelease
- ... And more!
You can use this crate to programmatically check where a binary came from and how it was built.
shadow-rs
build information is not always rebuilt when you build a project. shadow-rs
outputs several hints to Cargo in order to force rebuilds when required, but this does not always work. You can enforce up-to-date build information by running cargo clean
before the build, or use a CI/CD pipeline tool. For more details, see baoyachi#95.
- 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 thatshadow-rs
provides.
Modify your Cargo.toml
like so:
[package]
build = "build.rs"
[dependencies]
shadow-rs = "{latest version}"
[build-dependencies]
shadow-rs = "{latest version}"
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
].
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.
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)
}
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.
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
.
Function | Description |
---|---|
is_debug() |
true if this is a build with debug assertions. |
branch() |
Git branch at build time. |
tag() |
Current Git tag at build time. |
git_clean() |
Whether Git working tree was clean at build time. |
git_status_file() |
git status -like output, e.g. * examples/builtin_fn.rs (dirty) |
Constant | Example |
---|---|
VERSION | 3.4.5 |
CLAP_LONG_VERSION | (A multi-line string containing branch, commit hash, build time, Rust version and toolchain channel) |
BRANCH | master |
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 | (Output of 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 | release |
GIT_CLEAN | true |
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.
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 |