vergen - Emit cargo instructions from a build script

vergen, when used in conjunction with cargo build scripts can emit the following:

• Will emit cargo:rustc-env=VAR=VALUE for each feature you have enabled. These can be referenced with the env! macro in your code.
• Will emit cargo:rerun-if-changed=.git/HEAD if the git feature is enabled. This is done to ensure any git instructions are regenerated when commits are made.
• Will emit cargo:rerun-if-changed=.git/<path_to_ref> if the git feature is enabled. 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 or the idempotent flag.
• 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=SOURCE_DATE_EPOCH to rerun instruction emission if the SOURCE_DATE_EPOCH environment variable has changed.

Current Release

MSRV

The current minimum supported rust version is 1.70.0

Example Usage

See the documentation at docs.rs for example usage

Cargo feature unification for vergen versions prior to 8.3.0

When a dependency is used by multiple packages, Cargo will use the union of all features enabled on that dependency when building it. Prior to version 8.3.0, vergen had a set of mutually exclusive features gitcl, git2, and gitoxide to enable to specific git backend you wished to use. If your crate has a dependency on another crate that uses vergen, your crate may fail to compile if you select a different git backend then the crate you depend on. For example, your crate depends on fancy-lib.

fancy-lib Cargo.toml

[build-dependencies]
vergen = { version = "8.2.10", features = ["git","gitcl"] }

your crate Cargo.toml

[dependencies]
fancy-lib = "0.1.0"

[build-dependencies]
vergen = { version = "8.2.10", features = ["git","gitoxide"] }

Your crate will fail to compile because cargo unifies this to

vergen = { version = "8.2.10", features = ["git","gitcl","gitoxide"] }

and prior to 8.3.0 vergen will not compile with both gitcl and gitoxide as features.

As a workaround, you can use cargo tree -f "{p} {f}" | grep vergen to determine the feature list cargo has set for vergen. If a git backend has already been determined you will be able to use that without declaring those features in your dependency list. This is not perfect as this leaves you at the mercy of your dependency and the git feature they selected, but it's a workaround until version 9 comes out.

fancy-lib Cargo.toml

[build-dependencies]
vergen = { version = "8.2.10", features = ["git","gitcl"] }

your crate Cargo.toml

[dependencies]
fancy-lib = "0.1.0"

[build-dependencies]
vergen = "8.2.10"

Unified

vergen = { version = "8.2.10", features = ["git","gitcl"] }

Cargo feature unification for vergen versions 8.3.0 and beyond

vergen will accept gitcl,git2, and gitoxide as features. If more than one of them is included, vergen will select gitcl before git2 and git2 before gitoxide.

Notes about the optional git2 dependency

git2 picked up some security related features. In docker environments especially, this requires a safe.directory configuration. There are a couple methods for achieving this.

1. If you control the build, you can add git config --global --add safe.directory /workspace to the build file.
2. If you do not control the docker build, you can add git config --global --add safe.directory /workspace && before the actual command you are running when using docker run.
3. If you do not control the docker build, you can mount a .gitconfig file at /root that includes the safe.directory configuration. I use this method myself when building static binaries with clux/muslrust.

docker run -v cargo-cache:/root/.cargo/registry -v (pwd):/volume -v ~/.gitconfig:/root/.gitconfig:ro --rm -t clux/muslrust:stable cargo build --release

See #126 for more discussion on the topic. If the solutions above do not work for your usecase, you can pin your vergen version to 7.4.3, with the caveat you will be exposed to the issues described at the link above.

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.