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 encypted GH_TOKEN)
record total test coverage across in-crate and external tests, and upload to coveralls.io. NB. this requires sudo on Travis, and the test profile must have debug = 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=$HOME/.local/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

huonw/travis-cargo

huonw

Reviews

Repository Details