#version #git #verbose #long

no-std build bosion

Gather build information for verbose versions flags

5 stable releases

1.1.0 May 16, 2024
1.0.3 Apr 20, 2024
1.0.2 Nov 26, 2023
1.0.1 Jul 3, 2023
1.0.0 Mar 5, 2023

#137 in Build Utils

Download history 192/week @ 2024-03-13 110/week @ 2024-03-20 176/week @ 2024-03-27 204/week @ 2024-04-03 147/week @ 2024-04-10 433/week @ 2024-04-17 346/week @ 2024-04-24 171/week @ 2024-05-01 195/week @ 2024-05-08 361/week @ 2024-05-15 180/week @ 2024-05-22 158/week @ 2024-05-29 172/week @ 2024-06-05 185/week @ 2024-06-12 193/week @ 2024-06-19 329/week @ 2024-06-26

908 downloads per month
Used in 2 crates (via watchexec-cli)

Apache-2.0 OR MIT

23KB
302 lines

Bosion

Gather build information for verbose versions flags.

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

Dependencies

~0.7–11MB
~123K SLoC