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.3"

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().unwrap();
    build_data::set_GIT_COMMIT().unwrap();
    build_data::set_GIT_DIRTY().unwrap();
    build_data::set_SOURCE_TIMESTAMP().unwrap();
    build_data::no_debug_rebuilds().unwrap();
}

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

Metric output format: x/y
    x = unsafe code used by the build
    y = total unsafe code found in the crate

Symbols:
    🔒  = No `unsafe` usage found, declares #![forbid(unsafe_code)]
    ❓  = No `unsafe` usage found, missing #![forbid(unsafe_code)]
    ☢️  = `unsafe` usage found

Functions  Expressions  Impls  Traits  Methods  Dependency

0/0        0/6          0/0    0/0     0/0      🔒  build-data 0.3.3
0/0        1/13         1/1    0/0     0/0      ☢️  ├── chrono 0.4.41
0/0        0/0          0/0    0/0     0/0      ❓  │   ├── num-traits 0.2.19
0/0        0/5          0/0    0/0     0/0      ❓  │   └── serde 1.0.219
0/0        0/0          0/0    0/0     0/0      ❓  │       └── serde_derive 1.0.219
0/0        0/14         0/0    0/0     0/3      ❓  │           ├── proc-macro2 1.0.95
0/0        0/4          0/0    0/0     0/0      ❓  │           │   └── unicode-ident 1.0.18
0/0        0/0          0/0    0/0     0/0      ❓  │           ├── quote 1.0.40
0/0        0/14         0/0    0/0     0/3      ❓  │           │   └── proc-macro2 1.0.95
0/0        0/88         0/3    0/0     0/2      ❓  │           └── syn 2.0.101
0/0        0/14         0/0    0/0     0/3      ❓  │               ├── proc-macro2 1.0.95
0/0        0/0          0/0    0/0     0/0      ❓  │               ├── quote 1.0.40
0/0        0/4          0/0    0/0     0/0      ❓  │               └── unicode-ident 1.0.18
0/0        0/0          0/0    0/0     0/0      🔒  └── safe-regex 0.3.0
0/0        0/0          0/0    0/0     0/0      🔒      └── safe-regex-macro 0.3.0
0/0        0/0          0/0    0/0     0/0      🔒          ├── safe-proc-macro2 1.0.95
0/0        0/0          0/0    0/0     0/0      🔒          │   └── unicode-xid 0.2.6
0/0        0/0          0/0    0/0     0/0      🔒          └── safe-regex-compiler 0.3.0
0/0        0/0          0/0    0/0     0/0      🔒              ├── safe-proc-macro2 1.0.95
0/0        0/0          0/0    0/0     0/0      🔒              └── safe-quote 1.0.40
0/0        0/0          0/0    0/0     0/0      🔒                  └── safe-proc-macro2 1.0.95

0/0        1/130        1/4    0/0     0/5

Changelog

• v0.3.3 - Rebuild docs.
• v0.3.2 - Remove test binaries.
• v0.3.1 - Rebuild docs.
• v0.3.0 - Return Result and don't panic.
• 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

License: Apache-2.0