33 releases (16 stable)

✓ Uses Rust 2018 edition

3.1.0 Mar 10, 2020
3.0.4 Oct 16, 2018
2.1.3 Oct 16, 2018
1.1.1 Aug 9, 2018
0.0.6 Mar 26, 2015

#576 in Rust patterns

Download history 10317/week @ 2019-12-10 9585/week @ 2019-12-17 8967/week @ 2019-12-24 8740/week @ 2019-12-31 10810/week @ 2020-01-07 11561/week @ 2020-01-14 10200/week @ 2020-01-21 10076/week @ 2020-01-28 10078/week @ 2020-02-04 11749/week @ 2020-02-11 11722/week @ 2020-02-18 12219/week @ 2020-02-25 12227/week @ 2020-03-03 14016/week @ 2020-03-10 16105/week @ 2020-03-17 16482/week @ 2020-03-24

45,420 downloads per month
Used in 68 crates (31 directly)

MIT/Apache

30KB
327 lines

vergen

Current Release

Crates.io Crates.io Crates.io

Build Status

Travis Build Status
GitLab CI/CD pipeline status
Appveyor Build status

Code Coverage

codecov

Version 3.x.x

Introduces generate_cargo_keys() and support for rebuild when .git/HEAD changes. Internally converted to use failure so Result is no longer exported and changed to the Rust 2018 edition.

This means the 3.x.x version will only work in the beta and nightly channels until Rust 2018 hits stable (12/06/18)

Version 2.1.x

Build Status

Backport of the 3.x.x changes to work on stable until Rust 2018 hits stable.

Version 2.0.x

Build Status

Compatible with Version 1.x.x, but introduces a completely new way to use the constants without having to use the include! macro.

Documentation

Documentation

Generate Compile Time Information

vergen, when used in conjunction with cargo build scripts, will generate environment variables to use with the env! macro. Below is a list of the supported variables.

Key Sample Value
VERGEN_BUILD_TIMESTAMP 2018-08-09T15:15:57.282334589+00:000
VERGEN_BUILD_DATE 2018-08-09
VERGEN_SHA 75b390dc6c05a6a4aa2791cc7b3934591803bc22
VERGEN_SHA_SHORT 75b390d
VERGEN_COMMIT_DATE 2018-08-08
VERGEN_TARGET_TRIPLE x86_64-unknown-linux-gnu
VERGEN_SEMVER v3.0.0
VERGEN_SEMVER_LIGHTWEIGHT v3.0.0

The variable generation can be toggled on or off at an individual level via ConstantsFlags

Note on SEMVER

VERGEN_SEMVER can be generated via git describe or by env::var("CARGO_PKG_VERSION").

By default, SEMVER uses git describe if possible, and falls back to CARGO_PKG_VERSION.

If you wish to force CARGO_PKG_VERSION, toggle off SEMVER and toggle on SEMVER_FROM_CARGO_PKG.

Re-build On Changed HEAD

vergen can also be configured to re-run build.rs when either .git/HEAD or the file that .git/HEAD points at changes.

This can behavior can be toggled on or of with the REBUILD_ON_HEAD_CHANGE flag.

'cargo:' Key Build Script Output

[package]
#..
build = "build.rs"

[dependencies]
#..

[build-dependencies]
vergen = "3"

Example 'build.rs'

extern crate vergen;

use vergen::{ConstantsFlags, generate_cargo_keys};

fn main() {
    // Setup the flags, toggling off the 'SEMVER_FROM_CARGO_PKG' flag
    let mut flags = ConstantsFlags::all();
    flags.toggle(ConstantsFlags::SEMVER_FROM_CARGO_PKG);

    // Generate the 'cargo:' key output
    generate_cargo_keys(ConstantsFlags::all()).expect("Unable to generate the cargo keys!");
}

Use the constants in your code

fn my_fn() {
    println!("Build Timestamp: {}", env!("VERGEN_BUILD_TIMESTAMP"));
}

License

Licensed under either of

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~795KB
~11K SLoC