Confident package releases in R with crant

November 29, 2012
By

(This article was first published on Cartesian Faith » R, and kindly contributed to R-bloggers)

I recently released the new lambda.r package on CRAN for functional programming. This was my first new package in quite some time, and I forgot how onerous package releases to CRAN can be.

What I didn’t realize is that packages are tested against three distinct versions of R:

  • R – The latest official point release (e.g. 2.15)
  • R-patched – The latest patch release (e.g. 2.15.2)
  • R-devel – The latest source in the development branch

It just so happened that a dependency of lambda.r failed in the R-devel branch. The update then broke my package but only for one of the builds.

Most of the time worrying about these slightly different versions isn’t a big deal, but the more low-level a package is the more you have to worry about it. Lambda.R is one such package, and I was stuck in a curious situation where the CRAN maintainers were telling me the package was inconsistently failing. Joyriding aside, I’m not one for driving blind. Instead I created some tools to provide the coverage I needed, so I can release packages with confidence and not waste anybody’s time. The collection of these tools is called crant.

Features

Crant does just three things. Starting from scratch you can:

  • Create the three standalone R builds mentioned above. Each version is downloaded from source and can be updated at any time
  • Install 3rd party libraries for each build (e.g. RUnit, testthat). Basically any package that is “Suggested” but not “Required” will need to be installed prior to building your own package
  • Build and install your package. The rant script will also set the package version and perform the CRAN checks as necessary.

The key to crant is a consistent build chain for any version of R. This flexibility means that you can test your package against any set of R sources (not just the three tags above), depending on how much backwards compatibility you require.

Usage

Here is a quick guide to crant. More documentation is available on the source page.

Building the Environment

The buildenv.sh script can setup a clean OS with all the tools, such as make, gcc, gfortran, java, etc, necessary to build R from source. Note that only debian-flavored OSes are compatible. Include the -d option to install these dependencies (only do this once).

export PATH=$PATH:path/to/crant
buildenv.sh -u # Add -d if you have a clean OS

The -u option tells the script to get the R source and update it to the latest version. It will also build the R source and set up the package directory to something portable and safe from the other builds.

The end result is that you will have 3 installations of R built from source that correspond to the latest minor release (e.g. 2.15), the latest patch release (e.g. 2.15.2), and the current development source (R-devel).

Install Package Dependencies

Now armed with three R builds, you can install packages into each one. For fine-grained control, you need to do this with each version of R. I may wrap this up into a single command if there is interest.

setuplib.sh -R ~/devel/bin/R RUnit testthat
setuplib.sh -R ~/patch/bin/R RUnit testthat
setuplib.sh -R ~/release/bin/R RUnit testthat

Note that you only need to install packages that are Suggested. Required dependencies should be installed automatically during the package build process.

Build Your Package

At this point your environment is fully configured. You can now test your package against these R builds. The rant script will build, run tests, and check for CRAN compatibility. It will also optionally install the package to the R build running.

rant -v 1.0.0 -R path/to/R your.package

Note that rant will automatically set the version and date in the DESCRIPTION and package.Rd files for you. This works if you use the placeholders ‘{version}’ and ‘{date}’, respectively, in these files.

During package development, you can run the rant script whenever you want to test the integrity of the package. You will find the source packages in a directory called ‘export’. These can be uploaded to CRAN.

To summarize, anyone writing packages should take a look at crant. Having a consistent and easily reproducible build chain can greatly improve the success ratio of a CRAN upload in addition to making the process more efficient.


To leave a comment for the author, please follow the link and comment on his blog: Cartesian Faith » R.

R-bloggers.com offers daily e-mail updates about R news and tutorials on topics such as: visualization (ggplot2, Boxplots, maps, animation), programming (RStudio, Sweave, LaTeX, SQL, Eclipse, git, hadoop, Web Scraping) statistics (regression, PCA, time series, trading) and more...



If you got this far, why not subscribe for updates from the site? Choose your flavor: e-mail, twitter, RSS, or facebook...

Comments are closed.