Crate build_data

Source

Expand description

§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.3 - Add rerun_if_git_commit_or_branch_changed.
v0.2.2 - Fix get_source_time when git config has log.showsignature=true.
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.
rerun_if_git_commit_or_branch_changed: Tells Cargo to re-run the build if the git commit or branch changed.
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.

Crate build_dataCopy item path