built 0.8.1

To use built, you must call built::write_built_file() within your build.rs script. This collects build-environment information and serializes it into a Rust file in your OUT_DIR.

// In build.rs
fn main() {
    built::write_built_file().expect("Failed to acquire build-time information")
}

After running the build script, you can include the generated information as a module in your lib.rs or main.rs using the include! macro pointing to the file in OUT_DIR. This provides access to metadata such as PKG_VERSION, TARGET, RUSTC_VERSION, and CI_PLATFORM.

// In lib.rs or main.rs

// Include the generated-file as a separate module
pub mod built_info {
    include!(concat!(env!("OUT_DIR"), "/built.rs"));
}

println!(
    "This is version {}, built for {} by {}.",
    built_info::PKG_VERSION,
    built_info::TARGET,
    built_info::RUSTC_VERSION
);

You can manually set the values collected by built using environment variables. This is useful for automated build systems or achieving reproducible builds.

Naming Convention: Override variables must be prefixed with BUILT_OVERRIDE_{PKG_NAME}_, where {PKG_NAME} is your package name (with hyphens replaced by underscores). For example, if your package is my-cool-app, the prefix is BUILT_OVERRIDE_my_cool_app_.

Parsing Rules:

• Strings: Used as-is.
• Integers/Booleans: Must implement std::str::FromStr.
• Options (Option<T>): Use BUILT_OVERRIDE_NONE to force None. Any other value must parse as T.
• Lists: Parsed as comma-separated values.

If an override variable cannot be parsed, the build will panic.

You can force specific values for environment variables during the build process by using the BUILT_OVERRIDE_ prefix. The prefix is dynamically generated based on your package name (with hyphens replaced by underscores).

Pattern: BUILT_OVERRIDE_<package_name_with_underscores>_<VARIABLE_NAME>

Example: If your package name is example-project, the prefix is BUILT_OVERRIDE_example_project_. To override the RUSTC path, set the environment variable: BUILT_OVERRIDE_example_project_RUSTC=/path/to/custom/rustc

To use built to collect build-time metadata, follow these three steps:

1. Add as a build dependency: Add built to your [build-dependencies] in Cargo.toml.
2. Configure build script: Create or modify build.rs to call built::write_built_file().
3. Include generated code: In your crate (e.g., main.rs or lib.rs), use the include! macro to pull in the generated built.rs file from the OUT_DIR.

Note: built does not add runtime dependencies unless you explicitly enable features like chrono or semver and include them in your runtime dependency list.

[package]
build = "build.rs"

[build-dependencies]
built = "0.8"

// build.rs
fn main() {
    built::write_built_file().expect("Failed to acquire build-time information");
}

// main.rs
pub mod built_info {
   include!(concat!(env!("OUT_DIR"), "/built.rs"));
}

The generated built_info module contains a CI_PLATFORM field (an Option<&str>) indicating if the crate was built on a platform like Github Actions, Travis CI, or AppVeyor. Additionally, you can use built::util::detect_ci() to check if the code is currently executing on a CI platform.

match built_info::CI_PLATFORM {
    None => print!("It seems I've not been built on a continuous integration platform,"),
    Some(ci) => print!("I've been built on CI-platform {},", ci),
}

if built::util::detect_ci().is_some() {
    println!(" but I'm currently executing on one!");
} else {
    println!(" and I'm currently not executing on one!");
}

The detect_ci() method on EnvironmentMap attempts to identify the Continuous Integration environment by checking for specific environment variables.

It returns an Option<CIPlatform>. Supported platforms include:

• GitHubActions (GITHUB_ACTIONS)
• GitLab (GITLAB_CI)
• Circle (CIRCLECI)
• Travis (TRAVIS)
• Jenkins (JENKINS_URL)
• Buildkite (BUILDKITE)
• ...and many others (AppVeyor, Drone, TeamCity, etc.).

If no specific platform is recognized but a generic CI variable is present, it returns CIPlatform::Generic.

The built crate provides two main functions to generate the built.rs file during the build process:

1. write_built_file(): A shorthand that writes to [OUT_DIR]/built.rs using CARGO_MANIFEST_DIR as the manifest location. This is the recommended function for most users.
2. write_built_file_with_opts(manifest_location: Option<&Path>, dst: &Path): Allows specifying a custom manifest location and a custom destination path.

Both functions return io::Result<()>.

// Standard usage in build.rs
fn main() {
    built::write_built_file().expect("Failed to write built file");
}