Building an R Project
What This Guide Covers #
This guide covers build environment and configuration topics specific to R projects. Please make sure to read our Tutorial and build configuration guides first.
Community-Supported Warning #
Travis CI support for R is contributed by the community and may be removed or altered at any time. If you run into any problems, please report them in the R section of our forums and cc @jeroen and @jimhester.
Basic configuration #
R support in Travis CI is designed to make it easy to test R
packages. If your R package doesn’t need any system dependencies
beyond those specified in your
DESCRIPTION file, your
The R environment comes with LaTeX and pandoc pre-installed, making it easier to use packages like RMarkdown or knitr
Configuration options #
Travis CI supports a number of configuration options for your R package.
R Versions #
Travis CI supports R versions
3.0.3 and above on Ubuntu Precise, Ubuntu Trusty and macOS.
Aliases exist for each major release, e.g
3.1 points to
3.1.3. In addition the
oldrel is aliased to the previous major release and
release is aliased to the
latest minor release.
devel is built off of the R git mirror
of the R SVN trunk (updated hourly).
Matrix builds are supported for R builds, however both instances of
be in lowercase.
language: r r: - oldrel - release - devel
As new minor versions are released, aliases will float and point to the most current minor release.
You can access the above “channel” string (i.e.
release) as opposed to the concrete version number (i.e
3.2.1) with the environmental variable
The exact R version used for each build is included in the ‘R session information’ fold within the build log.
By default, Travis CI will find all R packages listed as dependencies in your
DESCRIPTION file, and install them from CRAN. You can include
dependencies on packages in development by listing them in the
DESCRIPTION. See the Remotes Vignette for more
information on using development remotes in your package.
Most of the time you should not need to specify any additional dependencies in
LaTeX/TexLive Packages #
The included TexLive distribution contains only a limited set of default
packages. If your vignettes require additional TexLive packages you
can install them using
tlmgr install in the
language: r before_install: - tlmgr install index
The best way to figure out what packages you may need is to look at the
packages listed in the LaTeX error message and search for them on CTAN.
Packages often have a
Contained in: field that indicates the package group
you need to install.
If you don’t need LaTeX, tell Travis CI not to install it using
The default pandoc version installed is
2.2. Alternative pandoc
releases can be installed by setting the
pandoc_version to the
language: r pandoc_version: 220.127.116.11
If you don’t need Pandoc, tell Travis CI not to install it using
APT packages #
Use the APT addon to install APT packages.
The snippet below installs a prerequisite for the R package
addons: apt: packages: - libxml2-dev
This option is ignored on non-Linux builds.
An alternative is the
apt_packages: - libxml2-dev
Package check options #
You can use the following top-level options to control what options are used when building and checking your package:
warnings_are_errors: This option forces all
R CMD checkto become build failures (default
true). This is especially helpful when preparing your package for submission to CRAN, and is recommended for most packages. Set
warnings_are_errors: falseif you don’t want
WARNINGSto fail the build.
r_build_args: additional arguments to pass to
R CMD build, as a single string. Defaults to empty.
r_check_args: additional arguments to pass to
R CMD check, as a single string. Defaults to
A typical Bioconductor package should only need to specify the
Bioconductor version they want to test against in their
language: r r: bioc-devel
Or if you want to test against the release branch
language: r r: bioc-release
Travis CI will use the proper R version for that version of Bioconductor and configure Bioconductor appropriately for installing dependencies.
If you want Travis CI to use your project-specific packrat package library,
rather than the default behaviour of downloading your package dependencies from CRAN, you can add this to your
install: - R -e "0" --args --bootstrap-packrat - R -e "packrat::restore(restart = FALSE)"
You can minimise build times by caching your packrat packages with:
cache: directories: - $TRAVIS_BUILD_DIR/packrat/src - $TRAVIS_BUILD_DIR/packrat/lib packages: true
cran: CRAN mirror to use for fetching packages. Defaults to
repos: Dictionary of repositories to pass to
CRANis not given in the dictionary the value of the
cranoption is used. Example:
repos: CRAN: https://cloud.r-project.org ropensci: http://packages.ropensci.org
truethis removes the preinstalled homebrew installation on macOS. Useful to test if the package builds on a vanilla macOS machine, such as the CRAN mac builder.
Environment Variables #
R-Travis sets the following additional environment variables from the Travis defaults.
TRAVIS_R_VERSION=3.2.4Set to version chosen by
TRAVIS_R_VERSION_STRINGset to the string provided to
devel. Useful, for example, to deploy only from
on: condition: "$TRAVIS_R_VERSION_STRING = release".
Additional Dependency Fields #
For most packages you should not need to specify any additional dependencies in
.travis.yml. However for rare cases the following fields
Each of the names below is a list of packages you can optionally specify as a
top-level entry in your
.travis.yml; entries in these lists will be
installed before building and testing your package. Note that these lists are
processed in order, so entries can depend on dependencies in a previous list.
apt_packages: See above
brew_packages: A list of packages to install via
brew. This option is ignored on non-macOS builds.
r_binary_packages: A list of R packages to install as binary packages on linux builds, via Michael Rutter’s cran2deb4ubuntu PPA. These installs will be faster than source installs, but may not always be the most recent version. Specify the name just as you would when installing from CRAN. On macOS builds these packages are installed from source.
r_packages: A list of R packages to install via
bioc_packages: A list of Bioconductor packages to install.
r_github_packages: A list of packages to install directly from GitHub, using
devtools::install_githubfrom the devtools package. The package names here should be of the form
user/repo. If the package is installed in a subdirectory, use
user/repo/subdirectory. An alternative is to add
Remotessection of the
DESCRIPTIONfile of your package
Customizing the Travis build steps #
For some advanced use cases, it makes sense to override the default steps used for building R packages. The default rules roughly amount to:
install: - R -e 'remotes::install_deps(dep = T)' script: - R CMD build . - R CMD check *tar.gz --as-cran
If you’d like to see the full details, see the source code.
Build Config Reference #
You can find more information on the build config format for R in our Travis CI Build Config Reference.
Package in a subdirectory #
If your package is in a subdirectory of the repository you need to
change to the subdirectory prior to running the
language: r before_install: - cd subdirectory
Remote package #
If your package depends on another repository you can use
r_github_packages in this way:
An alternative is to add the following line to your
Imports: pkg-name-of-repo Remotes: user/repo
Remotes: specifies the source of a development package, so the package still needs to be listed in
In the rare case where repo and package name differ,
Remotes: expects the repository name and
Imports: expects the package name (as per the
DESCRIPTION of that imported package).
Remote package in a subdirectory #
If your package depends on another repository which holds the package in a subdirectory, you can use
r_github_packages in this way:
An alternative is to add the following line to your
Converting from r-travis #
If you’ve already been using r-travis to test your R package, you’re
encouraged to switch to using the native support described here. We’ve written
a porting guide to help you modify your
R support for Travis CI was originally based on the r-travis project, and thanks are due to all the contributors. For more information on moving from r-travis to native support, see the porting guide.