Crate build_data

build-data

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.1
  • Add set_TARGET_PLATFORM. 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

• RustChannel

Functions

• escape_ascii
  Converts a byte slice into a string using core::ascii::escape_default to escape each byte.
• exec
  Executes cmd with args as parameters, waits for it to exit, and returns its stdout, trimmed, and escaped with escape_ascii.
• format_date
  Formats the epoch timestamp as a UTC date like "2021-05-04Z".
• format_time
  Formats the epoch timestamp as a UTC time like "13:02:59Z".
• format_timestamp
  Formats the epoch timestamp as a UTC timestamp like "20201-05-04T13:02:59Z".
• get_env
  Gets the environment variable named name if it is set.
• get_git_branch
  Gets the current branch of the source code directory.
• get_git_commit
  Gets the latest git commit of the source code directory.
• get_git_commit_short
  Gets the latest git commit of the source code directory. Returns the truncated hash.
• get_git_dirty
  Returns true if the source directory contains uncommitted changes.
• get_hostname
  Gets the name of the current machine.
• get_rustc_version
  Gets the version of the Rust compiler used to build the build script.
• get_source_time
  Gets the modification time of the source code.
• get_target_platform
  Gets the Rust target platform string. See set_TARGET_PLATFORM.
• no_debug_rebuilds
  Tells cargo not to rebuild build.rs during debug builds when other files change.
• now
  Gets the current time as an epoch timestamp, caching it so future calls return the same time.
• parse_rustc_channel
  Gets the channel from the rustc version string.
• parse_rustc_semver
  Gets the dotted-numeric version from the rustc version string.
• parse_rustc_version
  Parses the output of rustc --version.
• set_BUILD_DATE
  Sets the BUILD_DATE env variable with the current date, in UTC.
• set_BUILD_EPOCH_TIME
  Sets the BUILD_EPOCH_TIME env variable, with the current time.
• set_BUILD_HOSTNAME
  Sets the BUILD_HOSTNAME env variable, with the hostname of the machine executing the build.
• set_BUILD_TIME
  Sets the BUILD_TIME env variable, with the current time, in UTC.
• set_BUILD_TIMESTAMP
  Sets the BUILD_TIMESTAMP env variable, with the current date & time, in UTC.
• set_GIT_BRANCH
  Sets the GIT_BRANCH env variable.
• set_GIT_COMMIT
  Sets the GIT_COMMIT env variable.
• set_GIT_COMMIT_SHORT
  Sets the GIT_COMMIT_SHORT env variable.
• set_GIT_DIRTY
  Sets the GIT_DIRTY env variable.
• set_RUSTC_VERSION
  Sets the RUSTC_VERSION env variable to the output of rustc --version.
• set_RUSTC_VERSION_SEMVER
  Sets the RUSTC_VERSION_SEMVER to the dotted version number of the rustc used by the current build.
• set_RUST_CHANNEL
  Sets the RUST_CHANNEL env variable to Rust channel used by the current build.
• set_SOURCE_DATE
  Sets the SOURCE_DATE env variable.
• set_SOURCE_EPOCH_TIME
  Sets the SOURCE_EPOCH_TIME env variable.
• set_SOURCE_TIME
  Sets the SOURCE_TIME env variable.
• set_SOURCE_TIMESTAMP
  Sets the SOURCE_TIMESTAMP env variable.
• set_TARGET_PLATFORM
  Sets the TARGET_PLATFORM env variable to the Rust target triple. See “Target Triple” in The Cargo Book - Glossary.