# build_safely (previously ninja-build_rs)

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.

`ninja-build_rs` is now a transparent shim around the renamed `build_safely`,
the full git history is preserved, the original author remains and both crates
will be updated with every new version.

## Usage

```rust
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

```rust
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=[...]`
