Crate vergen_gitcl

vergen-gitcl - Emit cargo instructions from a build script

vergen-gitcl uses git from the command line to generate the git instructions.

vergen-gitcl, 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-gitcl as a build dependency in Cargo.toml, specifying the features you wish to enable.

[dependencies]
#..

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

3. Create a build.rs file that uses vergen-gitcl 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 gitcl = GitclBuilder::all_git()?;

Emitter::default()
    .add_instructions(&gitcl)?
    .emit()?;

Sample Output

                Date (  build): 2024-01-28
           Timestamp (  build): 2024-01-28T18:07:13.256193157Z
               Debug (  cargo): true
        Dependencies (  cargo): anyhow 1.0.79,vergen 8.3.1,vergen-pretty 0.3.1
            Features (  cargo):
           Opt Level (  cargo): 0
       Target Triple (  cargo): x86_64-unknown-linux-gnu
              Branch (    git): master
 Commit Author Email (    git): a_serious@vergen.com
  Commit Author Name (    git): Jason Ozias
        Commit Count (    git): 39
         Commit Date (    git): 2024-01-27
      Commit Message (    git): depsup
    Commit Timestamp (    git): 2024-01-27T15:13:49.000000000Z
            Describe (    git): 0.1.0-beta.1-10-gc139056
               Dirty (    git): false
                 SHA (    git): c1390562822a2f89ded3430c07cba03bf1651458
             Channel (  rustc): nightly
         Commit Date (  rustc): 2024-01-27
         Commit Hash (  rustc): 6b4f1c5e782c72a047a23e922decd33e7d462345
         Host Triple (  rustc): x86_64-unknown-linux-gnu
        LLVM Version (  rustc): 17.0
              Semver (  rustc): 1.77.0-nightly
           CPU Brand (sysinfo): AMD Ryzen Threadripper 1900X 8-Core Processor
      CPU Core Count (sysinfo): 8
       CPU Frequency (sysinfo): 3792
            CPU Name (sysinfo): cpu0,cpu1,cpu2,cpu3,cpu4,cpu5,cpu6,cpu7
          CPU Vendor (sysinfo): AuthenticAMD
                Name (sysinfo): Arch Linux
          OS Version (sysinfo): Linux  Arch Linux
        Total Memory (sysinfo): 31 GiB
                User (sysinfo): jozias

Generate specific output

let gitcl = GitclBuilder::default().commit_timestamp(true).build()?;

Emitter::default()
    .add_instructions(&gitcl)?
    .emit()?;

Sample Output

       Timestamp (  build): 2024-01-28T18:07:13.256193157Z
       Opt Level (  cargo): 0
Commit Timestamp (    git): 2024-01-27T15:13:49.000000000Z
          Semver (  rustc): 1.77.0-nightly
  CPU Core Count (sysinfo): 8

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-gitcl 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-gitcl currently recognizes the following environment variables

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

• Emitter
  The Emitter will emit cargo instructions (i.e. cargo:rustc-env=NAME=VALUE) base on the configuration you enable.
• Gitcl
  The VERGEN_GIT_* configuration features
• GitclBuilder
  Builder for Gitcl.

Traits

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