Skip to content

Home

Jump to bottom Edit New page
Matt Dowle edited this page Mar 30, 2017 · 43 revisions

Contents

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 hadley/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

Worked examples that higlight features of Travis-CI and r-travis can be found on the Recipes page.

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.

  • I'm seeing an error like Error in username %||% getOption("github.user") %||% stop("Unknown username.") : Unknown username. when using install_github.

    Short answer: switch to using username/reponame instead of just reponame.

    Longer answer: Early versions of devtools would default to looking for repos owned by Hadley, so that install_github('testthat') would end up running install_github('hadley/testthat'). While convenient for many, this led to some confusing issues, and has been removed -- now you either need to specify both, or provide an option for which username to use as the default. In the case of r-travis, just using the full username/reponame syntax is far and away the easiest choice.

  • My build times out.

    This can happen when e.g. the line * checking whether package ‘RFoo’ can be installed ... does not produce any output, yet involves a lot of complex code. Some template-heavy C++ packages have been stopped after ten minutes with the message No output has been received in the last 10 minutes, this potentially indicates a stalled build or something wrong with the build itself..

    One possible solution for this is suggested by the Travis docs and involves prefixing the command with the Travis function travis_wait. The full line in the .travis.yml file then becomes - travis_wait ./travis-tool.sh run_tests (under the script: tag).

    Note that one flip-side of this approach is that R will complain about a new top-level file; this is a side-effect of using travis_wait and local to use at Travis. It can therefore be ignore as far as CRAN is concerned.

  • I have packages listed in Enhances. How can they be installed automatically?

    Simply add the following line to your .travis.yml in the install: section just after - ./travis-tool.sh install_deps:

    - Rscript -e 'library("devtools"); library("methods"); options(repos=c(CRAN="http://cran.rstudio.com")); install_deps(dependencies = "Enhances")'
Add a custom footer
Add a custom sidebar
Clone this wiki locally