Get started with rhub

Source: vignettes/rhub.Rmd

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.

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.

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.

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
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 Debian clang version 11.0.1-2 debian-clang-devel linux-x86_64-debian-clang Linux linux linux 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 (Debian 10.2.1-6) 10.2.1 20210110 debian-gcc-devel linux-x86_64-debian-gcc Linux linux linux NA
debian-gcc-devel-nold Debian Linux, R-devel, GCC, no long double NA r-devel Linux x86_64 Debian GNU/Linux testing gcc (Debian 10.2.1-6) 10.2.1 20210110 debian-gcc-devel-nold linux-x86_64-debian-gcc Linux linux linux NA
debian-gcc-patched Debian Linux, R-patched, GCC r-patched-linux-x86_64 r-patched Linux x86_64 Debian GNU/Linux testing gcc (Debian 10.2.1-6) 10.2.1 20210110 debian-gcc-patched linux-x86_64-debian-gcc Linux linux linux NA
debian-gcc-release Debian Linux, R-release, GCC r-release-linux-x86_64 r-release Linux x86_64 Debian GNU/Linux testing gcc (Debian 10.2.1-6) 10.2.1 20210110 debian-gcc-release linux-x86_64-debian-gcc Linux linux linux NA
fedora-clang-devel Fedora Linux, R-devel, clang, gfortran r-devel-linux-x86_64-fedora-clang r-devel Linux x86_64 Fedora 33 clang version 11.0.0 (Fedora 11.0.0-2.fc33) fedora-clang-devel linux-x86_64-fedora-clang Linux linux linux NA
fedora-gcc-devel Fedora Linux, R-devel, GCC r-devel-linux-x86_64-fedora-gcc r-devel Linux x86_64 Fedora 33 gcc (GCC) 10.2.1 20201125 (Red Hat 10.2.1-9) fedora-gcc-devel linux-x86_64-fedora-gcc Linux linux linux 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
ubuntu-gcc-devel Ubuntu Linux 20.04.1 LTS, R-devel, GCC NA r-devel Linux x86_64 Ubuntu 20.04.1 LTS gcc (Ubuntu 9.3.0-17ubuntu1~20.04) 9.3.0 ubuntu-gcc-devel linux-x86_64-ubuntu-gcc Linux linux linux NA
ubuntu-gcc-release Ubuntu Linux 20.04.1 LTS, R-release, GCC NA r-release Linux x86_64 Ubuntu 20.04.1 LTS gcc (Ubuntu 9.3.0-17ubuntu1~20.04) 9.3.0 ubuntu-gcc-release linux-x86_64-ubuntu-gcc Linux linux linux NA
ubuntu-rchk Ubuntu Linux 20.04.1 LTS, R-devel with rchk NA r-devel Linux x86_64 Ubuntu 20.04.1 LTS clang version 12.0.0-3ubuntu1~20.04.5 ubuntu-rchk linux-x86_64-ubuntu-gcc Checks for compiled code linux linux rchk
windows-x86_64-devel Windows Server 2022, R-devel, 64 bit r-devel-windows-x86_64-new-UL r-devel Windows x86_64 Windows Server 2022 GCC 10.3.0, Rtools42 NA windows-2022 Windows windows-ucrt ucrt NA
windows-x86_64-oldrel Windows Server 2022, R-oldrel, 32/64 bit r-oldrel-windows-ix86+x86_64 r-oldrel Windows x86_64 Windows Server 2028 GCC 8.3.0, Rtools 4.0 NA windows-2022 Windows windows, rtools4 rtools4 NA
windows-x86_64-patched Windows Server 2022, R-patched, 32/64 bit NA r-patched Windows x86_64 Windows Server 2022 R2 SP1 GCC 8.3.0, Rtools 4.0 NA windows-2008 Windows windows, rtools4 rtools4 NA
windows-x86_64-release Windows Server 2022, R-release, 32/64 bit r-release-windows-ix86+x86_64 r-release Windows x86_64 Windows Server 2022 GCC 8.3.0, Rtools 4.0 NA windows-2022 Windows windows, rtools4 rtools4 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/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 ✖
group_check$urls()
# A tibble: 3 x 4
  html                 text                 artifacts             stringsAsFactors
  <chr>                <chr>                <chr>                 <lgl>           
1 https://builder-tes… https://builder-tes… https://artifacts.r-… FALSE           
2 https://builder-tes… https://builder-tes… https://artifacts.r-… FALSE           
3 https://builder-tes… https://builder-tes… https://artifacts.r-… FALSE

We could similarly extract the last check.

check_id <- previous_checks$id[1]
rhub::get_check(check_id)

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()).

cran_prep <- check_for_cran()
cran_prep$cran_summary()
#> ## Test environments
#> - R-hub fedora-clang-devel (r-devel)
#>  - R-hub windows-x86_64-devel (r-devel)
#>  - R-hub ubuntu-gcc-release (r-release)
#> 
#> ## R CMD check results
#> ❯ On fedora-clang-devel (r-devel), windows-x86_64-devel (r-devel), ubuntu-gcc-release (r-release)
#>   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.
#> 
#> ❯ On fedora-clang-devel (r-devel), windows-x86_64-devel (r-devel), ubuntu-gcc-release (r-release)
#>   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 ✖

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: