Cargo commands run conditionally upon rustc version and environment. Cargo
commands can aid in continuous integration scripts, among other uses.
Two cargo commands are provided,
unless is simply the negated condition of
when and has the exact same options. From the
when command line help documentation:
Runs subsequent cargo command only when the specified options match the current rust compiler version and environment. USAGE: cargo when [OPTIONS] <CARGO SUBCOMMAND> [SUBCOMMAND OPTIONS] FLAGS: -h, --help Prints help information OPTIONS: -c, --channel <CHANNEL> Matches rustc release channel(s) [values: stable, beta, nightly] -x, --exists <ENV-VARIABLE> Matches when environment variable(s) exist -e, --equals <ENV-VARIABLE=VALUE> Matches when environment variable(s) equals specified value(s), e.g. RUST_SRC_PATH=~/rustsrc -v, --version <VERSION> Matches rustc version(s) using same rules and version syntax as Cargo To specify a set of multiple possible matches for an option, separate the values by a comma and no spaces. At least one match option is required. If multiple match options are present, each option specifies an additional match requirement for any of the set of possible values for that option.
If you only want to compile and test a crate on the nightly rust compiler, and use a specialy "nightly" feature, use this command:
cargo when --channel nightly build --features nightly && cargo when --channel nightly test
If the rust compiler is not the nightly compiler, the cargo command will simply return a zero exit
code for success without actually running the
test cargo command.
If, instead, you know that your crate doesn't build properly on nightly and simply wish to skip nightly, either of the following examples will work:
cargo unless --channel nightly build
cargo when --channel stable,beta build
You can provide multiple match requirements for the
unless commands. Let's say you have
a crate that only builds on stable Rust 1.5 or higher. You could use the following command:
cargo when --channel stable --version 1.5 build
The version match option behaves exactly like specifying a Cargo dependency; it defaults to a caret
version requirement, meaning any stable Rust compiler version >= 1.5.0 but <= 2.0 will call
cargo build. Otherwise, nightly, beta, and 1.0 Rust will fail to build. You can use any version
dependency specification you would for Cargo for your Rust compiler! (Just be sure to add
double-quotes when the version strings contain special shell characters.)
In the following example, the crate worked until Rust 1.4, then is fixed again in 1.5 and up:
cargo when --version "<1.4,1.5" build --release
You can use
unless to check environment variables to determine whether a cargo command
should be run. The following example will only run the crate executable if the RUST_SRC_PATH
variable that the executable requires for its
srcpath option is set to any value in the current
cargo when --exists RUST_SRC_PATH run --srcpath="$RUST_SRC_PATH"
You can also test if the environment variable is set to specific values, for instance, this command won't cause any errors in any other shells, but will only run the crate tests when run from a bash shell, because someday somewhere this may prove useful to someone:
cargo when --equals SHELL=bash test
Example Travis CI Usage
when command works well in a continuous integration environment like
Travis CI. Here's one example scenario featuring nightly-only features and
building docs only on stable for later upload:
sudo: false language: rust rust: - stable - 1.8.0 - beta - nightly before_script: - | cargo install cargo-when script: - | cargo unless --channel=nightly build --verbose && cargo when --channel=nightly build --verbose --features nightly && cargo unless --channel=nightly test --verbose && cargo when --channel=nightly test --verbose --features nightly && cargo when --channel=stable doc
This library is distributed under the terms of either of:
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.