Expand description

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 five 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
siVERGEN_SYSINFO_* instructions

NOTE - All five features are enabled by default.

Sample Output

If all features are enabled and the default Config is used the build script will generate instructions for cargo similar to below.

Please see Config for more details on instruction generation.

cargo:rustc-env=VERGEN_BUILD_TIMESTAMP=2021-02-25T23:28:39.493201+00:00
cargo:rustc-env=VERGEN_BUILD_SEMVER=5.0.0
cargo:rustc-env=VERGEN_GIT_BRANCH=feature/fun
cargo:rustc-env=VERGEN_GIT_COMMIT_TIMESTAMP=2021-02-24T20:55:21+00:00
cargo:rustc-env=VERGEN_GIT_SEMVER=4.1.0-2-gf49246c
cargo:rustc-env=VERGEN_GIT_SHA=f49246ce334567bff9f950bfd0f3078184a2738a
cargo:rustc-env=VERGEN_RUSTC_CHANNEL=nightly
cargo:rustc-env=VERGEN_RUSTC_COMMIT_DATE=2021-02-24
cargo:rustc-env=VERGEN_RUSTC_COMMIT_HASH=a8486b64b0c87dabd045453b6c81500015d122d6
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_FEATURES=git,build
cargo:rustc-env=VERGEN_CARGO_PROFILE=debug
cargo:rustc-env=VERGEN_CARGO_TARGET_TRIPLE=x86_64-unknown-linux-gnu
cargo:rustc-env=VERGEN_SYSINFO_NAME=Darwin
cargo:rustc-env=VERGEN_SYSINFO_OS_VERSION=MacOS 10.15.7 Catalina
cargo:rustc-env=VERGEN_SYSINFO_USER=yoda
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/fun

Environment Variables

A full list of environment variables that can be generated are listed in the following table

VariableSample
See Build to configure the following
VERGEN_BUILD_DATE2021-02-25
VERGEN_BUILD_TIME23:28:39.493201
VERGEN_BUILD_TIMESTAMP2021-02-25T23:28:39.493201+00:00
VERGEN_BUILD_SEMVER5.0.0
See Git to configure the following
VERGEN_GIT_BRANCHfeature/fun
VERGEN_GIT_COMMIT_DATE2021-02-24
VERGEN_GIT_COMMIT_TIME20:55:21
VERGEN_GIT_COMMIT_TIMESTAMP2021-02-24T20:55:21+00:00
VERGEN_GIT_SEMVER5.0.0-2-gf49246c
VERGEN_GIT_SEMVER_LIGHTWEIGHTfeature-test
VERGEN_GIT_SHAf49246ce334567bff9f950bfd0f3078184a2738a
VERGEN_GIT_SHA_SHORTf49246c
See Rustc to configure the following
VERGEN_RUSTC_CHANNELnightly
VERGEN_RUSTC_COMMIT_DATE2021-02-24
VERGEN_RUSTC_COMMIT_HASHa8486b64b0c87dabd045453b6c81500015d122d6
VERGEN_RUSTC_HOST_TRIPLEx86_64-apple-darwin
VERGEN_RUSTC_LLVM_VERSION11.0
VERGEN_RUSTC_SEMVER1.52.0-nightly
See Cargo to configure the following
VERGEN_CARGO_FEATURESgit,build
VERGEN_CARGO_PROFILEdebug
VERGEN_CARGO_TARGET_TRIPLEx86_64-unknown-linux-gnu
See Sysinfo to configure the following
VERGEN_SYSINFO_NAMEManjaro Linux
VERGEN_SYSINFO_OS_VERSIONLinux Manjaro Linux
VERGEN_SYSINFO_USERYoda
VERGEN_SYSINFO_TOTAL_MEMORY33 GB
VERGEN_SYSINFO_CPU_VENDORAuthentic AMD
VERGEN_SYSINFO_CPU_CORE_COUNT8
VERGEN_SYSINFO_CPU_NAMEcpu0,cpu1,cpu2,cpu3,cpu4,cpu5,cpu6,cpu7
VERGEN_SYSINFO_CPU_BRANDAMD Ryzen Threadripper 1900X 8-Core Processor
VERGEN_SYSINFO_CPU_FREQUENCY3792

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! or option_env! macro in your code

Cargo.toml

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

[dependencies]
#..

[build-dependencies]
vergen = "6"
vergen = { version = "6", default-features = false, features = ["build", "rustc"] }

build.rs

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

use anyhow::Result;
use vergen::{Config, vergen};

fn main() -> Result<()> {
  // Generate the default 'cargo:' instruction output
  vergen(Config::default())
}

Use in code

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

Structs

Configuration for the VERGEN_BUILD_* instructions

Configuration for the VERGEN_CARGO_* instructions

Configure vergen to produce the cargo: instructions you need

Configuration for the VERGEN_GIT_* instructions

Configuration for the VERGEN_RUSTC_* instructions

Configuration for the VERGEN_SYSINFO_* instructions

Enums

The semver kind to output

The SHA kind to output

The timezone kind to use with date information

The timestamp kind to output

Functions

Generate the cargo: instructions