<p><div><div><div><div data-width="100" data-show-faces="false" data-send="true" data-layout="button_count" data-height="21" data-href="http://www.r-bloggers.com/a-beginners-guide-to-travis-ci-for-r/"></div></div><div><a data-url="http://www.r-bloggers.com/a-beginners-guide-to-travis-ci-for-r/" data-counturl="http://www.r-bloggers.com/a-beginners-guide-to-travis-ci-for-r/" data-count="horizontal" data-text="A Beginner’s Guide to Travis-CI for R" class="twitter-share-button" data-via="rbloggers" href="https://twitter.com/share"></a></div><div></div></div><div></div></div>
<div>
(This article was first published on <strong><a href="http://juliasilge.com/blog/Beginners-Guide-to-Travis/"> data science ish</a></strong>, and kindly contributed to <a rel="nofollow" href="http://www.r-bloggers.com/">R-bloggers)</a> </div>
<p>Have you seen all those attractive green badges on other people’s R packages and thought, “<em>I</em> want a lovely green badge!”</p>
<blockquote data-lang="en" class="twitter-tweet"><p dir="ltr" lang="en">Always a nice feeling when Travis manages to actually build. <a target="_blank" href="https://twitter.com/hashtag/runconf16?src=hash">#runconf16</a> <a target="_blank" href="https://t.co/7qZfH2OEij">pic.twitter.com/7qZfH2OEij</a></p>
<p>— Julia Silge (@juliasilge) <a target="_blank" href="https://twitter.com/juliasilge/status/716034756509507584">April 1, 2016</a></p></blockquote>
<p></p>
<p>OF COURSE YOU DO. Well, let’s give it a shot, because today I am going to attempt a beginner’s guide to using Travis-CI for continuous integration for R packages. It is going to be a <em>beginner’s</em> guide because that is all I could possibly write; my knowledge and experience with Travis is limited. Sometimes it can be helpful to have someone walk you through something new that she herself has only recently come to grips with, though, so here we go!</p>
<h2>What Is This? And Why? And Who Is Travis?!</h2>
<p>If you have written an R package, you probably have gotten into the habit of running <code>R CMD check</code> on a (hopefully) regular basis to check for common problems. It automatically detects lots of problems that can arise that you might not otherwise notice. Also you probably have put your package on GitHub, for version control and also to be able to share your code with other people and track issues and whatnot. The idea behind continuous integration is that CI will automatically run <code>R CMD check</code> (along with your tests, etc.) every time you push a commit to GitHub. You don’t have to remember to do this; CI automatically checks the code after every commit. <a target="_blank" href="https://travis-ci.org/">Travis-CI</a> is a continuous integration service that builds and tests projects that are hosted on GitHub; if your R package is open source (i.e., not private), then using Travis-CI is free.</p>
<p>What are some reasons that you would want to do this (if you aren’t already convinced by the very idea of automated checking)? If you plan to submit your package to CRAN, using Travis-CI is a way to check your package on a platform (Ubuntu) that you might not have access to otherwise, much like using <code>build_win()</code>. You can <a target="_blank" href="https://github.com/juliasilge/tidytext/blob/3a679c815210dee26e56d50dbb730e7058ad144d/cran-comments.md">look here</a> to see how I explained the different test environments I checked for the tidytext package. If you <em>don’t</em> plan to submit your package to CRAN, for whatever reason, then having your package passing on Travis signals to possible users that this package is probably not a hot mess and is more likely to be worth investing time in downloading and learning how to use.</p>
<h2>Getting Started with Travis</h2>
<p>To get started with Travis-CI, you mosey on over to <a target="_blank" href="https://travis-ci.org/">their website</a> and make an account that is connected to your GitHub account. After you do that, you will see all your GitHub repositories with switches that you can switch from off to on. Pick a repository (in this case, a repository for an R package) that you want to build on Travis and switch it on.</p>
<p>Now, we need to tell Travis what to do by adding a <code>.travis.yml</code> file to the R package. Many packages need only a minimal <code>.travis.yml</code> that looks like this:</p>
<div>
<pre><code>
 language: R
 cache: packages

</code></pre>
</div>
<p>This isn’t R code or anything; it is telling Travis how to go about building the package. (And FYI, this file needs to be added to <code>.Rbuildignore</code> because it is not part of the R package from the point of view of R.) You can use <code>devtools::use_travis()</code> to automatically add a minimal <code>.travis.yml</code> to your package, add <code>.travis.yml</code> to <code>.Rbuildignore</code>, and add the code for the badge to your README. This kind of simple <code>.travis.yml</code> is what I have for my <a target="_blank" href="https://github.com/juliasilge/janeaustenr/blob/2008066a02558ec36bddd9f3deb7d81469684a48/.travis.yml">janeaustenr package</a>. Once you have made this file and then push it to GitHub, the push triggers Travis to build and check the package. Every commit you push to GitHub after this will trigger a new build on Travis that will go through all the automated checking and testing.</p>
<p>If you are lucky, your package will build on Travis successfully and you can add your beautiful green badge to your README on GitHub, if you haven’t already added it via <code>devtools::use_travis()</code> or copy/pasting from elsewhere. If you are less than lucky, well…</p>
<blockquote data-lang="en" class="twitter-tweet"><p dir="ltr" lang="en">Things are going great; why do you ask?! <a target="_blank" href="https://twitter.com/hashtag/rstats?src=hash">#rstats</a> <a target="_blank" href="https://t.co/x3jJQZkuGs">pic.twitter.com/x3jJQZkuGs</a></p>
<p>— Julia Silge (@juliasilge) <a target="_blank" href="https://twitter.com/juliasilge/status/722514130968535042">April 19, 2016</a></p></blockquote>
<p></p>
<p>If a build on Travis is erroring or failing (which are different), I tend to think of the problems being of two possible types:</p>
<ul>
<li>either the code/package itself has a problem(s) or</li>
<li>I have not told Travis how to build the package correctly.</li>
</ul>
<p>One example might be that your package depends on a package from GitHub that is not on CRAN. Travis knows to look in your <code>DESCRIPTION</code> file and will install all your package’s dependencies from CRAN to build your package. What if one of your package’s dependencies is not on CRAN? Then you need to list them as <code>Remotes:</code> in your <code>DESCRIPTION</code> file. You can check out the <a target="_blank" href="https://cran.r-project.org/web/packages/devtools/vignettes/dependencies.html"><code>Remotes:</code> vignette from devtools</a> to see more details on this, and here are <a target="_blank" href="https://github.com/ropenscilabs/geojsonlint/blob/7f8c02925c7bca1fb0d5aa7ea750db1b5dd01fc8/DESCRIPTION">two example</a> <a target="_blank" href="https://github.com/jennybc/googlesheets/blob/df2fc3c227848878627bb44477162b2337b9ba71/DESCRIPTION"><code>DESCRIPTION</code> files</a> that use <code>Remotes:</code>. Both of those packages have <code>.travis.yml</code> files that are more complicated than the simplest version, but that is not because of a GitHub package dependency.</p>
<p>Speaking of which, another possibility is that you will need to tell Travis about some system requirements to get your package to build. For the tidytext package, we have some dependencies on packages that have system requirements. For one, we have a dependency on <a target="_blank" href="https://cran.r-project.org/web/packages/quanteda/index.html">quanteda</a>, which has a dependency on the <a target="_blank" href="https://cran.r-project.org/web/packages/XML/index.html">XML package</a>. If you check out that <a target="_blank" href="https://cran.r-project.org/web/packages/XML/index.html">link for the XML package on CRAN</a>, you’ll notice that it says:</p>
<div>
<pre><code>
 SystemRequirements: libxml2 (>= 2.6.3)

</code></pre>
</div>
<p>This means that wherever you want to build/use the XML package, you need <code>libxml2</code>. Thus, to build our package tidytext (which depends on quanteda which depends on XML) we need to get this library installed. The <code>.travis.yml</code> for tidytext (which has two such system requirements) looks like this:</p>
<div>
<pre><code>
 language: R
 cache: packages
 sudo: false

 addons:
   apt:
     packages:
       - libgsl0-dev # for topicmodels
       - libxml2-dev # for XML, a dependency of quanteda

</code></pre>
</div>
<h2>Thoughts on Debugging Travis Problems</h2>
<p>You may be thinking at this point, “How did she know to do those things specifically?” and that is an excellent question. If you browse the <a target="_blank" href="https://github.com/juliasilge/tidytext/commits/master/.travis.yml">history</a> of the <code>.travis.yml</code> for tidytext, you can see that things were a MESS for a while.</p>
<p><a target="_blank" href="https://imgflip.com/i/14hqh5"><img title="Build Failing" src="https://i.imgflip.com/14hqh5.jpg"></a></p>
<p>Let me share some of the things that have been helpful for me as I have tried to solve problems with building packages on Travis.</p>
<p>Hadley Wickham’s <em>R Packages</em> book has a <a target="_blank" href="http://r-pkgs.had.co.nz/check.html#travis">section on Travis</a> that is short but helpful; it is within the section on <a target="_blank" href="http://r-pkgs.had.co.nz/check.html">automated checking</a> that also has relevant helpful information. The <a target="_blank" href="https://docs.travis-ci.com/user/languages/r/">R docs at Travis</a> itself are also quite helpful, although when I am having a real headscratcher of a problem I always wish there was more detail.</p>
<p>I tend to end up Googling a lot of things when I am having a problem, looking for packages similar to mine to see how they have solved similar challenges. One thing to be aware of in that situation is that the way Travis has dealt with R projects has changed pretty significantly in the not-so-distant past. If you find an R package that started building on Travis before certain changes took place, their <code>.travis.yml</code> will look VERY different than what you will need to use, given that you are starting a new project today. There were changes with containers, sudo, etc. so a slightly older package will be grandfathered in to an older way of building on Travis than a new project. I ran into this in a pretty significant way when trying to solve the problem with building the XML package. Finding other packages that depended on the XML package <em>did</em> help me eventually fix my problems, but I couldn’t do it in the same way as the older packages.</p>
<h2>Unit Tests</h2>
<p>One other aspect I want to mention specifically is that Travis will also run all the unit tests in your package (such as those you have written using <a target="_blank" href="http://r-pkgs.had.co.nz/tests.html">testthat</a>) and the build will fail if any of your tests fail. I am very new to the worlds of unit testing and code coverage and all of that, but even so, I have seen how valuable it has been to immediately know when a change I have made breaks something in the code somewhere. Formal automated testing plus continuous integration equals less headache.</p>
<h2>The End</h2>
<p>I would like to thank <a target="_blank" href="http://www.jimhester.com/">Jim Hester</a>, who gave me feedback on a draft of this post and also helped me when I was struggling with getting Travis set up on my first R package. I’ll be honest; it was pretty rough and perplexing that first time I tried to set things up. Every time I have used CI since then has gone more smoothly and left me feeling more knowledgeable, though, and I am a believer now in the benefits and importance of this tool. At the same time, I am far from an expert, so feel free to chime in with feedback or thoughts, especially if I have said anything actually wrong about using Travis for continuous integration for R projects (please noooooooooooo…). I have shared pretty much the extent of my knowledge here, but I will attempt to answer questions if anyone has any.</p>
<p><div><div><div><div data-width="55" data-show-faces="false" data-send="true" data-layout="box_count" data-height="62" data-href="http://www.r-bloggers.com/a-beginners-guide-to-travis-ci-for-r/"></div></div><div><a data-url="http://www.r-bloggers.com/a-beginners-guide-to-travis-ci-for-r/" data-counturl="http://www.r-bloggers.com/a-beginners-guide-to-travis-ci-for-r/" data-count="vertical" data-text="A Beginner’s Guide to Travis-CI for R" class="twitter-share-button" data-via="rbloggers" href="https://twitter.com/share"></a></div><div></div></div><div></div></div>
<div>
<div>To <strong>leave a comment</strong> for the author, please follow the link and comment on their blog: <strong><a href="http://juliasilge.com/blog/Beginners-Guide-to-Travis/"> data science ish</a></strong>.</div>
<hr>
<a rel="nofollow" href="http://www.r-bloggers.com/">R-bloggers.com</a> offers <strong><a rel="nofollow" href="http://feedburner.google.com/fb/a/mailverify?uri=RBloggers">daily e-mail updates</a></strong> about <a title="The R Project for Statistical Computing" rel="nofollow" href="http://www.r-project.org/">R</a> news and <a title="R tutorials" rel="nofollow" href="http://www.r-bloggers.com/?s=tutorial">tutorials</a> on topics such as: <a title="Data science" rel="nofollow" href="http://www.r-bloggers.com/?s=data%20science">Data science</a>, <a title="Big Data" rel="nofollow" href="http://www.r-bloggers.com/?s=Big%20Data">Big Data, <a title="R jobs" rel="nofollow" href="http://www.r-users.com/">R jobs</a>, visualization (<a title="ggplot and ggplot2 tutorials" rel="nofollow" href="http://www.r-bloggers.com/?s=ggplot2">ggplot2</a>, <a title="Boxplots using lattice and ggplot2 tutorials" rel="nofollow" href="http://www.r-bloggers.com/?s=boxplot">Boxplots</a>, <a title="Maps and gis" rel="nofollow" href="http://www.r-bloggers.com/?s=map">maps</a>, <a title="Animation in R" rel="nofollow" href="http://www.r-bloggers.com/?s=animation">animation</a>), programming (<a title="RStudio IDE for R" rel="nofollow" href="http://www.r-bloggers.com/?s=RStudio">RStudio</a>, <a title="Sweave and literate programming" rel="nofollow" href="http://www.r-bloggers.com/?s=sweave">Sweave</a>, <a title="LaTeX in R" rel="nofollow" href="http://www.r-bloggers.com/?s=LaTeX">LaTeX</a>, <a title="SQL and databases" rel="nofollow" href="http://www.r-bloggers.com/?s=SQL">SQL</a>, <a title="Eclipse IDE for R" rel="nofollow" href="http://www.r-bloggers.com/?s=eclipse">Eclipse</a>, <a title="git and github, Version Control System" rel="nofollow" href="http://www.r-bloggers.com/?s=git">git</a>, <a title="Large data in R using Hadoop" rel="nofollow" href="http://www.r-bloggers.com/?s=hadoop">hadoop</a>, <a title="Web Scraping of google, facebook, yahoo, twitter and more using R" rel="nofollow" href="http://www.r-bloggers.com/?s=Web+Scraping">Web Scraping</a>) statistics (<a title="Regressions and ANOVA analysis tutorials" rel="nofollow" href="http://www.r-bloggers.com/?s=regression">regression</a>, <a title="principal component analysis tutorial" rel="nofollow" href="http://www.r-bloggers.com/?s=PCA">PCA</a>, <a title="Time series" rel="nofollow" href="http://www.r-bloggers.com/?s=time+series">time series</a>, <a title="finance trading" rel="nofollow" href="http://www.r-bloggers.com/?s=trading">trading</a>) and more...
<img height="1" alt="" width="1" src="http://feeds.feedburner.com/~r/RBloggers/~4/GaraWWC5-t0"></a></div>