3 releases
1.0.0-beta.2 | Feb 3, 2024 |
---|---|
1.0.0-beta.1 | Jan 30, 2024 |
#604 in Build Utils
1,444 downloads per month
Used in vergen-pretty
260KB
5K
SLoC
vergen - A suite of libraries for generating cargo instructions from a Cargo build script
vergen
, vergen-git2
, vergen-gitcl
, vergen-gix
. vergen-pretty
When used in conjunction with cargo build scripts 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.70.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
~13–18MB
~336K SLoC