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.

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

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	macos-version	params
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	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 (Debian 10.2.1-6) 10.2.1 20210110	debian-gcc-devel	linux-x86_64-debian-gcc	Linux	linux	linux	NA	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 (Debian 10.2.1-6) 10.2.1 20210110	debian-gcc-devel-nold	linux-x86_64-debian-gcc	Linux	linux	linux	NA	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 (Debian 10.2.1-6) 10.2.1 20210110	debian-gcc-patched	linux-x86_64-debian-gcc	Linux	linux	linux	NA	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 (Debian 10.2.1-6) 10.2.1 20210110	debian-gcc-release	linux-x86_64-debian-gcc	Linux	linux	linux	NA	NA	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	NA	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	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	NA
macos-highsierra-release	macOS 10.13.6 High Sierra, R-release, brew	NA	r-release	macOS	x86_64	Mac OS 10.13.6	XCode 10.1, Apple LLVM version 10.0.0 (clang-1000.10.44.4)	NA	osx-x86_64-clang	macOS	macos , highsierra, r-release	highsierra	NA	highsierra	NA
macos-highsierra-release-cran	macOS 10.13.6 High Sierra, R-release, CRAN’s setup	r-release-osx-x86_64	r-release	macOS	x86_64	Mac OS 10.13.6	XCode 10.1, Apple LLVM version 10.0.0 (clang-1000.10.44.4)	NA	osx-x86_64-clang	macOS	macos , highsierracran, r-release	highsierracran	NA	highsierra	NA
macos-m1-bigsur-release	Apple Silicon (M1), macOS 11.6 Big Sur, R-release	r-release-macos-arm64	r-release	macOS	aarch64	Mac OS 11.6	XCode 12.4, Apple clang version 12.0.0	NA	osx-aarch64-clang	macOS	macos , m1 , r-release	m1	NA	bigsur	NA
solaris-x86-patched	Oracle Solaris 10, x86, 32 bit, R-release	r-patched-solaris-x86	r-release	Solaris	x86_64	SunOS unknown 5.10 Generic_147148-26 i86pc i386 i86pc	GCC 5.5.0	NA	solaris-10	Solaris	solaris	solaris	NA	NA	NA
solaris-x86-patched-ods	Oracle Solaris 10, x86, 32 bit, R release, Oracle Developer Studio 12.6	r-patched-solaris-x86	r-release	Solaris	x86_64	SunOS unknown 5.10 Generic_147148-26 i86pc i386 i86pc	Oracle Developer Studio 12.6	NA	solaris-10	Solaris	solaris	solaris	NA	NA	ods=true
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	NA	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	NA	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	NA	NA
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	NA	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	NA	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	NA	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	NA	NA

Shortcuts for quick checks

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

check_on_linux() and check_on_windows() select the operating system.
check_on_debian(), check_on_ubuntu(), check_on_fedora() and check_on_centos() select an appropriate Linux platform.
check_on_solaris() also selects an operating system, Solaris, and by default checks neither vignettes nor manual (--no-manual --no-build-vignettes).
check_with_roldrel(), check_with_rrelease(), check_with_rpatched() and check_with_rdevel() select an R version.
check_for_cran() runs checks on platforms that are closest to platforms used by CRAN on submission:
- Fedora Linux, R-devel, clang, gfortran,
- Ubuntu Linux 16.04 LTS, R-release, GCC,
- Windows Server 2008 R2 SP1, R-devel, 32⁄64 bit,
- and, if your package needs compilation, Debian Linux, R-devel, GCC ASAN/UBSAN. You can run rhub:::default_cran_check_platforms(<package-path>) to find out which platforms will be selected for your package.
check_with_valgrind() runs the build and check on Linux, in valgrind to find memory leaks and pointer errors.
check_with_sanitizers() runs all package package tests, examples and vignettes with Address Sanitizer and Undefined Behavior Sanitizer, see below.

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

package tests,
all manual examples, and
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

CRAN itself whose checklist suggest using R-hub :-);
this book chapter;
this collaborative list.

Get started with `rhub`