Skip to content

Latest commit

 

History

History
201 lines (154 loc) · 11.1 KB

README.md

File metadata and controls

201 lines (154 loc) · 11.1 KB
Raw

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

shadow-rs build tool

GitHub Actions Crates.io Docs.rs Download DepStatus Gitter Coverage Status 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 or release
  • ... And more!

Strongly recommend using shadow-rs on the LSP service developed in Rust.

You can use this crate to programmatically check where a binary came from and how it was built.

Currently, integration into wasm is also supported. For detailed settings, please refer to the link example_wasm.

build_module

Note on Caching

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 #95.

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 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 that shadow-rs provides.

Setup

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

About build = "build.rs",this is an optional addition where, by default, build points to the build.rs file. It is recommended to use it as such. However, if your build script file is not named build.rs, please manually specify it. For example: build = "gen.rs".

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

If you want to exclude some build constants, you can use [new_deny] instead of [new].

3) Integrate Shadow

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.

4) Use Shadow Constants

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); //[email protected]

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

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

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.

List of Constants and Functions

Functions

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)

Constants

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 [email protected]
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.

People using shadow-rs

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