.. | ||
examples | ||
src | ||
Cargo.toml | ||
CHANGELOG.md | ||
README.md | ||
release.toml | ||
run-tests.sh |
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 = "0.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
: readsSOURCE_DATE_EPOCH
(default).git
: enables gathering git information (default).std
: enables thelong_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