Skip to content

Latest commit

 

History

History
 
 

bosion

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
examples
examples
 
 
src
src
 
 
CHANGELOG.md
CHANGELOG.md
 
 
Cargo.toml
Cargo.toml
 
 
README.md
README.md
 
 
release.toml
release.toml
 
 
run-tests.sh
run-tests.sh
 
 

README.md

Bosion

Gather build information for verbose versions flags.

Quick start

In your Cargo.toml:

[build-dependencies]
bosion = "1.0.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