#build #env-var #commit #data #branch #info #version-info

build build-data

Include build data in your program: date, rustc version, git commit & branch, etc

5 releases

0.2.1 Apr 18, 2024
0.2.0 Apr 18, 2024
0.1.5 Oct 6, 2023
0.1.4 Apr 16, 2023
0.1.3 Apr 18, 2021

#46 in Build Utils

Download history 4520/week @ 2024-06-13 6182/week @ 2024-06-20 5239/week @ 2024-06-27 4796/week @ 2024-07-04 4949/week @ 2024-07-11 5045/week @ 2024-07-18 4785/week @ 2024-07-25 5216/week @ 2024-08-01 5883/week @ 2024-08-08 4992/week @ 2024-08-15 5684/week @ 2024-08-22 4542/week @ 2024-08-29 5019/week @ 2024-09-05 3435/week @ 2024-09-12 4479/week @ 2024-09-19 3284/week @ 2024-09-26

17,431 downloads per month
Used in 10 crates (8 directly)

Apache-2.0

32KB
344 lines

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


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/0          0/0    0/0     0/0      🔒  build-data 0.2.1
0/0        1/11         1/1    0/0     0/0      ☢️  ├── chrono 0.4.38
0/0        0/0          0/0    0/0     0/0      ❓  │   └── num-traits 0.2.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.67
0/0        4/4          0/0    0/0     0/0      ☢️          │   └── unicode-ident 1.0.12
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.67
0/0        0/0          0/0    0/0     0/0      🔒              └── safe-quote 1.0.15
0/0        0/0          0/0    0/0     0/0      🔒                  └── safe-proc-macro2 1.0.67

0/0        5/15         1/1    0/0     0/0    

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

License: Apache-2.0

Dependencies

~1.5MB
~25K SLoC