Home

Getting started

• Visit https://travis-ci.org/profile and flip the switch for the project you want to test

  • Sign up if necessary

• Two options:

  • Paste the following into a terminal that has the current directory set to the root of the GitHub repository of your R package:

git checkout -b travis &&
wget https://github.com/craigcitro/r-travis/raw/master/sample.travis.yml -O .travis.yml &&
sed -i -e '$a\' .Rbuildignore &&
echo '^\.travis\.yml$' >> .Rbuildignore &&
git add .travis.yml .Rbuildignore &&
git commit -m "enable continuous integration via craigcitro/r-travis" &&
git push origin travis

(This assumes that you have set up and are allowed to push to the remote origin, which is the default setting.)

- TODO: Add instructions for GUI/GitHub users

• Tweak .travis.yml and/or your package until you are satisfied with results and run times of the tests

• Merge the travis branch into your main branch (usually master)

Configuration Options

Installing R packages from github

If you'd like to use the github version of any of your dependencies, one can simply add a line like

- ./travis-tool.sh install_github <package>

to install it, so for example

- ./travis-tool.sh install_github testthat

This uses devtools under the hood. The format for <package> is:

user/repo[/subdir][@rev|#pull]

where subdir is required if the package is not in the root of the repository, and rev and pull can be used to indicate a specific Git revision (branch, tag, SHA1, ...) or a GitHub pull request, respectively. (Currently, the latest devtools from GitHub is required to specify subdir, rev, or pull; use an additional install_github command for this.) See also the docs for more information.

Installing R packages from Bioconductor

If you are developing a package for Bioconductor, you can install packages your work depends on from the Bioconductor repositories.

install:
  # Installs packages GenomicRanges and ggbio.
  - ./travis-tool.sh install_bioc GenomicRanges ggbio
  # Installs all packages in the DESCRIPTION file.
  - ./travis-tool.sh install_bioc_deps

Because of Bioconductor's biannual release cycle, Bioconductor maintains two repositories -- release and devel. Developers are advised to always use the devel repository, and so by default, the above functions will use the devel repository. If for some reason you want to use the release repository, set the environment variable BIOC_USE_DEVEL to "FALSE". Example:

env:
  global:
    - BIOC_USE_DEVEL="FALSE"

install:
  # GenomicRanges and other deps installed from the release repo.
  - ./travis-tool.sh install_bioc GenomicRanges
  - ./travis-tool.sh install_bioc_deps

To run two sets of tests, one with devel and one with release, use

env:
  matrix:
    - BIOC_USE_DEVEL="TRUE"
    - BIOC_USE_DEVEL="FALSE"

install:
  - ./travis-tool.sh install_bioc GenomicRanges
  - ./travis-tool.sh install_bioc_deps

OSX

To build on OSX in addition to Ubuntu, execute scripts/create-osx.sh. The script will create a branch with suffix -osx that has the necessary changes made in .travis.yml to let the tests run on OS X instead of Ubuntu. If such a branch exists, it will be updated. As usual, to trigger the test you must push your changes to GitHub, for a new branch use the --all switch:

git push [--all]

Note that it's not currently possible to have one branch that runs tests on both Linux and OSX.

You can also create a link to this script in your private bin directory:

ln -s /path-to-r-travis/scripts/create-osx.sh ~/bin/

If you want to test exclusively on OS X (not recommended), simply change language to objective-c in your .travis.yml file.

Build and test options

Options used for building or testing your R package can be controlled by uncommenting one or both of the following; the values here are the defaults, which live in travis-tool.sh:

 env:
   global:
     - CRAN: http://cran.rstudio.com
     - R_BUILD_ARGS="--no-build-vignettes --no-manual"
     - R_CHECK_ARGS="--no-build-vignettes --no-manual --as-cran"
     - BOOTSTRAP_LATEX=""

See the travis docs for more information.

Logs

It's easy to dump the complete build logs after R CMD check completes:

after_script:
  - ./travis-tool.sh dump_logs

To only dump logs on failure, use after_failure instead of after_script.

Selective testing of branches

To restrict the branches to test, see the travis docs. For instance, to tests all branches except those with suffix -expt ("experimental"), use

 branches:
   except:
     - /-expt$/

Note that in general it is advisable to test (almost) all branches in order to automatically test pending pull requests.

Install non-R dependencies

Some R packages, such as rgdal, require libraries that are not present on the system by default. These requirements are listed in the SystemRequirements section of the package's DESCRIPTION. To use such packages for Travis, these requirements must be installed in advance.

Ubuntu

In many cases, dependencies are available in the standard Ubuntu package repository and can be installed through ./travis-tool.sh aptget_install. This command internally calls apt-get install. Figuring out the name of the corresponding Ubuntu package from a SystemRequirements entry in DESCRIPTION is mostly manual work. If an Ubuntu installation is available, the tool apt-file helps determining which packages provide a certain file; missing files are reported when an R package fails to install due to a missing dependency.

Similarly, a number of dependencies on other R packages can be satisfied by installing the corresponding binary package r-cran-* from Ubuntu which may be faster than installing directly from CRAN.

In case locally-built package are available over http, the ./travis-tool.sh install_dpkgcurl command can be used as well. And example is provided by the travis script for RQuantLib which install the QuantLib library and headers, as well as Rcpp, from locally-provided backports to the Ubuntu LTS release used by Travis.

OS X

No neat solution available yet. Comment on #61 if your dependencies are packaged as a .pkg file.

Recipes

FAQ

• I'm getting complaints about old versions of R packages being installed.

  This means that some packages were installed before we updated the apt repos to point to something recent; make sure that the call to travis-tool.sh bootstrap comes before you install any apt packages.

• I'm seeing TeX-related failures in files that work perfectly well on my local machine.

  The travis images use an older ubuntu distribution, which has some really old default packages. Try adding

  - sudo add-apt-repository -y ppa:texlive-backports/ppa
  

  before the bootstrap call in your .travis.yml, and see if this fixes the problem. If this is your issue, please comment on #113 -- we may just make this the default going forward.