Docs incomplete - `error: environment variable VERGEN_... not defined at compile time`

[JDeeth]

Sorry if I'm missing something incredibly obvious, but I think there's a step missing in the current Usage section? I get error: environment variable VERGEN_... not defined at compile time when I try to build my crate.

Steps:

1. cargo new vergen-hello, cd vergen-hello
2. update Cargo.toml as per docs
3. create build.rs in project root as per docs
4. add env!("VERGEN_BUILD_TIMESTAMP") to src/main.rs
5. cargo build > error: environment variable VERGEN_BUILD_TIMESTAMP not defined at compile time

# cargo.toml
[package]
name = "vergen-hello"
version = "0.1.0"
edition = "2021"
build = "build.rs"

[dependencies]

[build-dependencies]
vergen = { version = "8", features = ["build"]}

// build.rs
use std::error::Error;
use vergen::EmitBuilder;

fn main() -> Result<(), Box<dyn Error>> {
    EmitBuilder::builder().emit()?;
    Ok(())
}

// src/main.rs
fn main() {
    println!("Build timestamp: {}", env!("VERGEN_BUILD_TIMESTAMP"));
}

cargo build output:

jack@x240deb:~/dev/rust-lang/vergen-hello$ cargo build
   Compiling vergen-hello v0.1.0 (/home/jack/dev/rust-lang/vergen-hello)
error: environment variable `VERGEN_BUILD_TIMESTAMP` not defined at compile time
 --> src/main.rs:3:37
  |
3 |     println!("Build timestamp: {}", env!("VERGEN_BUILD_TIMESTAMP"));
  |                                     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  |
  = help: use `std::env::var("VERGEN_BUILD_TIMESTAMP")` to read the variable at run time
  = note: this error originates in the macro `env` (in Nightly builds, run with -Z macro-backtrace for more info)

error: could not compile `vergen-hello` (bin "vergen-hello") due to previous error

I've had the exact same result on Windows and Debian... sorry again if it's something elementary with Cargo I've not understood yet!

rustc v1.75.0

[JDeeth]

Well I found the minimal solution to my example: EmitBuilder::builder().all_build().emit()?;

Could the Usage section instead have the full example from the EmitBuilder::emit docs perhaps? If I understand right (if!), the current usage example simply does not emit anything!

edit: actually yes, if you start with EmitBuilder::builder().all_foo().all_bar().emit() then the compiler tells you nicely which methods to remove for the features you've not selected, which is pretty intuitive.

[CraZySacX]

Yeah, I admit the docs are not great at the top level. It's been awhile, but as I recall it was difficult to ensure that all of the configurations work at when the documentation is generated, but I think I can work around that now.