vergen

vergen, vergen-git2, vergen-gitcl, vergen-gix, vergen-pretty

The vergen suite of tools allow you to embed environment variables generated at build time into your code. For example, I may care about the last git commit number and need to reference it in my code. You can configure one of the vergen git tools in cargo build scripts and can emit a VERGEN_GIT_SHA environment variable for use in your code.

The vergen suite of tools can emit the following output:

• 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.
• If using one of the git enabled libraries, will emit cargo:rerun-if-changed=.git/HEAD. This is done to ensure any git instructions are regenerated when commits are made.
• If using one of the git enabled libraries, will emit cargo:rerun-if-changed=.git/<path_to_ref>. This is done to ensure any git instructions are regenerated when commits are made.
• Can emit cargo:warning outputs if the fail_on_error feature is not enabled and the requested variable is defaulted through error, the idempotent flag, or the default_on_error flag. By default a variable that cannot be generated (for example VERGEN_GIT_* when building outside a git worktree) is left unset; enable default_on_error (or set the VERGEN_DEFAULT_ON_ERROR environment variable) to emit the idempotent default value instead so env! keeps compiling.
• 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=VERGEN_DEFAULT_ON_ERROR to rerun instruction emission if the VERGEN_DEFAULT_ON_ERROR 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.

vergen-pretty is a macro and pretty printer for vergen based cargo instruction output.

Current Releases

vergen

vergen-git2

vergen-gitcl

vergen-gix

vergen-pretty

MSRV

The current minimum supported rust version is 1.95.0

⚠️ Notes on version 9 ⚠️

• Version 9 introduces 3 new libraries, vergen-git2, vergen-gitcl, and vergen-gix that will be versioned independently from vergen.
• The 3 new libraries are intended to be drop in replacements for vergen when you need to generate git based cargo build script instructions.
• The git based features have been removed from the base vergen library.
• vergen now contains the build, cargo, rustc, and sysinfo feature implementations. These features are re-exported by the new libraries allowing you to configure the output as you have previously.
• Version 9 introduces the AddCustomEntries trait. Implementing this trait allows you to include your own custom Cargo instructions, using vergen as the engine to generate them. See the AddCustomEntries docs for more information.
• The version 8 branch will be maintained for some time.

Why?

This was done to resolve issues with Cargo feature unification and mutually exclusive features. Previous versions of vergen had 3 mutually exclusive features (git2, gitcl, and gix). Feature unification could cause compilation issues if you had included a dependency that also used vergen but had configured a different git feature. Splitting the git backends into separate libraries helps alleviate this issue.

Migration from version 8

See the documentation at MIGRATING_v8_to_v9.md

Documentation

• vergen
• vergen-git2
• vergen-gitcl
• vergen-gix
• vergen-pretty

Contributing

See the documentation at CONTRIBUTING.md

License

Licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or https://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or https://opensource.org/licenses/MIT) at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.