README.md (3473B)
1 # `ci` 2 3 `ci` is a CLI application that runs [`cargo`](https://doc.rust-lang.org/cargo/index.html) with 4 `clippy -q`, `t -q --doc`, and `t -q --tests` with all possible combinations of features defined in `Cargo.toml`. 5 6 `ci` avoids superfluous combinations of features. For example if feature `foo` automatically enables 7 feature `bar` and `bar` automatically enables feature `fizz`, then no combination of features that contains 8 `foo` and `bar`, `foo` and `fizz`, or `bar` and `fizz` will be tested. 9 10 `ci` writes to `stderr` iff a command errors for a reason other than `compile_error` or `stderr` is written 11 to on success. When a non-`compile_error` occurs, `ci` is terminated after writing the offending command and 12 features. Upon successful completion, `ci` writes all _unique_ messages that were collected. `stdout` is 13 never written to. 14 15 ## Why is this useful? 16 17 The number of possible configurations grows exponentially based on the number of features in `Cargo.toml`. 18 This can easily cause a crate to not be tested with certain combinations of features. Instead of manually 19 invoking `cargo` with each possible combination of features, this handles it automatically. 20 21 ## Options 22 23 * `clippy`: `cargo clippy -q` is invoked for each combination of features. 24 * `doc_tests`: `cargo t -q --doc` is invoked for each combination of features. 25 * `tests`: `cargo t -q --tests` is invoked for each combination of features. 26 * `ignored`: `cargo t -q --tests -- --ignored` is invoked for each combination of features. 27 * `include-ignored`: `cargo t -q --tests -- --include-ignored` is invoked for each combination of features. 28 * `--color`: `--color always` is passed to the above commands; otherwise without this option, `--color never` is 29 passed. 30 * `--dir <path to directory Cargo.toml is in>`: `ci` changes the working directory to the passed path (after 31 canonicalizing it) before executing. Without this, the working directory and all ancestor directories are searched 32 for `Cargo.toml` before changing the working directory to its location. 33 34 When `clippy`, `doc_tests`, `tests`, `ignored`, and `include-ignored` are not passed; then `clippy`, `doc_tests`, 35 and `tests` are all invoked. 36 37 ## Limitations 38 39 Any use of `compile_error` _not_ related to incompatible features will be silently ignored. 40 41 ## Minimum Supported Rust Version (MSRV) 42 43 This will frequently be updated to be the same as stable. Specifically, any time stable is updated and that 44 update has "useful" features or compilation no longer succeeds (e.g., due to new compiler lints), then MSRV 45 will be updated. 46 47 MSRV changes will correspond to a SemVer patch version bump pre-`1.0.0`; otherwise a minor version bump. 48 49 ## SemVer Policy 50 51 * All on-by-default features of this library are covered by SemVer 52 * MSRV is considered exempt from SemVer as noted above 53 54 ## License 55 56 Licensed under either of 57 58 * Apache License, Version 2.0 ([LICENSE-APACHE](https://www.apache.org/licenses/LICENSE-2.0)) 59 * MIT license ([LICENSE-MIT](https://opensource.org/licenses/MIT)) 60 61 at your option. 62 63 ## Contribution 64 65 Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, 66 as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions. 67 68 Before any PR is sent, `cargo clippy` and `cargo t` should be run. Additionally 69 `RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features` should be run to ensure documentation can be built.