Cargo Travis

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

目标是最终与已假定失效的travis-cargo具有相同的功能

为了避免像这个问题一样的问题，我们直接链接到 cargo crate 并使用其低级操作。这应该比 stdout 捕获方法更可靠。另一方面，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 之前运行 cargo doc-upload，如果你想要使用不同的配置来编写文档，你可以在其中建立任何你想要的目录结构。如果你需要从非默认目标获取文档，你可以传递目标三元组到 --target，然后它会从 target/TRIPLE/doc 获取。

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

<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 加上一个脚本将私钥移动到正确的位置。