IROX-BUILD-RS

Compile-time build metadata injection inspired by shadow-rs

Quick-start

Part 1: Generating the metadata during the build

Create a build.rs file in your module, and include the defaults:

pub fn main() -> Result<(), irox_build_rs::Error> {
    println!("cargo:rerun-if-changed=build.rs");

    irox_build_rs::generate_module()?;

    Ok(())
}

Ensure your Cargo.toml has:

[build-dependencies]
irox-build-rs = "{latest-version}"

To include variables from Git, include the 'git' feature:

[build-dependencies]
irox-build-rs = { version = "{latest-version}", features = ["git"] }

Part 2: Including the build metadata

Somwhere in your module, usually in your top level lib.rs/main.rs:

pub mod build {
    include!(concat!(env!("OUT_DIR"), "/builders.rs"));
}

Part 3: Use them!

fn main() {
    println!("{}", build::CARGO_PKG_NAME);
    
    for (name, value) in build::get_ALL_ITEMS() {
        println!("{name} => {value}");
    }
}

Each of the sets of generated constants below are available in BTreeMap<&str, &str>'s as well:

use std::collections::BTreeMap;

fn main() {
    let cargo_items: &BTreeMap<&str, &str> = build::get_CARGO_ITEMS();
    let rustc_items: &BTreeMap<&str, &str> = build::get_RUSTC_ITEMS();
    let git_items: &BTreeMap<&str, &str> = build::get_GIT_ITEMS();
    
    // all_items is the union of all the sets
    let all_items: &BTreeMap<&str, &str> = build::get_ALL_ITEMS();
}

Generated Constants

From Cargo:

Consult The Cargo Book for details:

pub const CARGO_CFG_TARGET_ARCH: &str = "x86_64";
pub const CARGO_CFG_TARGET_ENDIAN: &str = "little";
pub const CARGO_CFG_TARGET_ENV: &str = "gnu";
pub const CARGO_CFG_TARGET_FAMILY: &str = "windows";
pub const CARGO_CFG_TARGET_FEATURE: &str = "fxsr,sse,sse2";
pub const CARGO_CFG_TARGET_HAS_ATOMIC: &str = "16,32,64,8,ptr";
pub const CARGO_CFG_TARGET_OS: &str = "windows";
pub const CARGO_CFG_TARGET_POINTER_WIDTH: &str = "64";
pub const CARGO_CFG_TARGET_VENDOR: &str = "pc";
pub const CARGO_PKG_AUTHORS: &str = "Sean P. Madden <sean@seanmadden.net>";
pub const CARGO_PKG_BIN_NAME: &str = "";
pub const CARGO_PKG_CRATE_NAME: &str = "";
pub const CARGO_PKG_DESCRIPTION: &str = "Extras & tweaks for the egui framework";
pub const CARGO_PKG_HOMEPAGE: &str = "https://github.com/spmadden/irox";
pub const CARGO_PKG_LICENSE: &str = "MIT OR Apache-2.0";
pub const CARGO_PKG_LICENSE_FILE: &str = "";
pub const CARGO_PKG_NAME: &str = "irox-egui-extras";
pub const CARGO_PKG_README: &str = "README.md";
pub const CARGO_PKG_REPOSITORY: &str = "https://github.com/spmadden/irox";
pub const CARGO_PKG_RUST_VERSION: &str = "";
pub const CARGO_PKG_VERSION: &str = "0.3.5";
pub const CARGO_PKG_VERSION_MAJOR: &str = "0";
pub const CARGO_PKG_VERSION_MINOR: &str = "3";
pub const CARGO_PKG_VERSION_PATCH: &str = "5";
pub const CARGO_PKG_VERSION_PRE: &str = "";
pub const CARGO_PRIMARY_PACKAGE: &str = "";

From Cargo, for Rustc

Consult The Cargo Book for details:

pub const DEBUG: &str = "true"; // "true" 
pub const HOST: &str = "x86_64-pc-windows-gnu";
pub const OPT_LEVEL: &str = "0";
pub const PROCESSOR_ARCHITECTURE: &str = "AMD64";
pub const PROCESSOR_IDENTIFIER: &str = "AMD64 Family 23 Model 113 Stepping 0, AuthenticAMD";
pub const PROCESSOR_LEVEL: &str = "23";
pub const PROCESSOR_REVISION: &str = "7100";
pub const PROFILE: &str = "debug";
pub const RUSTUP_TOOLCHAIN: &str = "1.74-x86_64-pc-windows-gnu";
pub const TARGET: &str = "x86_64-pc-windows-gnu";

From Git, with feature 'git'

pub const GIT_COMMIT_AUTHOR: &str = "user.name <user.email>";
pub const GIT_COMMIT_DATETIME: &str = "2023-11-09T04:07:06Z"; // ISO8601 UTC date-time from the commit timestamp
pub const GIT_COMMIT_FULLHASH: &str = "6a22a45109c9f8ab27971c8919d693bd995f0a16"; // Full hash of the current HEAD
pub const GIT_COMMIT_SHORTHASH: &str = "6a22a45"; // Short hash of the current HEAD
pub const GIT_COMMIT_TIMESTAMP_SECS: i64 = 1699502826; // Unix timestamp in UTC of the HEAD commit
pub const GIT_COMMIT_TZ_OFFSET_SECS: i64 = -18000; // Timezone Offset (seconds) from UTC of the HEAD commit
pub const GIT_DESCRIBE: &str = "irox-build-rs-g2c9c199-dirty";  // <module-name>-g<module-short-hash><-dirty>
pub const GIT_IS_CLEAN: bool = false; // true if `git status` reports clean