Crate build_safely 

Designed to help create good build scripts, with a focus on ease of use for you, valuable output in cargo build -vv & no annoying surprises for anyone downstream.

Usage

use build_safely::prelude::*;

// Result uses BuildError to give meaningful messages
fn main() -> Result<()> {

    // get an environment variable and re-run build script if it changes.
    let my_var: String = get_var("MY_VAR")?;

    // get values from an environment variable, separated by the
    // OS path separator and re-run build script if it changes.
    let my_vals: IndexSet<String> = split_var("MY_VALUES")?;
    if my_vals.contains("some_value") {
        unimplemented!("do something")
    }

    // get a new AutoCfg or provide a valuable error
    // rather than panicking.
    let ac = AutoCfg::new()?;

    // check to see if the downstream crate has defined
    // `unstable.allow-features` in `.cargo/config.toml`.
    // It is mandatory to perform this check and pass the
    // result to any calls to `emit_unstable_feature`
    let allowed_features = cargo_allowed_features()?;

    // We want to make use of `assert_matches` if it is available
    ac.emit_unstable_feature(assert_matches, &allowed_features);
    //                       ^^^^^^^^^^^^^^ - enum variant to avoid typos

    Ok(())
}

Prelude

use build_safely::prelude::*;

provides:

• A Result alias & BuildError type that gives meaningful output from main() -> Result<()>.
• get_var() & split_var() which automatically register cargo::rerun-if-env-changed and include the variable name in any errors.
• emit_unstable_feature(), cargo_allowed_features & enum UnstableFeature to provide a safe way to identify the availability of nightly features & handle the future stabilisation process without additional effort on your part. All while respecting any allow-features whitelists.

Note to downstream crates

If you (transiently) depend on a crate which uses build_safely and have implemented a whitelist of allowed-features.

Due to limitations in the information provided by cargo:

• This will obtain config.toml files based upon OUT_DIR. If this is not under the project root, you can override by providing an alternative path via the environment variable BUILD_SAFELY_CARGO_CONFIG_DIR. See cargo’s documentation on config file hierarchical structure for more details.
• This will not respect additional entries passed at the command line via cargo --config unstable.allow-features=[...]

Modules

nightly

Checking for experimental or stabilised features is prone to subtle errors which create issues for downstream users and verbose when done properly. This provides extensions to the amazing autocfg::AutoCfg (re-exported via our prelude to make your life easier) to safely identify the availability of nightly features & handle the future stabilisation process without additional effort on your part. All while respecting any allow-features whitelists.

prelude

Recommended prelude: use build_safely::prelude::*

Enums

BuildError

An error designed to have nice debug representations for common errors encountered in build.rs

Functions

get_var

Attempt to get an environment variable, re-run build if it changes or provide a meaningful error if missing.

split_var

Attempt to get an environment variable and split the values using the OS path separator, re-run build if it changes or provide a meaningful error if missing.

Type Aliases

Result

Result type wrapping BuildError. Using main() -> Result<()> in build.rs will provide useful information in the debug representation sent to stderr on failure.