Crate vergen[−][src]

vergen - Generate Cargo Build Instructions

vergen, when used in conjunction with cargo build scripts, will generate cargo: instructions.

  • The cargo:rustc-env instructions add environment variables that can be used with the env! macro in your code.
  • The cargo:rerun-if-changed instructions tell cargo to re-run the build script if the file at the given path has changed.

Features

vergen has three features toggles allowing you to customize your output.

FeatureEnables
buildVERGEN_BUILD_* instructions
gitVERGEN_GIT_* instructions, the cargo:rerun-if-changed instructions, and the REBUILD_ON_HEAD_CHANGE flag
rustcVERGEN_RUSTC_* instructions

NOTE - All three features are enabled by default.

Sample Output

If all three features are enabled, and all flags are toggled on, the build script will generate instructions for cargo similar to below

cargo:rustc-env=VERGEN_BUILD_DATE=2021-02-12
cargo:rustc-env=VERGEN_BUILD_TIMESTAMP=2021-02-12T01:54:15.134750+00:00
cargo:rustc-env=VERGEN_GIT_BRANCH=feature/git2
cargo:rustc-env=VERGEN_GIT_COMMIT_DATE=2021-02-11T20:05:53-05:00
cargo:rustc-env=VERGEN_GIT_SEMVER=v3.2.0-86-g95fc0f5
cargo:rustc-env=VERGEN_GIT_SEMVER_LIGHTWEIGHT=blah-33-g95fc0f5
cargo:rustc-env=VERGEN_GIT_SHA=95fc0f5d066710f16e0c23ce3239d6e040abca0d
cargo:rustc-env=VERGEN_GIT_SHA_SHORT=95fc0f5
cargo:rustc-env=VERGEN_RUSTC_CHANNEL=nightly
cargo:rustc-env=VERGEN_RUSTC_COMMIT_DATE=2021-02-10
cargo:rustc-env=VERGEN_RUSTC_COMMIT_HASH=07194ffcd25b0871ce560b9f702e52db27ac9f77
cargo:rustc-env=VERGEN_RUSTC_HOST_TRIPLE=x86_64-apple-darwin
cargo:rustc-env=VERGEN_RUSTC_LLVM_VERSION=11.0
cargo:rustc-env=VERGEN_RUSTC_SEMVER=1.52.0-nightly
cargo:rerun-if-changed=/Users/yoda/projects/rust-lang/vergen/.git/HEAD
cargo:rerun-if-changed=/Users/yoda/projects/rust-lang/vergen/.git/refs/heads/feature/git2

Example Usage

Cargo.toml

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

[dependencies]
#..

[build-dependencies]
vergen = "4"
# or
vergen = { version = "4", default-features = false, features = ["build", "rustc"] }
# if you wish to disable certain features

build.rs

NOTE - Individual instruction generation can be toggled on or off via ConstantsFlags

// 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:' instruction output
gen(flags).expect("Unable to generate the cargo keys!");

Use in code

println!("Build Timestamp: {}", env!("VERGEN_BUILD_TIMESTAMP"));
println!("git semver: {}", env!("VERGEN_GIT_SEMVER"));

Note on VERGEN_SEMVER and VERGEN_SEMVER_LIGHTWEIGHT

VERGEN_SEMVER and VERGEN_SEMVER_LIGHTWEIGHT can be generated via two methods

  1. git2::Repository::describe
  2. CARGO_PKG_VERSION

By default, if the git feature is enabled semver generation will use the first method. If the git feature is disabled or method one errors, generation falls back to the second method. Note that the git describe method is only useful if you have tags on your repository. I recommend SemVer tags, but this will work with any tag format. If your repository has no tags, this method will always fall back to CARGO_PKG_VERSION. Also worth noting, VERGEN_SEMVER and VERGEN_SEMVER_LIGHTWEIGHT will only differ if you use lightweight tags in your repository.

If you wish to force method two even if the git feature is enabled you may toggle off SEMVER and toggle on SEMVER_FROM_CARGO_PKG.

Note on REBUILD_ON_HEAD_CHANGE

vergen can also be configured to instruct cargo to re-run the build script when either <gitpath>/HEAD or the file that <gitpath>/HEAD points at changes.

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

Structs

ConstantsFlags

Constants Flags

Error

An error from the library

Functions

gen

Generate the cargo: instructions