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