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 --------------------------|---------------------------------------- VERGENBUILDTIMESTAMP |2018-08-09T15:15:57.282334589+00:000 VERGENBUILDDATE |2018-08-09 VERGENSHA |75b390dc6c05a6a4aa2791cc7b3934591803bc22 VERGENSHASHORT |75b390d VERGENCOMMITDATE |2018-08-08 VERGENTARGETTRIPLE |x8664-unknown-linux-gnu VERGENSEMVER |v3.0.0 VERGENSEMVERLIGHTWEIGHT |v3.0.0 VERGENRUSTCSEMVER |1.4.3 VERGENRUSTCCHANNEL |stable VERGENHOSTTRIPLE |x8664-unknown-linux-gnu

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 [REBUILDONHEAD_CHANGE] flag.

'cargo:' Key Build Script Output

```toml [package]

..

build = "build.rs"

[dependencies]

..

[build-dependencies] vergen = "3" ```

Example 'build.rs'

```rust extern crate vergen;

use vergen::{ConstantsFlags, generatecargokeys};

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

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

} ```

Use the constants in your code

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

License

Licensed under either of * Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0) * MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT) at your option.

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.