cargo-pkg-info-struct-builder

A Rust crate that operates as a build dependency which generates a source-code struct to provide access to compile-time package metadata, including versioning, authors, license information, and build details. This metadata is obtained from Cargo environment variables set during the build process and can be accessed at runtime without additional file I/O.

Why This is Injected at Compile Time

Unlike a typical crate that provides runtime metadata access, cargo-pkg-info-struct-builder injects metadata at compile time to ensure that it captures details about the entire project, not just the dependency itself.

If this crate were used as a standard Rust dependency, it would only retrieve the metadata of itself (i.e., cargo-pkg-info-struct-builder), not the actual project it is being used in. By injecting the metadata into your project’s source code at build time, it ensures that the correct package details—such as the main crate’s version, authors, and repository—are included in the final binary.

This approach:

• Captures project-wide metadata instead of dependency metadata.
• Avoids runtime file I/O since everything is embedded at compile time.
• Works with any Rust project without requiring dynamic runtime access to Cargo environment variables.
• Doesn't require repeatedly committing the auto-generated source file to version control, as it remains identical across builds and only changes if the template itself is modified, regardless of metadata updates.

Overview

cargo-pkg-info-struct-builder provides structured access to package metadata set by Cargo at compile time, including:

• Versioning (major, minor, patch, pre-release)
• Authors, description, homepage, and repository
• License information (including file contents)
• Rust version requirements
• Build target and timestamp

All values are retrieved from Cargo environment variables, ensuring no runtime file I/O is required. This crate is intended to run as a build dependency via build.rs.

It generates a struct in a specified path that can be committed to your source code, making the metadata easily accessible without needing additional file I/O at runtime.

Installation

cargo add cargo-pkg-info-struct-builder --build # Build dependency only

Usage

This crate is intended to be used in a build.rs script to inject the metadata into your project. Here’s an example usage:

In build.rs:

use cargo_pkg_info_struct_builder::inject_build_metadata;
use std::path::Path;

fn main() {
    // Example path for the generated metadata file
    let dest_path = Path::new("src").join("cargo_pkg_info.rs");

    // Inject build metadata into the specified file
    inject_build_metadata(dest_path.to_path_buf());
}

This function will generate a file with metadata at compile time, which is a struct that can be committed to your source code. It can be easily accessed from your Rust code via environment variables, with no additional file I/O required at runtime.

Example: Consuming the Generated Metadata in Your Application

Once the build script has generated the metadata struct (cargo_pkg_info.rs), you can access the metadata in your main application like this:

mod cargo_pkg_info;
use cargo_pkg_info::CargoPkgInfo;

fn main() {
    println!(
        "{:?} {:?} {:?} {:?} {:?}",
        CargoPkgInfo::pkg_name(),
        CargoPkgInfo::crate_name(),
        CargoPkgInfo::app_version(),
        CargoPkgInfo::build_target(),
        CargoPkgInfo::build_time_utc(),
    );
}

This code accesses the metadata generated by cargo-pkg-info-struct-builder and prints out the following details:

• Package name (pkg_name())
• Crate name (crate_name())
• Full version (app_version())
• Compilation target (build_target())
• Build timestamp (build_time_utc())

Available Metadata Methods

Notes

• Compile-time efficiency: The metadata is accessed directly from environment variables set during the compilation process, without requiring any file reads at runtime.
• Safe defaults: If an environment variable is missing, "N/A" is returned (Option types are used for non-string types).
• Generated Struct: The metadata is made available at compile time through a struct (CargoPkgInfo) that is generated by the build script. This struct contains methods for accessing the metadata, which is populated from the Cargo environment variables. The struct can be committed to source control, allowing the metadata to be accessed directly from the Rust code at runtime, without any file I/O or runtime environment access.

License

Licensed under MIT. See LICENSE for details.