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.
Feature | Enables |
---|---|
build | VERGEN_BUILD_* instructions |
git | VERGEN_GIT_* instructions, the cargo:rerun-if-changed instructions, and the REBUILD_ON_HEAD_CHANGE flag |
rustc | VERGEN_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
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 |