Travis CI for R — Advanced guide

Travis CI for R — Advanced guide

Continuous integration for building an R project in Travis CI including code coverage, pkgdown documentation, osx and multiple R-Versions

Travis CI is a common tool to build R packages. It is in my opinion the best platform to use R in continuous integration. Some of the most downloaded R packages built at this platform. These are for example testthat, magick or covr. I also built my package RTest at this platform. During the setup I ran into some trouble. The knowledge I gained I’m sharing with you in this guide.

Table of contents

• Basics from “Building an R project”
• Modifying R CMD build
• Multiple operating systems
• Run scripts with user interfaces
• Code coverage
• Build and deploy a pkgdown page to github pages
• ImageMagick and Travis CI
• Further reading

Basics from “Building an R project”

The article “Building an R Project” from Travis CI tells you about the basics. It allows setting up a build for an R-package or R project. The main take away comes with this .travis.yml file.

# Use R language
language: r
#Define multiple R-versions, one from bioconductor
r:
  - oldrel
  - release
  - devel
  - bioc-devel
# Set one of you dependencies from github
r_github_packages: r-lib/testthat
# Set one of your dependencies from CRAN
r_packages: RTest
# set a Linux system dependency
apt_packages:
  - libxml2-dev

The tutorial explains to you that you should setup your type language as R. You can use different R-versions. Those R-Versions are:

[oldrel, release, devel, bioc-devel, bioc-release]

Additionally you can load any package from github by r_github_packages . Or you can get any package from CRAN by r_packages . A list of multiple packages can be created using the standard yml format:

r_packages:
  - RTest
  - testthat

In case you have a Linux dependency, it needs to be mentioned. The RTest package uses XML test cases. The XML Linux library needed is libxml2 . It can be added by:

apt_packages:
  - libxml2-dev

You are done with the basics. In case you have this .travis.yml file inside your repository, it will use R CMD build and R CMD check to check your project.

Modifying R CMD commands

To build my project I wanted to build it like on CRAN. Therefore I needed to change the script of the package check. Therefore I added:

script:
  - R CMD build . --compact-vignettes=gs+qpdf
  - R CMD check *tar.gz --as-cran

Inside this script you can changeR CMD build orR CMD check arguments. For a list of arguments to R CMD see this tutorial from RStudio.

To run vignette compression get gs+qpdf by:

addons:
  apt:
    update: true
    packages:
      - libgs-dev
      - qpdf
      - ghostscript

Multiple operating systems

Travis CI offers two different operating systems right now (Jan 2019). Those are macOS and Linux. The standard way of testing is Linux. For my project RTest I needed to test in macOS, too. To test in two operating systems use the matrix parameter of Travis CI.

The matrix parameter allows adjusting certain parameters for certain builds. To have the exact same build in Linux and macOS I used the following structure:

matrix:
  include:
  - r: release
    script:
      - R CMD build . --compact-vignettes=gs+qpdf
      - R CMD check *tar.gz --as-cran 
  - r: release
    os: osx
    osx_image: xcode7.3
    before_install:
      - sudo tlmgr install framed titling
    script:
      - R CMD build . --compact-vignettes=gs+qpdf
      - R CMD check *tar.gz --as-cran

The matrix function splits the build into different operating systems. For macOS I used the image xcode7.3 as it is proposed by rOpenSCI. An extra point for this version is that it is close to the current CRAN macOS version. As you can see you should install the Latex packages framed and titling to create vignettes.

Run scripts with User interfaces

My package RTest uses Tcl/Tk user interfaces. To test such user interfaces you need enable user interfaces in Linux and macOS separately. Travis CI provides the xvfb package for Linux. For macOS you need to reinstall xquartz and tcl-tk with homebrew .

User interfaces for Linux

To enable user interfaces in Linux install xvfb .

addons:
  apt:
    update: true
    packages:
       -   x11proto-xf86vidmode-dev
       -   xvfb
       -   libxxf86vm-dev

You can run all R scripts with a user interface using the xvfb-run command in front of the R command.

script:
      - R CMD build . --compact-vignettes=gs+qpdf
      - xvfb-run R CMD check *tar.gz --as-cran

User interfaces for macOS

For macOS the installation of a user interface is more difficult. You need to add xquart and tcl-tk to the image provided in xcode7.3 .

before_install:
      - brew update
      - brew cask reinstall xquartz
      - brew install tcl-tk --with-tk
      - brew link --overwrite --force tcl-tk; brew unlink tcl-tk

To use xquartz there is no xvfb-run command under macOS. In a github issue I found a solution that still makes user interfaces work with xquartz .

before_script:
      - "export DISPLAY=:99.0"
      - if [ "${TRAVIS_OS_NAME}" = "osx" ]; then ( sudo Xvfb :99 -ac -screen 0 1024x768x8; echo ok ) & fi

You create a display before running any R script that can be used by the R session. It is important to export the DISPLAY variable. This variable is read by the tcktk R package.

In macOS you do not need to change the script

script:
      - R CMD build . --compact-vignettes=gs+qpdf
      - R CMD check *tar.gz --as-cran

Addon

For more information on user interfaces you can read these two github issues:

• RSelenium with travis and shiny
• RSelenium with sauce

Code coverage

For code coverage I would suggest to use one specific version of your builds. I decided for Linux + r-release to test the code coverage. First of all I added the covr package to my build script:

r_github_packages:
  - r-lib/covr

Secondly I wanted to test my package using covr. This can be done in Travis using the after_success step. To use covr inside this step you need to define how your package tarball will be named. You can write this directly into your script. A better way to do it is to write it into the env part of you .travis.yml file. The name of your tarball will always be PackageName + “_” + PackageVersion + “.tar.gz”. Inside your DESCRIPTION file you defined PackageName and PackageVersion. I used CODECOV to store the results of my coverage tests.

env:
    - PKG_TARBALL=RTest_1.2.3.1000.tar.gz
after_success:
      - tar -C .. -xf $PKG_TARBALL
      - xvfb-run Rscript -e 'covr::codecov(type=c("tests", "vignettes", "examples"))'

The setup I’m using for my package includes code coverage for all my examples, vignettes and tests. To deploy the results of the code coverage you must define the global variable CODECOV_TOKEN . The token can be found under https://codecov.io/gh/<owner>/<repo>/settings . You can insert it secretly into your Travis CI build. Add tokens inside https://travis-ci.org/<owner>/<repo>/settings . The section environment variables stores variables secretly for you.

To use COVERALLS instead of CODECOV use the covr::coveralls function and define a COVERALLS_TOKEN inside your environment.

Build and deploy a pkgdown page to github pages

Building a pkgdown page can be really useful to document your code. On my github repository I also host the pkgdown page of my package RTest. You can find the page here: https://zappingseb.github.io/RTest/index.html

To allow deployment to github pages I activated this feature at: https://github.com/<owner>/<repo>/settings. You have to use the gh-pages branch. If you do not have such a branch you need to create it.

Inside the .travis.yml you start by installing pkgdown.

r_github_packages:
  - r-lib/pkgdown

You will have to build the page from your package tarball. The name of the package tarball has to be defined. Please see the section code coverage for how this is done. After unpacking the tarball you should delete any leftovers from checking the package by rm -rf <PackageName>.Rcheck .

after_success:
      - tar -C .. -xf $PKG_TARBALL
      - rm -rf RTest.Rcheck
      - Rscript -e 'pkgdown::build_site()'

The Rscript will produce the website inside adocs folder. This folder must be deployed on github pages.

First go to to https://github.com/settings/tokens when you’re logged into github. There you have to create a token with public_repo or repo scope. Now store this token inside your Travis CI build. Therefore go to https://travis-ci.org/<owner>/<repo>/settings and store it as a global variable named GITHUB_TOKEN . The website will now be deployed on every successful build using this script:

deploy:
  - provider: pages
        skip-cleanup: true
        github-token: $GITHUB_TOKEN
        keep-history: false
        local-dir: docs
        on:
          branch: master

for more info on deploying pages you can check the Travis CI guide on pages.

ImageMagick and Travis CI

Inside the travis-ci-community there was a question on how to install the magick package on Travis-CI. The answer is simple. You need to have all system dependencies of ImageMagick. Install these for Linux by:

addons:
   apt:
     update: true
     sources:
       - sourceline: 'ppa:opencpu/imagemagick'
       - sourceline: 'ppa:ubuntugis/ppa'
     packages:
       - libmagick++-dev
       - librsvg2-dev
       - libwebp-dev
       - libpoppler-cpp-dev
       - libtesseract-dev
       - libleptonica-dev
       - tesseract-ocr-eng
       - r-cran-rgdal
       - libfftw3-dev
       - cargo

This also worked for macOS for me.

Dear Reader: It’s always a pleasure to write about my work on continuous integrations. I thank you for reading until the end of this article. If you liked the article, you can clap for it on Medium or star the repository on github. In case of any comment, leave it here or on my LinkedIn profile http://linkedin.com/in/zappingseb.

Further reading

• Building R projects on Travis CI (Basics)
• Travis CI community for R (Forum)
• RTest package .travis.yml file
• The RTest package — 99% code coverage with Travis-CI

Travis CI for R — Advanced guide was originally published in Towards Data Science on Medium, where people are continuing the conversation by highlighting and responding to this story.