5 releases (2 stable)
1.0.1 | Sep 17, 2024 |
---|---|
1.0.0 | Jul 9, 2024 |
1.0.0-beta.2 | Feb 3, 2024 |
1.0.0-beta.1 | Jan 30, 2024 |
#129 in Build Utils
61,173 downloads per month
Used in 35 crates
(19 directly)
270KB
5K
SLoC
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 theenv!
oroption_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 thefail_on_error
feature is not enabled and the requested variable is defaulted through error or theidempotent
flag. - Will emit
cargo:rerun-if-changed=build.rs
to rerun instruction emission if thebuild.rs
file changed. - Will emit
cargo:rerun-if-env-changed=VERGEN_IDEMPOTENT
to rerun instruction emission if theVERGEN_IDEMPOTENT
environment variable has changed. - Will emit
cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH
to rerun instruction emission if theSOURCE_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.74.0
⚠️ Notes on version 9 ⚠️
- Version 9 introduces 3 new libraries,
vergen-git2
,vergen-gitcl
, andvergen-gix
that will be versioned independently fromvergen
. - 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 thebuild
,cargo
,rustc
, andsysinfo
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, usingvergen
as the engine to generate them. See theAddCustomEntries
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
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.
Dependencies
~1.5–3MB
~57K SLoC