# 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](https://doc.rust-lang.org/cargo/reference/build-scripts.html) and can emit a `VERGEN_GIT_SHA` environment variable for use in your code.
The `vergen` suite of tools can emit the following [output]((https://doc.rust-lang.org/cargo/reference/build-scripts.html#outputs-of-the-build-script)):
- Will emit [`cargo:rustc-env=VAR=VALUE`](https://doc.rust-lang.org/cargo/reference/build-scripts.html#cargorustc-envvarvalue)
for each feature you have enabled. These can be referenced with the [`env!`](https://doc.rust-lang.org/std/macro.env.html) or [`option_env!`](https://doc.rust-lang.org/std/macro.option_env.html) macro in your code.
- If using one of the git enabled libraries, will emit [`cargo:rerun-if-changed=.git/HEAD`](https://doc.rust-lang.org/cargo/reference/build-scripts.html#rerun-if-changed). 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>`](https://doc.rust-lang.org/cargo/reference/build-scripts.html#rerun-if-changed). This is done to ensure any git instructions are regenerated when commits are made.
- Can emit [`cargo:warning`](https://doc.rust-lang.org/cargo/reference/build-scripts.html#cargo-warning) outputs if the
[`fail_on_error`](EmitBuilder::fail_on_error) feature is not enabled and the requested variable is defaulted through error or
the [`idempotent`](EmitBuilder::idempotent) flag.
- Will emit [`cargo:rerun-if-changed=build.rs`](https://doc.rust-lang.org/cargo/reference/build-scripts.html#rerun-if-changed)
to rerun instruction emission if the `build.rs` file changed.
- Will emit [`cargo:rerun-if-env-changed=VERGEN_IDEMPOTENT`](https://doc.rust-lang.org/cargo/reference/build-scripts.html#rerun-if-changed)
to rerun instruction emission if the `VERGEN_IDEMPOTENT` environment variable has changed.
- Will emit [`cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH`](https://doc.rust-lang.org/cargo/reference/build-scripts.html#rerun-if-changed)
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
[](https://docs.rs/vergen)
[](https://crates.io/crates/vergen)
[](https://crates.io/crates/vergen)
[](https://crates.io/crates/vergen)
[](https://codecov.io/gh/rustyhorde/vergen)
[](https://github.com/rustyhorde/vergen/actions)
[](https://github.com/sponsors/CraZySacX)
### vergen-git2
[](https://docs.rs/vergen-git2)
[](https://crates.io/crates/vergen-git2)
[](https://crates.io/crates/vergen-git2)
[](https://crates.io/crates/vergen-git2)
### vergen-gitcl
[](https://docs.rs/vergen-gitcl)
[](https://crates.io/crates/vergen-gitcl)
[](https://crates.io/crates/vergen-gitcl)
[](https://crates.io/crates/vergen-gitcl)
### vergen-gix
[](https://docs.rs/vergen-gix)
[](https://crates.io/crates/vergen-gix)
[](https://crates.io/crates/vergen-gix)
[](https://crates.io/crates/vergen-gix)
### vergen-pretty
[](https://docs.rs/vergen-pretty)
[](https://crates.io/crates/vergen-pretty)
[](https://crates.io/crates/vergen-pretty)
[](https://crates.io/crates/vergen-pretty)
## MSRV
The current minimum supported rust version is 1.81.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`](https://docs.rs/vergen/9.0.0/vergen/trait.AddCustomEntries.html) docs for more information.
* The [version 8 branch](https://github.com/rustyhorde/vergen/tree/legacy/v8) will be maintained for some time.
### Why?
This was done to resolve issues with [Cargo feature unification](https://doc.rust-lang.org/cargo/reference/features.html#mutually-exclusive-features) 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](MIGRATING_v8_to_v9.md)
## Documentation
* [vergen](https://docs.rs/vergen/latest)
* [vergen-git2](https://docs.rs/vergen-git2/latest)
* [vergen-gitcl](https://docs.rs/vergen-gitcl/latest)
* [vergen-gix](https://docs.rs/vergen-gix/latest)
* [vergen-pretty](https://docs.rs/vergen-pretty/latest)
## Contributing
See the documentation at [CONTRIBUTING.md](CONTRIBUTING.md)
## License
Licensed under either of
* Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or https://www.apache.org/licenses/LICENSE-2.0)
* MIT license ([LICENSE-MIT](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.