Struct Emitter

pub struct Emitter { /* private fields */ }

The Emitter will emit cargo instructions (i.e. cargo:rustc-env=NAME=VALUE) base on the configuration you enable.

Implementations

impl Emitter

pub fn new() -> Emitter

Instantiate the builder to configure the cargo instruction emits

pub fn idempotent(&mut self) -> &mut Emitter

Enable the idempotent feature

NOTE - This feature can also be enabled via the VERGEN_IDEMPOTENT environment variable.

When this feature is enabled, certain vergen output (i.e. timestamps, sysinfo) will be set to an idempotent default. This will allow systems that depend on deterministic builds to override user requested vergen impurities. This will mainly allow for package maintainers to build packages that depend on vergen in a deterministic manner.

See this issue for more details

Variable	Sample
VERGEN_BUILD_DATE	VERGEN_IDEMPOTENT_OUTPUT
VERGEN_BUILD_TIMESTAMP	VERGEN_IDEMPOTENT_OUTPUT

Example

Emitter::new().idempotent().emit()?;
// or
// set::env("VERGEN_IDEMPOTENT", "true");
Emitter::new().emit()?;

pub fn fail_on_error(&mut self) -> &mut Emitter

Enable the fail_on_error feature

By default vergen will emit the instructions you requested. If for some reason those instructions cannot be generated correctly, placeholder values will be used instead. vergen will also emit cargo:warning instructions notifying you this has happened.

For example, if you configure vergen to emit VERGEN_GIT_* instructions and you run a build from a source tarball with no .git directory, the instructions will be populated with placeholder values, rather than information gleaned through git.

You can turn off this behavior by enabling fail_on_error.

Example

Emitter::new().fail_on_error().emit()?;

pub fn quiet(&mut self) -> &mut Emitter

Enable the quiet feature

Suppress the emission of the cargo:warning instructions.

Example

Emitter::new().quiet().emit()?;

pub fn custom_build_rs(&mut self, path: &'static str) -> &mut Emitter

Set a custom build.rs path if you are using a non-standard path

By default vergen will use build.rs as the build path for the cargo:rerun-if-changed emit. You can specify a custom build.rs path here if you have changed this default

Example

Emitter::new().custom_build_rs("my/custom/build.rs").emit()?;

pub fn add_instructions(&mut self, gen: &dyn Add) -> Result<&mut Emitter, Error>

Add a set of instructions to the emitter output

Errors

pub fn add_custom_instructions<K, V>( &mut self, gen: &impl AddCustom<K, V>, ) -> Result<&mut Emitter, Error>

where K: Into<String> + Ord, V: Into<String>,

Add a set of custom instructions to the emitter output

Errors

Errors may be generated if fail_on_error has been configured.

pub fn emit(&self) -> Result<(), Error>

Emit cargo instructions from your build script

• Will emit cargo:rustc-env=VAR=VALUE for each feature you have enabled.
• Will emit cargo:rerun-if-changed=PATH if the git feature is enabled. This is done to ensure any git variables 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.

Errors

• The writeln! macro can throw a std::io::Error

Example

let emitter = Emitter::default().emit()?;

Sample Output

NOTE - You won’t see this output unless you invoke cargo with the -vv flag. The instruction output is not displayed by default.

cargo:rustc-env=VERGEN_BUILD_DATE=2023-01-04
cargo:rustc-env=VERGEN_BUILD_TIMESTAMP=2023-01-04T15:38:11.097507114Z
cargo:rustc-env=VERGEN_CARGO_DEBUG=true
cargo:rustc-env=VERGEN_CARGO_FEATURES=build,git
cargo:rustc-env=VERGEN_CARGO_OPT_LEVEL=1
cargo:rustc-env=VERGEN_CARGO_TARGET_TRIPLE=x86_64-unknown-linux-gnu
cargo:rustc-env=VERGEN_GIT_BRANCH=feature/version8
cargo:rustc-env=VERGEN_GIT_COMMIT_AUTHOR_EMAIL=your@email.com
cargo:rustc-env=VERGEN_GIT_COMMIT_AUTHOR_NAME=Yoda
cargo:rustc-env=VERGEN_GIT_COMMIT_COUNT=476
cargo:rustc-env=VERGEN_GIT_COMMIT_DATE=2023-01-03
cargo:rustc-env=VERGEN_GIT_COMMIT_MESSAGE=The best message
cargo:rustc-env=VERGEN_GIT_COMMIT_TIMESTAMP=2023-01-03T14:08:12.000000000-05:00
cargo:rustc-env=VERGEN_GIT_DESCRIBE=7.4.4-103-g53ae8a6
cargo:rustc-env=VERGEN_GIT_SHA=53ae8a69ab7917a2909af40f2e5d015f5b29ae28
cargo:rustc-env=VERGEN_RUSTC_CHANNEL=nightly
cargo:rustc-env=VERGEN_RUSTC_COMMIT_DATE=2023-01-03
cargo:rustc-env=VERGEN_RUSTC_COMMIT_HASH=c7572670a1302f5c7e245d069200e22da9df0316
cargo:rustc-env=VERGEN_RUSTC_HOST_TRIPLE=x86_64-unknown-linux-gnu
cargo:rustc-env=VERGEN_RUSTC_LLVM_VERSION=15.0
cargo:rustc-env=VERGEN_RUSTC_SEMVER=1.68.0-nightly
cargo:rustc-env=VERGEN_SYSINFO_NAME=Arch Linux
cargo:rustc-env=VERGEN_SYSINFO_OS_VERSION=Linux  Arch Linux
cargo:rustc-env=VERGEN_SYSINFO_USER=jozias
cargo:rustc-env=VERGEN_SYSINFO_TOTAL_MEMORY=31 GiB
cargo:rustc-env=VERGEN_SYSINFO_CPU_VENDOR=AuthenticAMD
cargo:rustc-env=VERGEN_SYSINFO_CPU_CORE_COUNT=8
cargo:rustc-env=VERGEN_SYSINFO_CPU_NAME=cpu0,cpu1,cpu2,cpu3,cpu4,cpu5,cpu6,cpu7
cargo:rustc-env=VERGEN_SYSINFO_CPU_BRAND=AMD Ryzen Threadripper 1900X 8-Core Processor
cargo:rustc-env=VERGEN_SYSINFO_CPU_FREQUENCY=3792
cargo:rerun-if-changed=.git/HEAD
cargo:rerun-if-changed=.git/refs/heads/feature/version8
cargo:rerun-if-changed=build.rs
cargo:rerun-if-env-changed=VERGEN_IDEMPOTENT
cargo:rerun-if-env-changed=SOURCE_DATE_EPOCH

pub fn emit_and_set(&self) -> Result<(), Error>

Available on crate feature emit_and_set only.

Emit cargo instructions from your build script and set environment variables for use in build.rs

• Will emit cargo:rustc-env=VAR=VALUE for each feature you have enabled.
• Will emit cargo:rerun-if-changed=PATH if the git feature is enabled. This is done to ensure any git variables 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.

Errors

• The writeln! macro can throw a std::io::Error

Example

Emitter::new().emit_and_set()?;

Trait Implementations

impl Clone for Emitter

fn clone(&self) -> Emitter

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Emitter

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Emitter

fn default() -> Emitter

Returns the “default value” for a type.

impl PartialEq for Emitter

fn eq(&self, other: &Emitter) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Emitter