ci

CI for all possible combinations of features in Cargo.toml.
git clone https://git.philomathiclife.com/repos/ci
Log | Files | Refs | README

README.md (3267B)

      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 * `--color`: `--color always` is passed to the above commands; otherwise without this option, `--color never` is
     27   passed.
     28 * `--dir <path to directory Cargo.toml is in>`: `ci` changes the working directory to the passed path (after
     29   canonicalizing it) before executing. Without this, the working directory and all ancestor directories are searched
     30   for `Cargo.toml` before changing the working directory to its location.
     31 
     32 When `clippy`, `doc_tests`, and `tests` are not passed; then all three are invoked.
     33 
     34 ## Limitations
     35 
     36 Any use of `compile_error` _not_ related to incompatible features will be silently ignored. Any tests that
     37 are marked `ignored` will not be run.
     38 
     39 ## Minimum Supported Rust Version (MSRV)
     40 
     41 This will frequently be updated to be the same as stable. Specifically, any time stable is updated and that
     42 update has "useful" features or compilation no longer succeeds (e.g., due to new compiler lints), then MSRV
     43 will be updated.
     44 
     45 MSRV changes will correspond to a SemVer patch version bump pre-`1.0.0`; otherwise a minor version bump.
     46 
     47 ## SemVer Policy
     48 
     49 * All on-by-default features of this library are covered by SemVer
     50 * MSRV is considered exempt from SemVer as noted above
     51 
     52 ## License
     53 
     54 Licensed under either of
     55 
     56 * Apache License, Version 2.0 ([LICENSE-APACHE](https://www.apache.org/licenses/LICENSE-2.0))
     57 * MIT license ([LICENSE-MIT](https://opensource.org/licenses/MIT))
     58 
     59 at your option.
     60 
     61 ## Contribution
     62 
     63 Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you,
     64 as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
     65 
     66 Before any PR is sent, `cargo clippy` and `cargo t` should be run. Additionally
     67 `RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features` should be run to ensure documentation can be built.