Get started with rhub

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.

check()

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-gcc-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.

mycheck <- check()
mycheck$browse()
mycheck$print()
mycheck$livelog()
mycheck$urls()

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.

name description cran-name rversion os-type cpu-type os-info compilers docker-image sysreqs-platform categories node-labels output-parser macos-version
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 6.2.0 (Debian 6.2.0-6) debian-gcc-devel linux-x86_64-debian-gcc 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 6.2.0 (Debian 6.2.0-6) debian-gcc-patched linux-x86_64-debian-gcc 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 6.2.0 (Debian 6.2.0-6) debian-gcc-release linux-x86_64-debian-gcc 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 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 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 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 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 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”) NA elcapitan
macos-mavericks-oldrel macOS 10.9 Mavericks, R-oldrel (experimental) r-oldrel-osx-x86_64 r-oldrel macOS x86_64 Mac OS X 10.9.5 13F1911 Apple LLVM version 6.0 (clang-600.0.57); GNU Fortran 4.2.3 NA osx-x86_64-clang macOS c(“macos”, “mavericks”, “r-oldrel”) NA mavericks
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 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 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 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 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”) 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”) 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”) 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”) 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”) 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

previous_checks <- rhub::list_package_checks(<package-path>,
                                  email = "maelle.salmon@yahoo.se",
                                  howmany = 4)
previous_checks
# A tibble: 10 x 13
   package version result group   id      platform_name build_time
   <chr>   <chr>   <rhub> <rhub:> <rhub:> <chr>         <time>    
 1 note    1.0     NN     e863a86 00c375b windows-x86_… ~1m       
 2 note    1.0     NN     e863a86 5d67129 fedora-clang… ~1m       
 3 note    1.0     NN     e863a86 61a7543 ubuntu-gcc-r… ~53.2s    
 4 note    1.0     NN     a99e137 197fd0e fedora-clang… ~46s      
 5 note    1.0     NN     a99e137 2ed7302 windows-x86_… ~1m       
 6 note    1.0     NN     a99e137 88293d9 ubuntu-gcc-r… ~36.7s    
 7 note    1.0     NN     9ceef8e 4f9113c windows-x86_… ~1m       
 8 note    1.0     NN     9ceef8e 6761ed2 ubuntu-gcc-r… ~35.9s    
 9 note    1.0     N      9ceef8e f8bc9d2 fedora-clang… ~57.9s    
10 note    1.0     ok     d3b8509 d3b8509 debian-gcc-d… ~45.5s    
# … with 6 more variables: submitted <dttm>, started <dttm>, platform <list>,
#   builder <chr>, status <rhub::status>, email <chr>

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.

group_id <- previous_checks$group[1]
group_check <- rhub::get_check(group_id)
group_check
── 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