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.

Uses

I personally use vergen for two use cases.

The first is generating verbose output describing a command line application.

~/p/r/app λ app -vv
app 0.1.0

Build Timestamp:     2021-02-23T20:14:46.558472672+00:00
Build Version:       0.1.0-9-g46f83e1
Commit SHA:          46f83e112520533338245862d366f6a02cef07d4
Commit Date:         2021-02-23T08:08:02-05:00
Commit Branch:       master
rustc Version:       1.52.0-nightly
rustc Channel:       nightly
rustc Host Triple:   x86_64-unknown-linux-gnu
rustc Commit SHA:    3f5aee2d5241139d808f4fdece0026603489afd1
cargo Target Triple: x86_64-unknown-linux-musl
cargo Profile:       release

The second is information endpoints in web apis

~/p/r/app λ curl https://some.app.com/info | jq
{
  "build_timestamp": "2021-02-19T21:32:22.932833758+00:00",
  "git_semver": "0.0.0-7-gc96c096",
  "git_sha": "c96c0961c3b7b749eab92f6f588b67915889c4cd",
  "git_commit_date": "2021-02-19T16:29:06-05:00",
  "git_branch": "master",
  "rustc_semver": "1.52.0-nightly",
  "rustc_channel": "nightly",
  "rustc_host_triple": "x86_64-unknown-linux-gnu",
  "rustc_commit_sha": "3f5aee2d5241139d808f4fdece0026603489afd1",
  "cargo_target_triple": "x86_64-unknown-linux-musl",
  "cargo_profile": "release"
}

Features

vergen has four feature toggles allowing you to customize your output.

FeatureEnables
buildVERGEN_BUILD_* instructions
cargoVERGEN_CARGO_* instructions
gitVERGEN_GIT_* instructions and the cargo:rerun-if-changed instructions
rustcVERGEN_RUSTC_* instructions

NOTE - All four features are enabled by default.

Sample Output

If all features are enabled and all flags are toggled on the build script will generate instructions for cargo similar to below. Please see ConstantsFlags for more details on instruction generation.

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:rustc-env=VERGEN_CARGO_TARGET_TRIPLE=x86_64-unknown-linux-gnu
cargo:rustc-env=VERGEN_CARGO_PROFILE=debug
cargo:rustc-env=VERGEN_CARGO_FEATURES=git,build
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

Usage

  1. Ensure you have build scripts enabled via the build configuration in your Cargo.toml
  2. Add vergen as a build dependency, optionally disabling default features in your Cargo.toml
  3. Create a build.rs file that uses vergen to generate cargo: instructions.
  4. Use the env! macro in your code

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

use vergen::{ConstantsFlags, Error, gen};

fn main() -> Result<(), Box<dyn std::error::Error>> {
  // Setup the flags, toggling off unused instructions
  let mut flags = ConstantsFlags::all();
  flags.toggle(ConstantsFlags::SEMVER_FROM_CARGO_PKG);
  flags.toggle(ConstantsFlags::SEMVER_LIGHTWEIGHT);
  flags.toggle(ConstantsFlags::SHA_SHORT);
  flags.toggle(ConstantsFlags::BUILD_DATE);

  // Generate the 'cargo:' instruction output
  gen(flags).map_err(Error::into)
}

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

Flags used to toggle individual cargo: instruction generation

Error

An error from the library

Functions

gen

Generate the cargo: instructions