vergen - A suite of libraries for generating cargo instructions from a build script
vergen
, vergen-git2
, vergen-gitcl
, vergen-gix
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.
Current Release
vergen
⚠️ Notes on version 9 ⚠️
With version 9 comes the introduction of 3 new libraries, vergen-git2
, vergen-gitcl
, and vergen-gix
. Along with this change, the git features has been removed from the base vergen
library. The 3 new libraries are intended to be drop in replacements for
vergen
when you need to generate git based cargo build script instructions. 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.
Why? This was done to resolve issues with Cargo feature unification and mutually exclusive features. Previous version 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.
Version 9 also 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.
MSRV
The current minimum supported rust version is 1.70.0
Example Usage
See the documentation at docs.rs for example usage
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.