Crate vergen_git2

vergen-git2 - Emit cargo instructions from a build script

vergen-git2 uses the git2 library to generate the git instructions.

vergen-git2, when used in conjunction with cargo build scripts can emit the following:

• Will emit cargo:rustc-env=VAR=VALUE for each feature you have enabled. These can be referenced with the env! or option_env! macro in your code.
• Can emit cargo:warning outputs if the fail_on_error feature is not enabled and the requested variable is defaulted through error or the idempotent flag.
• Will emit cargo:rerun-if-changed=.git/HEAD if git instructions are emitted. This is done to ensure any git instructions are regenerated when commits are made.
• Will emit cargo:rerun-if-changed=.git/<path_to_ref> if git instructions are emitted. This is done to ensure any git instructions are regenerated when commits are made.
• Will emit cargo:rerun-if-changed=build.rs to rerun instruction emission if the build.rs file changed.
• Will emit cargo:rerun-if-env-changed=VERGEN_IDEMPOTENT to rerun instruction emission if the VERGEN_IDEMPOTENT environment variable has changed.
• Will emit cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH to rerun instruction emission if the SOURCE_DATE_EPOCH environment variable has changed.

Usage

1. Ensure you have build scripts enabled via the build configuration in your Cargo.toml

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

2. Add vergen-git2 as a build dependency in Cargo.toml, specifying the features you wish to enable.

[dependencies]
#..

[build-dependencies]
# All features enabled
vergen-git2 = { version = "1.0.0", features = ["build", "cargo", "rustc", "si"] }
# or
vergen-git2 = { version = "1.0.0", features = ["build"] }
# if you wish to disable certain features

3. Create a build.rs file that uses vergen-git2 to emit cargo instructions. Configuration starts with Emitter. Eventually you will call emit to output the cargo instructions. See the emit documentation for more robust examples.

Generate all output

// NOTE: This will output everything, and requires all features enabled.
// NOTE: See the specific builder documentation for configuration options.
let build = BuildBuilder::all_build()?;
let cargo = CargoBuilder::all_cargo()?;
let git2 = Git2Builder::all_git()?;
let rustc = RustcBuilder::all_rustc()?;
let si = SysinfoBuilder::all_sysinfo()?;

Emitter::default()
    .add_instructions(&build)?
    .add_instructions(&cargo)?
    .add_instructions(&git2)?
    .add_instructions(&rustc)?
    .add_instructions(&si)?
    .emit()?;

Sample Output

cargo:rustc-env=VERGEN_BUILD_DATE=2024-01-31
cargo:rustc-env=VERGEN_BUILD_TIMESTAMP=2024-01-31T03:26:34.065893658Z
cargo:rustc-env=VERGEN_CARGO_DEBUG=true
cargo:rustc-env=VERGEN_CARGO_FEATURES=
cargo:rustc-env=VERGEN_CARGO_OPT_LEVEL=0
cargo:rustc-env=VERGEN_CARGO_TARGET_TRIPLE=x86_64-unknown-linux-gnu
cargo:rustc-env=VERGEN_CARGO_DEPENDENCIES=anyhow 1.0.79,vergen-pretty 0.3.2
cargo:rustc-env=VERGEN_GIT_BRANCH=master
cargo:rustc-env=VERGEN_GIT_COMMIT_AUTHOR_EMAIL=emitter@vergen.com
cargo:rustc-env=VERGEN_GIT_COMMIT_AUTHOR_NAME=Jason Ozias
cargo:rustc-env=VERGEN_GIT_COMMIT_COUNT=44
cargo:rustc-env=VERGEN_GIT_COMMIT_DATE=2024-01-30
cargo:rustc-env=VERGEN_GIT_COMMIT_MESSAGE=depsup
cargo:rustc-env=VERGEN_GIT_COMMIT_TIMESTAMP=2024-01-30T21:43:43.000000000Z
cargo:rustc-env=VERGEN_GIT_DESCRIBE=0.1.0-beta.1-15-g728e25c
cargo:rustc-env=VERGEN_GIT_SHA=728e25ca5bb7edbbc505f12b28c66b2b27883cf1
cargo:rustc-env=VERGEN_RUSTC_CHANNEL=nightly
cargo:rustc-env=VERGEN_RUSTC_COMMIT_DATE=2024-01-29
cargo:rustc-env=VERGEN_RUSTC_COMMIT_HASH=5518eaa946291f00471af8b254b2a1715f234882
cargo:rustc-env=VERGEN_RUSTC_HOST_TRIPLE=x86_64-unknown-linux-gnu
cargo:rustc-env=VERGEN_RUSTC_LLVM_VERSION=17.0
cargo:rustc-env=VERGEN_RUSTC_SEMVER=1.77.0-nightly
cargo:rustc-env=VERGEN_SYSINFO_NAME=Arch Linux
cargo:rustc-env=VERGEN_SYSINFO_OS_VERSION=Linux  Arch Linux
cargo:rustc-env=VERGEN_SYSINFO_USER=jozias
cargo:rustc-env=VERGEN_SYSINFO_TOTAL_MEMORY=31 GiB
cargo:rustc-env=VERGEN_SYSINFO_CPU_VENDOR=AuthenticAMD
cargo:rustc-env=VERGEN_SYSINFO_CPU_CORE_COUNT=8
cargo:rustc-env=VERGEN_SYSINFO_CPU_NAME=cpu0,cpu1,cpu2,cpu3,cpu4,cpu5,cpu6,cpu7
cargo:rustc-env=VERGEN_SYSINFO_CPU_BRAND=AMD Ryzen Threadripper 1900X 8-Core Processor
cargo:rustc-env=VERGEN_SYSINFO_CPU_FREQUENCY=3792
cargo:rerun-if-changed=/home/jozias/projects/rust-lang/vergen-cl/.git/HEAD
cargo:rerun-if-changed=/home/jozias/projects/rust-lang/vergen-cl/.git/refs/heads/master
cargo:rerun-if-changed=build.rs
cargo:rerun-if-env-changed=VERGEN_IDEMPOTENT
cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH

Generate specific output

// NOTE: This will output only the instructions specified.
// NOTE: See the specific builder documentation for configuration options. 
let build = BuildBuilder::default().build_timestamp(true).build()?;
let cargo = CargoBuilder::default().opt_level(true).build()?;
let git2 = Git2Builder::default().commit_timestamp(true).build()?;
let rustc = RustcBuilder::default().semver(true).build()?;
let si = SysinfoBuilder::default().cpu_core_count(true).build()?;

Emitter::default()
    .add_instructions(&build)?
    .add_instructions(&cargo)?
    .add_instructions(&git2)?
    .add_instructions(&rustc)?
    .add_instructions(&si)?
    .emit()?;

Sample Output

cargo:rustc-env=VERGEN_BUILD_TIMESTAMP=2024-01-31T03:26:34.065893658Z
cargo:rustc-env=VERGEN_CARGO_OPT_LEVEL=0
cargo:rustc-env=VERGEN_GIT_COMMIT_TIMESTAMP=2024-01-30T21:43:43.000000000Z
cargo:rustc-env=VERGEN_RUSTC_SEMVER=1.77.0-nightly
cargo:rustc-env=VERGEN_SYSINFO_CPU_CORE_COUNT=8
cargo:rerun-if-changed=/home/jozias/projects/rust-lang/vergen-cl/.git/HEAD
cargo:rerun-if-changed=/home/jozias/projects/rust-lang/vergen-cl/.git/refs/heads/master
cargo:rerun-if-changed=build.rs
cargo:rerun-if-env-changed=VERGEN_IDEMPOTENT
cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH

4. Use the env! or option_env! macro in your code to read the environment variables.

if let Some(timestamp) = option_env!("VERGEN_BUILD_TIMESTAMP") {
    println!("Build Timestamp: {timestamp}");
}
if let Some(describe) = option_env!("VERGEN_GIT_DESCRIBE") {
    println!("git describe: {describe}");
}

Features

vergen-git2 has four main feature toggles allowing you to customize your output. No features are enabled by default.
You must specifically enable the features you wish to use.

Feature	Enables
build	VERGEN_BUILD_* instructions
cargo	VERGEN_CARGO_* instructions
rustc	VERGEN_RUSTC_* instructions
si	VERGEN_SYSINFO_* instructions

Environment Variables

vergen-git2 currently recognizes the following environment variables. The full list of the environment variable names can be found as constants here

Variable	Functionality
VERGEN_IDEMPOTENT	If this environment variable is set vergen will use the idempotent output feature regardless of the configuration set in build.rs. This exists mainly to allow package maintainers to force idempotent output to generate deterministic binary output.
SOURCE_DATE_EPOCH	If this environment variable is set vergen will use the value (unix time since epoch) as the basis for a time based instructions. This can help emit deterministic instructions.
VERGEN_BUILD_*	If this environment variable is set vergen will use the value you specify for the output rather than generating it.
VERGEN_CARGO_*	If this environment variable is set vergen will use the value you specify for the output rather than generating it.
VERGEN_GIT_*	If this environment variable is set vergen will use the value you specify for the output rather than generating it.
VERGEN_RUSTC_*	If this environment variable is set vergen will use the value you specify for the output rather than generating it.
VERGEN_SYSINFO_*	If this environment variable is set vergen will use the value you specify for the output rather than generating it.

Structs

• BuildBuilderbuild
  Builder for Build.
• CargoBuildercargo
  Builder for Cargo.
• CpuRefreshKindsi
  Used to determine what you want to refresh specifically on the Cpu type.
• DefaultConfig
  The default configuration to use when an issue has occured generating instructions
• Emitter
  The Emitter will emit cargo instructions (i.e. cargo:rustc-env=NAME=VALUE) base on the configuration you enable.
• Git2
  The VERGEN_GIT_* configuration features
• Git2Builder
  Builder for Git2.
• MemoryRefreshKindsi
  Used to determine which memory you want to refresh specifically.
• ProcessRefreshKindsi
  Used to determine what you want to refresh specifically on the Process type.
• RefreshKindsi
  Used to determine what you want to refresh specifically on the System type.
• RustcBuilderrustc
  Builder for Rustc.
• SysinfoBuildersi
  Builder for Sysinfo.

Enums

• DependencyKindcargo
  Dependencies can come in three kinds

Traits

• AddCustomEntries
  This trait should be implemented to allow the vergen emitter to properly emit your custom instructions.

Type Aliases

• CargoRerunIfChanged
  The vector of strings used to emit cargo:rerun-if-changed=VALUE cargo instructions
• CargoWarning
  The vector of strings used to emit cargo:warning=VALUE cargo instructions