Crate build_data

source ·
Expand description

§build-data

crates.io version license: Apache 2.0 unsafe forbidden pipeline status

Include build data in your program.

§Features

  • Saves build-time data:
    • Git commit, branch, and dirtiness
    • Source modification date & time
    • Rustc version
    • Rust channel (stable, nightly, or beta)
  • Does all of its work in your build.rs.
  • Sets environment variables. Use env! to use them in your program.
  • No macros
  • No runtime dependencies
  • Light build dependencies
  • forbid(unsafe_code)
  • 100% test coverage

§Alternatives

  • Environment variables that cargo sets for crates:
    • CARGO_PKG_NAME
    • CARGO_PKG_VERSION
    • CARGO_BIN_NAME
    • others
  • vergen
    • Mature & very popular
    • Good API, needs only env! to retrieve values
    • Excellent test coverage
    • Heavy build dependencies
  • build-info
    • Mature
    • Confusing API
    • Uses procedural macros

§Example

// Cargo.toml
[dependencies]

[build-dependencies]
build-data = "0"

Add a build.rs file next to your Cargo.toml. Call build_data::set_* functions to set variables.

// build.rs

fn main() {
    build_data::set_GIT_BRANCH();
    build_data::set_GIT_COMMIT();
    build_data::set_GIT_DIRTY();
    build_data::set_SOURCE_TIMESTAMP();
    build_data::no_debug_rebuilds();
}

Use env! to access the variables in your program:

// src/bin/main.rs
fn main() {
    // Built from branch=release
    // commit=a5547bfb1edb9712588f0f85d3e2c8ba618ac51f
    // dirty=false
    // source_timestamp=2021-04-14T06:25:59+00:00
    println!("Built from branch={} commit={} dirty={} source_timestamp={}",
        env!("GIT_BRANCH"),
        env!("GIT_COMMIT"),
        env!("GIT_DIRTY"),
        env!("SOURCE_TIMESTAMP"),
    );
}

§Cargo Geiger Safety Report

§Changelog

  • v0.2.0
    • Add set_TARGET. Thanks tison!
    • Use u64 for timestamps in helper functions.
  • v0.1.5 - Update a dependency. Thanks dignifiedquire!
  • v0.1.4 - Update a dependency.
  • v0.1.3 - Update docs.
  • v0.1.2 - Rewrote based on feedback from r/rust.
  • v0.1.1 - Update docs.
  • v0.1.0 - Initial version

§To Do

Enums§

Functions§