Travis

构建 R 项目

本指南涵盖的内容 #

本指南涵盖了 R 项目特有的构建环境和配置主题。请务必先阅读我们的 教程 和 构建配置 指南。

社区支持警告 #

Travis CI 对 R 的支持由社区贡献，可能随时被删除或修改。如果您遇到任何问题，请在 我们论坛的 R 部分 中报告，并抄送 @jeroen 和 @jimhester。

基本配置 #

Travis CI 中的 R 支持旨在简化测试 R 包。如果您的 R 包不需要 DESCRIPTION 文件中指定的系统依赖项之外的任何其他系统依赖项，则您的 .travis.yml 可以简单地为

language: r

R 环境预安装了 LaTeX 和 pandoc，这使得使用诸如 RMarkdown 或 knitr 之类的包变得更加容易

配置选项 #

Travis CI 支持许多用于您的 R 包的配置选项。

R 版本 #

Travis CI 支持 Ubuntu Precise、Ubuntu Trusty 和 macOS 上的 R 版本 3.0.3 及更高版本。每个主要版本都存在别名，例如 3.1 指向 3.1.3。此外，名称 oldrel 是对以前主要版本的别名，而 release 是对最新次要版本的别名。 devel 是基于 R SVN 主干的 R git 镜像（每小时更新）构建的。

R 构建支持矩阵构建，但 r 的两个实例都必须为 *小写*。

language: r
r:
  - oldrel
  - release
  - devel

随着新的次要版本发布，别名将浮动并指向最新的次要版本。

您可以使用环境变量 TRAVIS_R_VERSION_STRING 访问上述“通道”*字符串*（即 release），而不是具体的版本号（即 3.2.1）。

构建日志中的“R 会话信息”折叠中包含用于每个构建的确切 R 版本。

依赖项 #

默认情况下，Travis CI 会查找您包的 DESCRIPTION 文件中列出的所有 R 包作为依赖项，并从 CRAN 安装它们。您可以通过将它们列在 DESCRIPTION 中的 Remotes: 字段中，包含对开发中包的依赖项。有关在包中使用开发远程的更多信息，请参见 Remotes Vignette。

在大多数情况下，您不需要在 .travis.yml 中指定任何其他依赖项。

LaTeX/TexLive 包 #

包含的 TexLive 发行版仅包含有限的默认包集。如果您的小插图需要额外的 TexLive 包，您可以使用 tlmgr install 在 before_install 步骤中安装它们。

language: r

before_install:
  - tlmgr install index

找出可能需要哪些包的最佳方法是查看 LaTeX 错误消息中列出的包，并在 CTAN 上搜索它们。包通常有一个 Contained in: 字段，该字段指示您需要安装的包组。

如果您不需要 LaTeX，请告诉 Travis CI 不要安装它，方法是使用 latex: false。

Pandoc #

安装的默认 pandoc 版本为 2.2。可以通过将 pandoc_version 设置为所需版本来安装其他 pandoc 版本。

language: r
pandoc_version: 1.19.2.1

如果您不需要 Pandoc，请告诉 Travis CI 不要安装它，方法是使用 pandoc: false。

APT 包 #

使用 APT 附加组件 安装 APT 包。以下代码片段安装了 R 包 xml2 的先决条件

addons:
  apt:
    packages:
      - libxml2-dev

此选项在非 Linux 构建上被忽略。

另一种方法是使用 apt_packages 键

apt_packages:
  - libxml2-dev

包检查选项 #

您可以使用以下顶级选项来控制在构建和检查包时使用哪些选项

  • warnings_are_errors：此选项强制所有来自 R CMD check 的 WARNINGS 成为构建失败（默认值为 true）。这在准备将包提交到 CRAN 时特别有用，并且建议大多数包使用此选项。如果您不希望 WARNINGS 导致构建失败，请将 warnings_are_errors: false 设置为。

  • r_build_args：要传递给 R CMD build 的额外参数，以单个字符串形式表示。默认为空。

  • r_check_args：要传递给 R CMD check 的额外参数，以单个字符串形式表示。默认为 --as-cran。

Bioconductor #

典型的 Bioconductor 包只需要在他们的 .travis.yml 中指定他们想要测试的 Bioconductor 版本。

language: r
r: bioc-devel

或者如果您想测试发布分支

language: r
r: bioc-release

Travis CI 会使用适合该 Bioconductor 版本的 R 版本，并为安装依赖项适当地配置 Bioconductor。

Packrat #

如果您希望 Travis CI 使用您项目特定的 packrat 包库，而不是默认行为（从 CRAN 下载包依赖项），您可以在 .travis.yml 中添加以下内容

install:
  - R -e "0" --args --bootstrap-packrat
  - R -e "packrat::restore(restart = FALSE)"

您可以通过以下方式缓存 packrat 包来最大限度地减少构建时间

cache:
  directories:
    - $TRAVIS_BUILD_DIR/packrat/src
    - $TRAVIS_BUILD_DIR/packrat/lib
  packages: true

其他 #

  • cran：用于获取包的 CRAN 镜像。默认为 https://cloud.r-project.org。

  • repos：要传递给 options(repos) 的存储库字典。如果字典中没有给出 CRAN，则使用 cran 选项的值。示例

repos:
  CRAN: https://cloud.r-project.org
  ropensci: http://packages.ropensci.org
  • disable_homebrew：如果为 true，这将删除 macOS 上预安装的 homebrew 安装程序。这对测试包是否在 vanilla macOS 机器（例如 CRAN mac 构建器）上构建很有用。

环境变量 #

R-Travis 从 Travis 默认值 设置以下额外的环境变量。

  • TRAVIS_R_VERSION=3.2.4 设置为 r: 选择的版本。
  • R_LIBS_USER=~/R/Library
  • R_LIBS_SITE=/usr/local/lib/R/site-library:/usr/lib/R/site-library
  • _R_CHECK_CRAN_INCOMING_=false
  • NOT_CRAN=true
  • R_PROFILE=~/.Rprofile.site
  • TRAVIS_R_VERSION_STRING 设置为提供给 r: 的 *字符串*，即 release、oldrel 或 devel。   例如，这对于仅从 release 部署很有用，可以通过 on: condition: "$TRAVIS_R_VERSION_STRING = release" 来实现。

其他依赖项字段 #

对于大多数软件包，您不需要在 .travis.yml 中指定任何其他依赖项。但是，在极少数情况下，支持以下字段。

以下每个名称都是一个软件包列表，您可以选择将其指定为 .travis.yml 中的顶级条目；这些列表中的条目将在构建和测试您的软件包之前安装。请注意，这些列表按顺序处理，因此条目可以依赖于之前列表中的依赖项。

  • apt_packages: 见上文

  • brew_packages: 通过 brew 安装的软件包列表。此选项在非 macOS 构建上会被忽略。

  • r_binary_packages: 通过 Michael Rutter 的 cran2deb4ubuntu PPA 在 linux 构建上作为二进制软件包安装的 R 软件包列表。这些安装速度比源代码安装快，但可能不总是最新版本。指定名称的方式与从 CRAN 安装时相同。在 macOS 构建上，这些软件包从源代码安装。

  • r_packages: 通过 install.packages 安装的 R 软件包列表。

  • bioc_packages: 要安装的 Bioconductor 软件包列表。

  • r_github_packages: 使用 devtools 软件包 中的 devtools::install_github 直接从 GitHub 安装的软件包列表。此处的软件包名称应采用 user/repo 的形式。如果软件包安装在子目录中，请使用 user/repo/subdirectory。另一种方法是将 user/repo 或 user/repo/folder 添加到您的软件包的 DESCRIPTION 文件的 Remotes 部分

自定义 Travis 构建步骤 #

对于一些高级用例，覆盖用于构建 R 软件包的默认步骤是有意义的。默认规则大致相当于

install:
- R -e 'remotes::install_deps(dep = T)'

script:
- R CMD build .
- R CMD check *tar.gz --as-cran

如果您想查看完整细节，请参阅 源代码。

构建配置参考 #

您可以在我们的 Travis CI 构建配置参考 中找到有关 R 的构建配置格式的更多信息。

示例 #

子目录中的软件包 #

如果您的软件包位于存储库的子目录中，则需要在运行 install 或 script 步骤之前更改到子目录。

language: r
before_install:
  - cd subdirectory

远程软件包 #

如果您的软件包依赖于另一个存储库，您可以以这种方式使用 r_github_packages

r_github_packages: user/repo

另一种方法是在您的 DESCRIPTION 文件中添加以下行

Imports: pkg-name-of-repo
Remotes: user/repo

请记住，Remotes: 指定开发软件包的 *来源*，因此该软件包仍需要在 Imports:、Suggests: Depends: 或 LinkingTo: 中列出。在 *repo* 和 *package* 名称不同的罕见情况下，Remotes: 期望 *仓库* 名称，而 Imports: 期望 *软件包* 名称（根据该导入软件包的 DESCRIPTION）。

子目录中的远程软件包 #

如果您的软件包依赖于另一个存储库，该存储库将软件包保存在子目录中，您可以以这种方式使用 r_github_packages

r_github_packages: user/repo/folder

另一种方法是在您的 DESCRIPTION 文件中添加以下行

Remotes: user/repo/folder

从 r-travis 转换 #

如果您一直在使用 r-travis 来测试您的 R 软件包，我们鼓励您切换到此处描述的原生支持。我们已经编写了一个 移植指南 来帮助您修改 .travis.yml。

致谢 #

Travis CI 的 R 支持最初基于 r-travis 项目，并感谢所有 贡献者。有关从 r-travis 迁移到原生支持的更多信息，请参阅 移植指南。