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.

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() {
    // Create an instance of the struct generated at build time
    let cargo_pkg_info = CargoPkgInfo::new();

    // Print out various metadata fields from the struct
    println!(
        "{:?} {:?} {:?} {:?} {:?}",
        cargo_pkg_info.app_name(),
        cargo_pkg_info.crate_name(),
        cargo_pkg_info.app_version(),
        cargo_pkg_info.build_target(),
        cargo_pkg_info.build_time_utc(),
    );
}

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

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

Available Metadata Methods

Method	Description
`app_name()`	Package name (`CARGO_PKG_NAME`)
`crate_name()`	Crate name (`CARGO_CRATE_NAME`)
`app_version()`	Full version (`CARGO_PKG_VERSION`)
`version_major()`	Major version (`CARGO_PKG_VERSION_MAJOR`)
`version_minor()`	Minor version (`CARGO_PKG_VERSION_MINOR`)
`version_patch()`	Patch version (`CARGO_PKG_VERSION_PATCH`)
`version_pre()`	Pre-release version (`CARGO_PKG_VERSION_PRE`)
`authors()`	Authors (`CARGO_PKG_AUTHORS`)
`description()`	Description (`CARGO_PKG_DESCRIPTION`)
`homepage()`	Homepage URL (`CARGO_PKG_HOMEPAGE`)
`repository()`	Repository URL (`CARGO_PKG_REPOSITORY`)
`license()`	License name (`CARGO_PKG_LICENSE`)
`license_content()`	Full license text (`CARGO_PKG_LICENSE_FILE`)
`rust_version()`	Required Rust version (`CARGO_PKG_RUST_VERSION`)
`readme_path()`	Path to README file (`CARGO_PKG_README`)
`build_target()`	Compilation target (`BUILD_TARGET`)
`build_time_utc()`	Build timestamp UTC (`BUILD_TIME_UTC`)

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.

cargo-pkg-info-struct-builder 0.1.0-alpha1