watchexec/crates/bosion

Bosion

Gather build information for verbose versions flags.

• API documentation.
• Licensed under Apache 2.0 or MIT.
• Status: maintained.

Quick start

In your Cargo.toml:

[build-dependencies]
bosion = "1.1.0"

In your build.rs:

fn main() {
    bosion::gather();
}

In your src/main.rs:

include!(env!("BOSION_PATH"));

fn main() {
    // default output, like rustc -Vv
    println!("{}", Bosion::LONG_VERSION);

    // with additional fields
    println!("{}", Bosion::long_version_with(&[
        ("custom data", "value"),
        ("LLVM version", "15.0.6"),
    ]));

    // enabled features like +feature +an-other
    println!("{}", Bosion::CRATE_FEATURE_STRING);

    // the raw data
    println!("{}", Bosion::GIT_COMMIT_HASH);
    println!("{}", Bosion::GIT_COMMIT_SHORTHASH);
    println!("{}", Bosion::GIT_COMMIT_DATE);
    println!("{}", Bosion::GIT_COMMIT_DATETIME);
    println!("{}", Bosion::CRATE_VERSION);
    println!("{:?}", Bosion::CRATE_FEATURES);
    println!("{}", Bosion::BUILD_DATE);
    println!("{}", Bosion::BUILD_DATETIME);
}

Advanced usage

Generating a struct with public visibility:

// build.rs
bosion::gather_pub();

Customising the output file and struct names:

// build.rs
bosion::gather_to("buildinfo.rs", "Build", /* public? */ false);

Outputting build-time environment variables instead of source:

// build.rs
bosion::gather_to_env();

// src/main.rs
fn main() {
    println!("{}", env!("BOSION_GIT_COMMIT_HASH"));
    println!("{}", env!("BOSION_GIT_COMMIT_SHORTHASH"));
    println!("{}", env!("BOSION_GIT_COMMIT_DATE"));
    println!("{}", env!("BOSION_GIT_COMMIT_DATETIME"));
    println!("{}", env!("BOSION_BUILD_DATE"));
    println!("{}", env!("BOSION_BUILD_DATETIME"));
    println!("{}", env!("BOSION_CRATE_VERSION"));
    println!("{}", env!("BOSION_CRATE_FEATURES")); // comma-separated
}

Custom env prefix:

// build.rs
bosion::gather_to_env_with_prefix("MYAPP_");

Features

• reproducible: reads SOURCE_DATE_EPOCH (default).
• git: enables gathering git information (default).
• std: enables the long_version_with method (default). Specifically, this is about the downstream crate's std support, not Bosion's, which always requires std.

Why not...?

• bugreport: runtime library, for bug information.
• git-testament: uses the git CLI instead of gitoxide.
• human-panic: runtime library, for panics.
• shadow-rs: uses libgit2 instead of gitoxide, doesn't rebuild on git changes.
• vergen: uses the git CLI instead of gitoxide.

Bosion also requires no dependencies outside of build.rs, and was specifically made for crates installed in a variety of ways, like with cargo install, from pre-built binary, from source with git, or from source without git (like a tarball), on a variety of platforms. Its default output with clap is almost exactly like rustc -Vv.

Examples

The examples directory contains a practical and runnable clap-based example, as well as several other crates which are actually used for integration testing.

Here is the output for the Watchexec CLI:

watchexec 1.21.1 (5026793 2023-03-05)
commit-hash: 5026793a12ff895edf2dafb92111e7bd1767650e
commit-date: 2023-03-05
build-date: 2023-03-05
release: 1.21.1
features:

For comparison, here's rustc -Vv:

rustc 1.67.1 (d5a82bbd2 2023-02-07)
binary: rustc
commit-hash: d5a82bbd26e1ad8b7401f6a718a9c57c96905483
commit-date: 2023-02-07
host: x86_64-unknown-linux-gnu
release: 1.67.1
LLVM version: 15.0.6