knitr::opts_chunk$set( collapse = TRUE, comment = "#>" )
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)
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.
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. r platforms()$name[1]
,
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.
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.
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.
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)
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: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.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
with ASAN and UBSAN enabled. Use it via check_with_sanitizers()
.
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)
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 :-);
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:
If you need to communicate sensitive information, contact admin@r-hub.io Otherwise please use the two public spaces mentioned above.
Any scripts or data that you put into this service are public.
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.