Travis CI for R — Advanced guideContinuous integration for building an R project in Travis CI including code coverage, pkgdown documentation, osx and multiple R-VersionsSebastian WolfBlockedUnblockFollowFollowingJan 13Photo by Guilherme Cunha on UnsplashTravis 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 contentsBasics from “Building an R project”Modifying R CMD buildMultiple operating systemsRun scripts with user interfacesCode coverageBuild and deploy a pkgdown page to github pagesImageMagick and Travis CIFurther readingBasics 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 languagelanguage: r#Define multiple R-versions, one from bioconductorr: – oldrel – release – devel – bioc-devel# Set one of you dependencies from githubr_github_packages: r-lib/testthat# Set one of your dependencies from CRANr_packages: RTest# set a Linux system dependencyapt_packages: – libxml2-devThe 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 – testthatIn 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-devYou 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 commandsTo 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-cranInside 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 – ghostscriptMultiple operating systemsTravis 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-cranThe 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 interfacesMy 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 LinuxTo enable user interfaces in Linux install xvfb .
addons: apt: update: true packages: – x11proto-xf86vidmode-dev – xvfb – libxxf86vm-devYou 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-cranUser interfaces for macOSFor 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-tkTo 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 ) & fiYou 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 scriptscript: – R CMD build .
–compact-vignettes=gs+qpdf – R CMD check *tar.
gz –as-cranAddonFor more information on user interfaces you can read these two github issues:RSelenium with travis and shinyRSelenium with sauceCode coverageFor 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/covrSecondly 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.
gzafter_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 pagesBuilding 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.
htmlTo 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/pkgdownYou 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: masterfor more info on deploying pages you can check the Travis CI guide on pages.
ImageMagick and Travis CIInside 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 – cargoThis 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 readingBuilding R projects on Travis CI (Basics)Travis CI community for R (Forum)RTest package .
travis.
yml fileThe RTest package — 99% code coverage with Travis-CI.. More details