travis-cargo
This provides a standalone script travis-cargo
that manages running
cargo and several other related features on Travis CI (and
somewhat on AppVeyor).
Features:
- run commands only on specific versions of the compiler
- insert a feature flag when using a nightly compiler to enable conditional use of unstable features
- automatically only run
cargo bench
when supported (nightly compiler) - upload documentation via the technique
described by hoverbear with
my modifications to avoid
sudo
(in particular, it requires an encyptedGH_TOKEN
) - record total test coverage across in-crate and external tests, and
upload to coveralls.io. NB. this requires
sudo
on Travis, and thetest
profile must havedebug = true
(this is the default)
The script is designed to automatically work with both Python 2 and Python 3.
I've written some things about this:
Installation
pip install 'travis-cargo<0.2' --user
export PATH=`python -m site --user-base`/bin:$PATH
NB. travis-cargo
follows semantic versioning rules, so breaking
changes may occur between 0.x
and 0.(x+1)
, and between major
versions. One should use the version-restriction syntax demonstrated
above to protect against this.
Example
A possible .travis.yml
configuration is:
sudo: false
language: rust
# necessary for `travis-cargo coveralls --no-sudo`
addons:
apt:
packages:
- libcurl4-openssl-dev
- libelf-dev
- libdw-dev
- binutils-dev # optional: only required for the --verify flag of coveralls
# run builds for all the trains (and more)
rust:
- nightly
- beta
# check it compiles on the latest stable compiler
- stable
# and the first stable one (this should be bumped as the minimum
# Rust version required changes)
- 1.0.0
# load travis-cargo
before_script:
- |
pip install 'travis-cargo<0.2' --user &&
export PATH=$HOME/.local/bin:$PATH
# the main build
script:
- |
travis-cargo build &&
travis-cargo test &&
travis-cargo bench &&
travis-cargo --only stable doc
after_success:
# upload the documentation from the build with stable (automatically only actually
# runs on the master branch, not individual PRs)
- travis-cargo --only stable doc-upload
# measure code coverage and upload to coveralls.io (the verify
# argument mitigates kcov crashes due to malformed debuginfo, at the
# cost of some speed <https://github.com/huonw/travis-cargo/issues/12>)
- travis-cargo coveralls --no-sudo --verify
env:
global:
# override the default `--features unstable` used for the nightly branch (optional)
- TRAVIS_CARGO_NIGHTLY_FEATURE=nightly
# encrypted github token for doc upload (see `GH_TOKEN` link above)
- secure: "..."
Extra arguments can be passed to cargo
invocations, although
-
-prefixed arguments will need to occur after a --
, e.g. travis-cargo build -- --features something
.
If you do not wish to define an unstable
or similar feature, setting
TRAVIS_CARGO_NIGHTLY_FEATURE=""
should avoid errors caused by undefined
features.
Help
usage: travis-cargo [-h] [-q] [--only VERSION] [--skip VERSION]
{coverage,coveralls,doc-upload,...} ...
Manages interactions between Travis and Cargo and common tooling tasks.
optional arguments:
-h, --help show this help message and exit
-q, --quiet don't pass --verbose to cargo subcommands
--only VERSION only run the given command if the specified version
matches `TRAVIS_RUST_VERSION`
subcommands:
travis-cargo supports all cargo subcommands, and selected others (listed
below). Cargo subcommands have `--verbose` added to their invocation by
default, and, when running with a nightly compiler, `--features unstable`
(or `--features $TRAVIS_CARGO_NIGHTLY_FEATURE` if that environment
variable is defined) if `--features` is a valid argument.
{coverage,coveralls,doc-upload,...}
coverage record code coverage
coveralls record and upload code coverage to coveralls.io
doc-upload upload documentation to Github pages.
coverage
usage: travis-cargo coverage [-h] [-m DIR] [--exclude-pattern PATTERN]
[--kcov-options OPTION] [--no-sudo] [--verify]
[ARGS [ARGS ...]]
Record coverage of `cargo test`, this runs all binaries that `cargo test` runs
but not doc tests. The results of all tests are merged into a single
directory.
positional arguments:
ARGS arguments to pass to `cargo test`
optional arguments:
-h, --help show this help message and exit
-m DIR, --merge-into DIR
the directory to put the final merged kcov result into
(default `target/kcov`)
--exclude-pattern PATTERN
pass additional comma-separated exclusionary patterns
to kcov. See <https://github.com/SimonKagstrom/kcov
#filtering-output> for how patterns work. By default,
the /.cargo pattern is ignored. Example: --exclude-
pattern="test/,bench/"
--kcov-options OPTION
pass additional arguments to kcov, apart from --verify
and --exclude-pattern, when recording coverage.
Specify multiple times for multiple arguments.
Example: --kcov-options="--debug=31"
--no-sudo don't use `sudo` to install kcov's deps. Requires that
libcurl4-openssl-dev, libelf-dev and libdw-dev are
installed (e.g. via `addons: apt: packages:`)
--verify pass `--verify` to kcov, to avoid some crashes. See
<https://github.com/huonw/travis-cargo/issues/12>.
This requires installing the `binutils-dev` package.
coveralls
usage: travis-cargo coveralls [-h] [--exclude-pattern PATTERN]
[--kcov-options OPTION] [--no-sudo] [--verify]
[ARGS [ARGS ...]]
Record coverage of `cargo test` and upload to coveralls.io with kcov, this
runs all binaries that `cargo test` runs but not doc tests. Merged kcov
results can be accessed in `target/kcov`.
positional arguments:
ARGS arguments to pass to `cargo test`
optional arguments:
-h, --help show this help message and exit
--exclude-pattern PATTERN
pass additional comma-separated exclusionary patterns
to kcov. See <https://github.com/SimonKagstrom/kcov
#filtering-output> for how patterns work. By default,
the /.cargo pattern is ignored. Example: --exclude-
pattern="test/,bench/"
--kcov-options OPTION
pass additional arguments to kcov, apart from --verify
and --exclude-pattern, when recording coverage.
Specify multiple times for multiple arguments.
Example: --kcov-options="--debug=31"
--no-sudo don't use `sudo` to install kcov's deps. Requires that
libcurl4-openssl-dev, libelf-dev and libdw-dev are
installed (e.g. via `addons: apt: packages:`)
--verify pass `--verify` to kcov, to avoid some crashes. See
<https://github.com/huonw/travis-cargo/issues/12>.
This requires installing the `binutils-dev` package.
doc-upload
usage: travis_cargo.py doc-upload [-h] [--branch BRANCH]
Use ghp-import to upload cargo-rendered docs to Github Pages, from the master
branch.
optional arguments:
-h, --help show this help message and exit
--branch BRANCH upload docs when on this branch, defaults to master