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.
Feature | Enables |
---|---|
build | VERGEN_BUILD_* instructions |
cargo | VERGEN_CARGO_* instructions |
git | VERGEN_GIT_* instructions and the cargo:rerun-if-changed instructions |
rustc | VERGEN_RUSTC_* instructions |
NOTE - All four 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: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
Variable | Sample |
---|---|
See Build to configure the following | |
VERGEN_BUILD_DATE | 2021-02-25 |
VERGEN_BUILD_TIME | 23:28:39.493201 |
VERGEN_BUILD_TIMESTAMP | 2021-02-25T23:28:39.493201+00:00 |
VERGEN_BUILD_SEMVER | 5.0.0 |
See Git to configure the following | |
VERGEN_GIT_BRANCH | feature/fun |
VERGEN_GIT_COMMIT_DATE | 2021-02-24 |
VERGEN_GIT_COMMIT_TIME | 20:55:21 |
VERGEN_GIT_COMMIT_TIMESTAMP | 2021-02-24T20:55:21+00:00 |
VERGEN_GIT_SEMVER | 5.0.0-2-gf49246c |
VERGEN_GIT_SHA | f49246ce334567bff9f950bfd0f3078184a2738a |
See Rustc to configure the following | |
VERGEN_RUSTC_CHANNEL | nightly |
VERGEN_RUSTC_COMMIT_DATE | 2021-02-24 |
VERGEN_RUSTC_COMMIT_HASH | a8486b64b0c87dabd045453b6c81500015d122d6 |
VERGEN_RUSTC_HOST_TRIPLE | x86_64-apple-darwin |
VERGEN_RUSTC_LLVM_VERSION | 11.0 |
VERGEN_RUSTC_SEMVER | 1.52.0-nightly |
See Cargo to configure the following | |
VERGEN_CARGO_FEATURES | git,build |
VERGEN_CARGO_PROFILE | debug |
VERGEN_CARGO_TARGET_TRIPLE | x86_64-unknown-linux-gnu |
Usage
- Ensure you have build scripts enabled via the
build
configuration in yourCargo.toml
- Add
vergen
as a build dependency, optionally disabling default features in yourCargo.toml
- Create a
build.rs
file that usesvergen
to generatecargo:
instructions. - Use the
env!
macro in your code
Cargo.toml
[package]
#..
build = "build.rs"
[dependencies]
#..
[build-dependencies]
vergen = "5"
# or
vergen = { version = "5", 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 Config
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
Build | Configuration for the |
Cargo | Configuration for the |
Config | Configure |
Git | Configuration for the |
Rustc | Configuration for the |
Enums
SemverKind | The semver kind to output |
ShaKind | The SHA kind to output |
TimeZone | The timezone kind to use with date information |
TimestampKind | The timestamp kind to output |
Functions
vergen | Generate the |