Cargo Travis

记录crate内和外部测试的总覆盖率，并上传到 coveralls.io。

目标是最终与假设已死的 travis-cargo 具有相同的功能

为了避免像 这个问题 这样的问题，我们直接链接到 cargo crate 并使用其底层操作。这应该比标准输出捕获方法更可靠。另一方面，cargo crate 并不稳定，导致像 这个问题。

安装

cargo install cargo-travis
export PATH=$HOME/.cargo/bin:$PATH

示例

一个可能的 travis.yml 配置如下

sudo: required
language: rust

# Cache cargo symbols for faster build
cache: cargo

# Dependencies of kcov, used by coverage
addons:
  apt:
    packages:
      - libcurl4-openssl-dev
      - libelf-dev
      - libdw-dev
      - binutils-dev
      - cmake # also required for cargo-update
    sources:
      - kalakris-cmake

# 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

before_script:
  - export PATH=$HOME/.cargo/bin:$PATH
  - cargo install cargo-update || echo "cargo-update already installed"
  - cargo install cargo-travis || echo "cargo-travis already installed"
  - cargo install-update -a # update outdated cached binaries

# the main build
script:
  - |
      cargo build &&
      cargo test &&
      cargo bench &&
      cargo doc

after_success:
# measure code coverage and upload to coveralls.io
  - cargo coveralls
# upload documentation to github.io (gh-pages branch)
  - cargo doc-upload

有关 cargo-update 的详细信息，请参阅 cargo-update 仓库。

请注意，使用 kcov 需要 sudo: required。有关更多信息，请参阅 这个问题。

帮助

覆盖率

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

Usage:
    cargo coverage [options] [--] [<args>...]

Coverage Options:
    -V, --version                Print version info and exit
    -m PATH, --merge-into PATH   Path to the directory to put the final merged
                                 kcov result into [default: target/kcov]
    --exclude-pattern PATTERN    Comma-separated path patterns to exclude from the report
    --kcov-build-location PATH   Path to the directory in which to build kcov (into a new folder)
                                 [default: target] -- kcov ends up in target/kcov-master

Test Options:
    -h, --help                   Print this message
    --lib                        Test only this package's library
    --bin NAME                   Test only the specified binary
    --bins                       Test all binaries
    --test NAME                  Test only the specified integration test target
    --tests                      Test all tests
    --bench NAME ...             Test only the specified bench target
    --benches                    Test all benches
    --all-targets                Test all targets (default)
    -p SPEC, --package SPEC ...  Package to run tests for
    --all                        Test all packages in the workspace
    --exclude SPEC ...           Exclude packages from the test
    -j N, --jobs N               Number of parallel jobs, defaults to # of CPUs
    --release                    Build artifacts in release mode, with optimizations
    --features FEATURES          Space-separated list of features to also build
    --all-features               Build all available features
    --no-default-features        Do not build the `default` feature
    --target TRIPLE              Build for the target triple
    --manifest-path PATH         Path to the manifest to build tests for
    -v, --verbose ...            Use verbose output
    -q, --quiet                  No output printed to stdout
    --color WHEN                 Coloring: auto, always, never
    --no-fail-fast               Run all tests regardless of failure
    --frozen                     Require Cargo.lock and cache are up to date
    --locked                     Require Cargo.lock is up to date
    -Z FLAG ...                  Unstable (nightly-only) flags to Cargo

coveralls

Record coverage of `cargo test`, this runs all binaries that `cargo test` runs
but not doc tests. The results of all tests are sent to coveralls.io

Usage:
    cargo coveralls [options] [--] [<args>...]

Coveralls Options:
    -V, --version                Print version info and exit
    --exclude-pattern PATTERN    Comma-separated  path patterns to exclude from the report
    --kcov-build-location PATH   Path to the directory in which to build kcov (into a new folder)
                                 [default: target] -- kcov ends up in target/kcov-master

Test Options:
    -h, --help                   Print this message
    --lib                        Test only this package's library
    --bin NAME                   Test only the specified binary
    --bins                       Test all binaries
    --test NAME                  Test only the specified integration test target
    --tests                      Test all tests
    --bench NAME ...             Test only the specified bench target
    --benches                    Test all benches
    --all-targets                Test all targets (default)
    -p SPEC, --package SPEC ...  Package to run tests for
    --all                        Test all packages in the workspace
    --exclude SPEC ...           Exclude packages from the test
    -j N, --jobs N               Number of parallel jobs, defaults to # of CPUs
    --release                    Build artifacts in release mode, with optimizations
    --features FEATURES          Space-separated list of features to also build
    --all-features               Build all available features
    --no-default-features        Do not build the `default` feature
    --target TRIPLE              Build for the target triple
    --manifest-path PATH         Path to the manifest to build tests for
    -v, --verbose ...            Use verbose output
    -q, --quiet                  No output printed to stdout
    --color WHEN                 Coloring: auto, always, never
    --no-fail-fast               Run all tests regardless of failure
    --frozen                     Require Cargo.lock and cache are up to date
    --locked                     Require Cargo.lock is up to date
    -Z FLAG ...                  Unstable (nightly-only) flags to Cargo

文档上传

Upload built rustdoc documentation to GitHub pages.

Usage:
    cargo doc-upload [options] [--] [<args>...]

Options:
    -V, --version                Print version info and exit
    --branch NAME ...            Only publish documentation for these branches
                                 Defaults to only the `master` branch
    --token TOKEN                Use the specified GitHub token to publish documentation
                                 If unspecified, checks $GH_TOKEN then attempts to use SSH endpoint
    --message MESSAGE            The message to include in the commit
    --deploy BRANCH              Deploy to the given branch [default: gh-pages]
    --path PATH                  Upload the documentation to the specified remote path [default: /$TRAVIS_BRANCH/]
    --clobber-index              Delete `index.html` from repo
    --target TRIPLE              Fetch the documentation for the target triple

用于文档推送的分支可能受到保护，因为不使用强制推送。文档按分支在子目录中维护，所以 user.github.io/repo/PATH 是主分支文档所在的位置。 PATH 默认为分支名称，你可以通过将自定义路径传递给 --path 来覆盖此行为。还会生成一个徽章，类似于 docs.rs，位于 user.github.io/repo/master/badge.svg。此外，还会生成一个 badge.json 文件，对应于 shields.io的端点。默认情况下，只有主分支会构建文档，但你可以通过传递任意数量的 --branch NAME 参数来构建其他分支的文档（存在这些参数将禁用默认的主分支构建）。文档从 target/doc 部署，这是 rustdoc 的默认目标，所以请确保在 cargo doc-upload 之前运行 cargo doc，如果你想要使用不同的配置进行文档记录，你可以在其中构建你想要的任何目录结构。如果你需要从非默认目标获取文档，你可以将目标三元组传递给 --target，然后它会从 target/TRIPLE/doc 获取它。

我们建议在文档根目录设置一个 index.html，以便重定向到实际内容。为此，我们不修改 gh-pages 分支的根目录（除了创建分支文件夹）并且故意忽略分支文件夹中的 index.html。你可以通过传递 --clobber-index 来选择退出此行为。你可以使用 cargo rustdoc -- -Z unstable-options --enable-index-page（仅在 rust nightly 中有效）来创建一个 index.html 文件（或看起来像这样）

<meta http-equiv="refresh" content="0; url=my_crate/index.html">
<a href="my_crate/index.html">Redirect</a>

这需要Travis具有对您的仓库的写入权限。实现这一点的最简单（并且相对安全）的方式是创建一个具有 public_repo 范围的 个人API访问令牌。然后在Travis上，定义安全环境变量 GH_TOKEN，其值为新令牌。

这使任何在Travis上运行的脚本都具有读取/写入您可以使用的公共仓库的权限（仅在非PR构建中，但请注意，bors staging/trying 不是一个PR构建），所以请留意这一点。这也适用于组织仓库，只要用户的令牌有权写入它。

如果您想要更高的安全性，可以使用一个 部署密钥 来进行特定于仓库的访问。如果您不提供令牌，脚本将使用SSH从/写入仓库。 Travis Pro 自动处理部署密钥，而普通用户可以使用 Travis encrypt-file 加上一个脚本将私有密钥移动到正确的位置。