In this article you’ll learn how to use rhub to connect to the R-hub builder API to start new checks and get the results and artifacts of recent checks.

library(rhub)

Validate your email address

To build and check packages, first you need to validate your email address with validate_email().

The package tries to detect your email address using whoami (note that whoami does so using your global git config) and the maintainer email listed in DESCRIPTION; and if it fails to do this correctly, you’ll need to specify it. This means that if running validate_email() gives an error, you should either run validate_email("youremail@example.com") ( quickest fix), or edit your global git config (less quick, but useful for package development in general; to set it up smoothly refer to this usethis helper).

rhub stores the token permanently on the machine, so you do not need to validate your email again. You can also copy your token to other machines: run list_validated_emails() to get the token, and use the validate_email() function on the new machine, using both the email and token arguments.

Currently you cannot use the token obtained via this function in the Web UI of the R-hub builder.

Run a package check

check() runs an R CMD check on the package in the specified directory, or specified source R package tarball created by R CMD build or devtools::build(). It defaults to the working directory.

If the platform argument is NULL, and the R session is interactive, then a menu is shown. If it is NULL, and the session is not interactive, then the default R-hub platform platforms()$name[1], i.e. debian-clang-devel, is used.

In interactive R sessions, the output of the check is printed to the screen unless you set the show_status argument to FALSE. Therefore, by default, your R session is busy showing the log until the check is finished, so set show_status to FALSE if you want to submit a check and then go on with your work in the same session.

In all cases, you will receive a notification email with results after the check.

recording of a check on a screen

recording of a check on a screen

You can either just run the function, or assign its output to an object, that you can use to print results to the screen, to browse the web page of the check, and to retrieve URLs to the web page of the check but also to its artifacts that are kept a few days.

To retrieve such objects from previous checks, see the corresponding section.

Select a building and checking architecture

You can run checks on any platform. You can use the platform ids (e.g. "debian-gcc-devel" or c("debian-gcc-devel", "debian-gcc-patched")) to select between platforms. You should not run checks on all platforms at once. E.g. if preparing for a CRAN submission, use the shortcut function check_for_cran() that will submit your package to a few recommended platforms. The following subsections give more info on how to select platforms.

Listing R-hub platforms

If looking for a platform with particular characteristics, in particular to reproduce a result from CRAN’s own platform, have a look at the R-hub platform characteristics.

knitr::kable(platforms(), row.names = FALSE)
name description cran-name rversion os-type cpu-type os-info compilers docker-image sysreqs-platform categories node-labels queue output-parser macos-version
debian-clang-devel Debian Linux, R-devel, clang, ISO-8859-15 locale r-devel-linux-x86_64-debian-clang r-devel Linux x86_64 Debian GNU/Linux testing clang version 7.0.1-8 (tags/RELEASE_701/final) debian-clang-devel linux-x86_64-debian-clang Linux linux linux NA NA
debian-gcc-devel Debian Linux, R-devel, GCC r-devel-linux-x86_64-debian-gcc r-devel Linux x86_64 Debian GNU/Linux testing gcc version 8.3.0 (Debian 8.3.0-5) debian-gcc-devel linux-x86_64-debian-gcc Linux linux linux NA NA
debian-gcc-devel-nold Debian Linux, R-devel, GCC, no long double NA r-devel Linux x86_64 Debian GNU/Linux testing gcc version 8.3.0 (Debian 8.3.0-5) debian-gcc-devel-nold linux-x86_64-debian-gcc Linux linux linux NA NA
debian-gcc-patched Debian Linux, R-patched, GCC r-patched-linux-x86_64 r-patched Linux x86_64 Debian GNU/Linux testing gcc version 8.3.0 (Debian 8.3.0-5) debian-gcc-patched linux-x86_64-debian-gcc Linux linux linux NA NA
debian-gcc-release Debian Linux, R-release, GCC r-release-linux-x86_64 r-release Linux x86_64 Debian GNU/Linux testing gcc version 8.3.0 (Debian 8.3.0-5) debian-gcc-release linux-x86_64-debian-gcc Linux linux linux NA NA
fedora-clang-devel Fedora Linux, R-devel, clang, gfortran r-devel-linux-x86_64-fedora-clang r-devel Linux x86_64 Fedora 24 clang version 3.8.0; GNU Fortran 6.1.1 fedora-clang-devel linux-x86_64-fedora-clang Linux linux linux NA NA
fedora-gcc-devel Fedora Linux, R-devel, GCC r-devel-linux-x86_64-fedora-gcc r-devel Linux x86_64 Fedora 24 GCC 6.1.1 fedora-gcc-devel linux-x86_64-fedora-gcc Linux linux linux NA NA
linux-x86_64-centos6-epel CentOS 6, stock R from EPEL NA r-release Linux x86_64 CentOS 6 GCC 4.4.x centos6-epel linux-x86_64-centos6-epel Linux linux linux NA NA
linux-x86_64-centos6-epel-rdt CentOS 6 with Redhat Developer Toolset, R from EPEL NA r-release Linux x86_64 CentOS 6 GCC 5.2.1 centos6-epel-rdt linux-x86_64-centos6-epel Linux linux linux NA NA
linux-x86_64-rocker-gcc-san Debian Linux, R-devel, GCC ASAN/UBSAN NA r-devel Linux x86_64 Debian GNU/Linux testing GCC 5.4.0 (Debian 5.4.0-4) rocker-gcc-san linux-x86_64-debian-gcc Checks for compiled code linux linux sanitizers NA
macos-elcapitan-release macOS 10.11 El Capitan, R-release (experimental) r-release-osx-x86_64 r-release macOS x86_64 Mac OS X 10.11.6 15G1217 Apple LLVM version 8.0 (clang-800.0.42.1); GNU Fortran 4.2.3 NA osx-x86_64-clang macOS c(“macos”, “elcapitan”, “r-release”) elcapitan NA elcapitan
solaris-x86-patched Oracle Solaris 10, x86, 32 bit, R-patched (experimental) r-patched-solaris-x86 r-patched Solaris x86_64 SunOS 5.10 Generic_147148-26 i86pc i386 i86pc GCC 5.2.0 NA solaris-10 Solaris solaris solaris NA NA
ubuntu-gcc-devel Ubuntu Linux 16.04 LTS, R-devel, GCC NA r-devel Linux x86_64 Ubuntu 16.04 LTS GCC 5.3.1 ubuntu-gcc-devel linux-x86_64-ubuntu-gcc Linux linux linux NA NA
ubuntu-gcc-release Ubuntu Linux 16.04 LTS, R-release, GCC NA r-release Linux x86_64 Ubuntu 16.04 LTS GCC 5.3.1 ubuntu-gcc-release linux-x86_64-ubuntu-gcc Linux linux linux NA NA
ubuntu-rchk Ubuntu Linux 16.04 LTS, R-devel with rchk NA r-devel Linux x86_64 Ubuntu 16.04 LTS clang 3.8.0-2ubuntu4 ubuntu-rchk linux-x86_64-ubuntu-gcc Checks for compiled code linux linux rchk NA
windows-x86_64-devel Windows Server 2008 R2 SP1, R-devel, 32/64 bit r-devel-windows-ix86+x86_64 r-devel Windows x86_64 Windows Server 2008 R2 SP1 GCC 4.9.3, Rtools 3.4 NA windows-2008 Windows c(“windows”, “rtools3”) rtools3 NA NA
windows-x86_64-devel-rtools4 Windows Server 2012, R-devel, Rtools4.0, 32/64 bit (experimental) NA r-testing Windows x86_64 Windows Server 2012 Rtools 4.0 NA windows-2012 Windows c(“windows”, “rtools4.0”) rtools4.0 NA NA
windows-x86_64-oldrel Windows Server 2008 R2 SP1, R-oldrel, 32/64 bit r-oldrel-windows-ix86+x86_64 r-oldrel Windows x86_64 Windows Server 2008 R2 SP1 GCC 4.6.3, Rtools 3.3 NA windows-2008 Windows c(“windows”, “rtools3”) rtools3 NA NA
windows-x86_64-patched Windows Server 2008 R2 SP1, R-patched, 32/64 bit NA r-patched Windows x86_64 Windows Server 2008 R2 SP1 GCC 4.9.3, Rtools 3.4 NA windows-2008 Windows c(“windows”, “rtools3”) rtools3 NA NA
windows-x86_64-release Windows Server 2008 R2 SP1, R-release, 32/64 bit r-release-windows-ix86+x86_64 r-release Windows x86_64 Windows Server 2008 R2 SP1 GCC 4.9.3, Rtools 3.4 NA windows-2008 Windows c(“windows”, “rtools3”) rtools3 NA NA

Shortcuts for quick checks

These are quick shortcuts that select the right platform(s):

Sanitizers for compiled code

R-hub provides a special Docker image to run Address Sanitizer (ASAN) and Undefined Behavior Sanitizer (UBSAN). This is based on the r-devel-san image of the Rocker project.

This image does not run R CMD check at all, but it runs

  1. package tests,
  2. all manual examples, and
  3. all vignette code

with ASAN and UBSAN enabled. Use it via check_with_sanitizers().

Browse previous checks

Once a check is finished (or failed), you will get a notification email but you can also get information from R. E.g. you could submit a check for a package located at <package-path>, then turn off your computer and on the following days retrieve results via

You can then extract checks from this list using their group ID (ID for checks submitted simultaneously e.g. via check_for_cran()) or id (check id). In both cases you’ll get a rhub_check object.

Here’s an example where we extract the last group of checks, print it to the screen, and query its URLs.

── note 1.0: NOTE

  Build ID:   note_1.0.tar.gz-00c375b187024da7a32c27ef94fa8832
  Platform:   Windows Server 2008 R2 SP1, R-devel, 32/64 bit
  Submitted:  4d 1h 44m 17.5s ago
  Build time: 1m 46.2s

❯ checking CRAN incoming feasibility ... NOTE
  Maintainer: 'Ma�lle Salmon <maelle.salmon@yahoo.se>'
  
  New submission
  The Description field contains
  
    <http://http://cran.r-project.org/doc/manuals/r-release/R-exts.html#The-DESCRIPTION-file>
  Please enclose URLs in angle brackets (<...>).
  
  The Date field is over a month old.

❯ checking R code for possible problems ... NOTE
  .bello: no visible global function definition for 'tail'
  Undefined global functions or variables:
    tail
  Consider adding
    importFrom("utils", "tail")
  to your NAMESPACE file.

0 errors ✔ | 0 warnings ✔ | 2 notes ✖

── note 1.0: NOTE

  Build ID:   note_1.0.tar.gz-5d6712942ce243dcb8d34f7bdfc8ccc6
  Platform:   Fedora Linux, R-devel, clang, gfortran
  Submitted:  4d 1h 44m 17.6s ago
  Build time: 1m 7.2s

❯ checking CRAN incoming feasibility ... NOTE
  Maintainer: ‘Maëlle Salmon <maelle.salmon@yahoo.se>
  
  New submission
  
  The Description field contains
    <http://http://cran.r-project.org/doc/manuals/r-release/R-exts.html#The-DESCRIPTION-file>
  Please enclose URLs in angle brackets (<...>).
  
  The Date field is over a month old.

❯ checking R code for possible problems ... NOTE
  .bello: no visible global function definition for ‘tail’
  Undefined global functions or variables:
    tail
  Consider adding
    importFrom("utils", "tail")
  to your NAMESPACE file.

0 errors ✔ | 0 warnings ✔ | 2 notes ✖

── note 1.0: NOTE

  Build ID:   note_1.0.tar.gz-61a75439c8b64c409a72c079dce20d30
  Platform:   Ubuntu Linux 16.04 LTS, R-release, GCC
  Submitted:  4d 1h 44m 17.7s ago
  Build time: 53.2s

❯ checking CRAN incoming feasibility ... NOTE
  Maintainer: ‘Maëlle Salmon <maelle.salmon@yahoo.se>
  
  New submission
  
  The Description field contains
    <http://http://cran.r-project.org/doc/manuals/r-release/R-exts.html#The-DESCRIPTION-file>
  Please enclose URLs in angle brackets (<...>).
  
  The Date field is over a month old.

❯ checking R code for possible problems ... NOTE
  .bello: no visible global function definition for ‘tail’
  Undefined global functions or variables:
    tail
  Consider adding
    importFrom("utils", "tail")
  to your NAMESPACE file.

0 errors ✔ | 0 warnings ✔ | 2 notes ✖

We could similarly extract the last check.

Prepare a CRAN submission

First, run check_for_cran() and assign the result to an object (or retrieve the results from a previous check_for_cran() submission by its group ID as shown in the previous subsection). Then once the checks are done, use the cran_summary() method to get a message that you can copy-paste in your cran-comments.md file (created via e.g. usethis::use_cran_comments()).

For more general information about CRAN submissions, refer to

Get more info and help

The R-hub builder has a documentation website.

If you need further help with the rhub package or the R-hub package builder in general (e.g. if you think a system dependency is missing), please refer to: