Help for package rhub

Title:

Tools for R Package Developers

Version:

2.0.1

Description:

R-hub v2 uses GitHub Actions to run 'R CMD check' and similar package checks. The 'rhub' package helps you set up R-hub v2 for your R package, and start running checks.

License:

MIT + file LICENSE

URL:

https://github.com/r-hub/rhub, https://r-hub.github.io/rhub/

BugReports:

https://github.com/r-hub/rhub/issues

RoxygenNote:

7.3.2

Depends:

R (≥ 4.0)

Imports:

callr, cli, curl, desc, gert, glue, gitcreds, jsonlite, pkgbuild, processx, rappdirs, rematch, R6, rprojroot, utils, whoami

Suggests:

asciicast, debugme, knitr, mockery, pillar, rmarkdown, testthat (≥ 3.0.0), webfakes, withr

Encoding:

UTF-8

Config/testthat/edition:

NeedsCompilation:

Packaged:

2025-03-06 22:13:05 UTC; gaborcsardi

Author:

Gábor Csárdi [aut, cre], Maëlle Salmon

[aut], R Consortium [fnd]

Maintainer:

Gábor Csárdi <csardi.gabor@gmail.com>

Repository:

CRAN

Date/Publication:

2025-03-06 22:40:02 UTC

The rhub package

Description

Tools for R package developers

Details

Installation

Install rhub from CRAN:

pak::pkg_install("rhub")

Usage

Requirements

A Github account.
Your R package must be in a GitHub repository.
You need a GitHub Personal Access Token. You can use the gitcreds package to add the token to the git credential store.

See the R Consortium runners section for using rhub if your package is not on GitHub.

Private repositories

rhub uses GitHub Actions, which is free for public repositories. For private repositories you also get some minutes for free, depending on the GitHub subscription you have. See About billing for GitHub Actions for details.

Setup

Switch to the directory of your package, and call rhub::rhub_setup() to add the R-hub workflow file to your package.

rhub::rhub_setup()

#> Setting up R-hub v2.                                                            
#> ✔ Found R package at /private/tmp/cli.                                          
#> ✔ Found git repository at /private/tmp/cli.                                     
#> ✔ Created workflow file /private/tmp/cli/.github/workflows/rhub.yaml.           
#>                                                                                 
#> Notes:                                                                          
#> • The workflow file must be added to the default branch of the GitHub           
#>   repository.                                                                   
#> • GitHub actions must be enabled for the repository. They are disabled for      
#>   forked repositories by default.                                               
#>                                                                                 
#> Next steps:                                                                     
#> • Add the workflow file to git using `git add <filename>`.                      
#> • Commit it to git using `git commit`.                                          
#> • Push the commit to GitHub using `git push`.                                   
#> • Call `rhub::rhub_doctor()` to check that you have set up R-hub correctly.     
#> • Call `rhub::rhub_check()` to check your package.

Run ⁠git commit⁠ and ⁠git push⁠ to push the workflow file to GitHub.
Run rhub::rhub_doctor() to check if everything is set up correctly:

rhub::rhub_doctor()

#> ✔ Found R package at /private/tmp/cli.                                          
#> ✔ Found git repository at /private/tmp/cli.                                     
#> ✔ Found GitHub PAT.                                                             
#> ✔ Found repository on GitHub at <https://github.com/r-lib/cli>.                 
#> ✔ GitHub PAT has the right scopes.                                              
#> ✔ Found R-hub workflow in default branch, and it is active.                     
#> → WOOT! You are ready to run `rhub::rhub_check()` on this package.

Run checks

Use rhub::rhub_platforms() to get a list of supported platforms and checks:

rhub::rhub_platforms()

#> ── Virtual machines ─────────────────────────────────────────────────────────── 
#>  1 [VM]  linux                                                                  
#>    All R versions on GitHub Actions ubuntu-latest                               
#>  2 [VM]  macos                                                                  
#>    All R versions on GitHub Actions macos-latest                                
#>  3 [VM]  macos-arm64                                                            
#>    All R versions on GitHub Actions macos-14                                    
#>  4 [VM]  windows                                                                
#>    All R versions on GitHub Actions windows-latest                              
#>                                                                                 
#> ── Containers ───────────────────────────────────────────────────────────────── 
#>  5 [CT]  atlas  [ATLAS]                                                         
#>    R Under development (unstable) (2024-03-19 r86153) on Fedora Linux 38 (Conta…
#>    ghcr.io/r-hub/containers/atlas:latest                                        
#>  6 [CT]  clang-asan  [asan, clang-ASAN, clang-UBSAN, ubsan]                     
#>    R Under development (unstable) (2024-03-19 r86153) on Ubuntu 22.04.4 LTS     
#>    ghcr.io/r-hub/containers/clang-asan:latest                                   
#>  7 [CT]  clang16  [clang16]                                                     
#>    R Under development (unstable) (2024-03-18 r86148) on Ubuntu 22.04.4 LTS     
#>    ghcr.io/r-hub/containers/clang16:latest                                      
#>  8 [CT]  clang17  [clang17]                                                     
#>    R Under development (unstable) (2024-03-18 r86148) on Ubuntu 22.04.4 LTS     
#>    ghcr.io/r-hub/containers/clang17:latest                                      
#>  9 [CT]  clang18  [clang18]                                                     
#>    R Under development (unstable) (2024-03-18 r86148) on Ubuntu 22.04.4 LTS     
#>    ghcr.io/r-hub/containers/clang18:latest                                      
#> 10 [CT]  donttest  [donttest]                                                   
#>    R Under development (unstable) (2024-03-18 r86148) on Ubuntu 22.04.4 LTS     
#>    ghcr.io/r-hub/containers/donttest:latest                                     
#> 11 [CT]  gcc13  [gcc13]                                                         
#>    R Under development (unstable) (2024-03-19 r86153) on Fedora Linux 38 (Conta…
#>    ghcr.io/r-hub/containers/gcc13:latest                                        
#> 12 [CT]  intel  [Intel]                                                         
#>    R Under development (unstable) (2024-03-19 r86153) on Fedora Linux 38 (Conta…
#>    ghcr.io/r-hub/containers/intel:latest                                        
#> 13 [CT]  mkl  [MKL]                                                             
#>    R Under development (unstable) (2024-03-19 r86153) on Fedora Linux 38 (Conta…
#>    ghcr.io/r-hub/containers/mkl:latest                                          
#> 14 [CT]  nold  [noLD]                                                           
#>    R Under development (unstable) (2024-03-19 r86153) on Ubuntu 22.04.4 LTS     
#>    ghcr.io/r-hub/containers/nold:latest                                         
#> 15 [CT]  nosuggests  [noSuggests]                                               
#>    R Under development (unstable) (2024-03-19 r86153) on Fedora Linux 38 (Conta…
#>    ghcr.io/r-hub/containers/nosuggests:latest                                   
#> 16 [CT]  ubuntu-clang  [r-devel-linux-x86_64-debian-clang]                      
#>    R Under development (unstable) (2024-03-19 r86153) on Ubuntu 22.04.4 LTS     
#>    ghcr.io/r-hub/containers/ubuntu-clang:latest                                 
#> 17 [CT]  ubuntu-gcc12  [r-devel-linux-x86_64-debian-gcc]                        
#>    R Under development (unstable) (2024-03-19 r86153) on Ubuntu 22.04.4 LTS     
#>    ghcr.io/r-hub/containers/ubuntu-gcc12:latest                                 
#> 18 [CT]  ubuntu-next  [r-next, r-patched, r-patched-linux-x86_64]               
#>    R version 4.3.3 Patched (2024-02-29 r86153) on Ubuntu 22.04.4 LTS            
#>    ghcr.io/r-hub/containers/ubuntu-next:latest                                  
#> 19 [CT]  ubuntu-release  [r-release, r-release-linux-x86_64, ubuntu]            
#>    R version 4.3.3 (2024-02-29) on Ubuntu 22.04.4 LTS                           
#>    ghcr.io/r-hub/containers/ubuntu-release:latest                               
#> 20 [CT]  valgrind  [valgrind]                                                   
#>    R Under development (unstable) (2024-03-19 r86153) on Fedora Linux 38 (Conta…
#>    ghcr.io/r-hub/containers/valgrind:latest

Run rhub::rhub_check() to start R-hub v2 checks on GitHub Actions:

rhub::rhub_check()

#> ✔ Found git repository at /private/tmp/cli.                                     
#> ✔ Found GitHub PAT.                                                             
#>                                                                                 
#> Available platforms (see `rhub::rhub_platforms()` for details):                 
#>                                                                                 
#>  1 [VM] linux          R-* (any version)                     ubuntu-latest on G…
#>  2 [VM] macos          R-* (any version)                     macos-latest on Gi…
#>  3 [VM] macos-arm64    R-* (any version)                     macos-14 on GitHub 
#>  4 [VM] windows        R-* (any version)                     windows-latest on …
#>  5 [CT] atlas          R-devel (2024-03-19 r86153)           Fedora Linux 38 (C…
#>  6 [CT] clang-asan     R-devel (2024-03-19 r86153)           Ubuntu 22.04.4 LTS 
#>  7 [CT] clang16        R-devel (2024-03-18 r86148)           Ubuntu 22.04.4 LTS 
#>  8 [CT] clang17        R-devel (2024-03-18 r86148)           Ubuntu 22.04.4 LTS 
#>  9 [CT] clang18        R-devel (2024-03-18 r86148)           Ubuntu 22.04.4 LTS 
#> 10 [CT] donttest       R-devel (2024-03-18 r86148)           Ubuntu 22.04.4 LTS 
#> 11 [CT] gcc13          R-devel (2024-03-19 r86153)           Fedora Linux 38 (C…
#> 12 [CT] intel          R-devel (2024-03-19 r86153)           Fedora Linux 38 (C…
#> 13 [CT] mkl            R-devel (2024-03-19 r86153)           Fedora Linux 38 (C…
#> 14 [CT] nold           R-devel (2024-03-19 r86153)           Ubuntu 22.04.4 LTS 
#> 15 [CT] nosuggests     R-devel (2024-03-19 r86153)           Fedora Linux 38 (C…
#> 16 [CT] ubuntu-clang   R-devel (2024-03-19 r86153)           Ubuntu 22.04.4 LTS 
#> 17 [CT] ubuntu-gcc12   R-devel (2024-03-19 r86153)           Ubuntu 22.04.4 LTS 
#> 18 [CT] ubuntu-next    R-4.3.3 (patched) (2024-02-29 r86153) Ubuntu 22.04.4 LTS 
#> 19 [CT] ubuntu-release R-4.3.3 (2024-02-29)                  Ubuntu 22.04.4 LTS 
#> 20 [CT] valgrind       R-devel (2024-03-19 r86153)           Fedora Linux 38 (C…
#>                                                                                 
#> Selection (comma separated numbers, 0 to cancel): 1, 5                          
#>                                                                                 
#> ✔ Check started: linux, atlas (apricot-flycatcher).                             
#>   See <https://github.com/r-lib/cli/actions> for live output!

The R Consortium runners

If you don't want to put your package on GitHub, you can still use the rhub package to run package checks on any supported platform using a shared pool of runners in the https://github.com/r-hub2 GitHub organization.

The process is similar to the first version of R-hub:

Set your working directory to the R package you want to check.
Obtain a token from R-hub, to verify your email address:
```
rc_new_token()
```
(You do not need to do this, if you already submitted packages to a previous version of R-hub from the same machine, using the same email address. Call rc_list_local_tokens() to check if you already have tokens.)
Submit a build with
```
rc_submit()
```
Select the platforms you want to use, and follow the instructions and the link provided to see your check results.

Limitations of the R Consortium runners

You package will be public for the world, and will be stored in the https://github.com/r-hub2 organization. Your check output and results will be public for anyone with a GitHub account. If you want to keep your package private, you can put it in a private GitHub repository, and use the rhub_setup() and rhub_check() functions instead.
The R Consortium runners are shared among all users, so you might need to wait for your builds to start.
You have to wait at least five minutes between submissions with rc_submit().
Currently you need to create a GitHub account to see the check logs of your package. You don't need a GitHub account to submit the checks.

To avoid these limitations (except for the need for a GitHub account), put your package in a GitHub repository, and use the rhub_setup() and rhub_check() functions instead of rc_submit() and the R Consortium runners.

Code of Conduct

Please note that the rhub package is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.

License

MIT © R Consortium

This function is deprecated and defunct. Please see rhubv2.

Description

This function is deprecated and defunct. Please see rhubv2.

Usage

check(...)

Arguments

...

Deprecated.

This function is deprecated and defunct. Please see rhubv2.

Description

This function is deprecated and defunct. Please see rhubv2.

Usage

check_for_cran(...)

Arguments

...

Deprecated.

This function is deprecated and defunct. Please see rhubv2.

Description

This function is deprecated and defunct. Please see rhubv2.

Usage

check_on_linux(...)

check_on_windows(...)

check_on_macos(...)

check_on_debian(...)

check_on_ubuntu(...)

check_on_fedora(...)

check_on_solaris(...)

check_on_centos(...)

check_with_roldrel(...)

check_with_rrelease(...)

check_with_rpatched(...)

check_with_rdevel(...)

check_with_valgrind(...)

check_with_sanitizers(...)

Arguments

...

Deprecated.

This function is deprecated and defunct. Please see rhubv2.

Description

This function is deprecated and defunct. Please see rhubv2.

Usage

get_check(...)

Arguments

...

Deprecated.

This function is deprecated and defunct. Please see rhubv2.

Description

This function is deprecated and defunct. Please see rhubv2.

Usage

last_check(...)

Arguments

...

Deprecated.

This function is deprecated and defunct. Please see rhubv2.

Description

This function is deprecated and defunct. Please see rhubv2.

Usage

list_my_checks(...)

Arguments

...

Deprecated.

This function is deprecated and defunct. Please see rhubv2.

Description

This function is deprecated and defunct. Please see rhubv2.

Usage

list_package_checks(...)

Arguments

...

Deprecated.

This function is deprecated and defunct. Please see rhubv2.

Description

This function is deprecated and defunct. Please see rhubv2.

Usage

list_validated_emails(...)

Arguments

...

Deprecated.

This function is deprecated and defunct. Please see rhubv2.

Description

This function is deprecated and defunct. Please see rhubv2.

Usage

local_check_linux(...)

Arguments

...

Deprecated.

This function is deprecated and defunct. Please see rhubv2.

Description

This function is deprecated and defunct. Please see rhubv2.

Usage

local_check_linux_images(...)

Arguments

...

Deprecated.

This function is deprecated and defunct. Please see rhubv2.

Description

This function is deprecated and defunct. Please see rhubv2.

Usage

platforms(...)

Arguments

...

Deprecated.

Show your tokens for the R Consortium runners

Description

Lists all tokens stored on the local machine.

Usage

rc_list_local_tokens()

Value

Data frame with string columns email and token.

List your repositories created by the R Consortium runners

Description

Lists repositories created by rc_submit() submissions.

Usage

rc_list_repos(email = NULL)

Arguments

email

Email address. We try to detect this, but if the detection fails, you can specify it explicitly.

Value

Data frame with columns:

repo_name: Name of the repository.
repo_url: URL of the repository.
builds_url: URL to the builds of the repository.

Additional columns and customized printing will be probably added later to the result.

Request a new token for submissions to the R Consortium runners

Description

To build and check R packages on the RC runners of R-hub, you'll need to verify your email address. R-hub will send a token to your email address, and this token will be stored on your computer.

Usage

rc_new_token(email = NULL, token = NULL)

Arguments

email

Email address to verify We try to detect this, but if the detection fails, you can specify it explicitly. If this argument is missing (or NULL), then you can specify it interactively.

token

Token to add. If you already received a token in an email from R-hub, you can specify that here.

Details

You need to store a token on every computer you want to submit jobs from, either using the same token from the email you got, or you can request additional tokens for the new machines. Your old token will stay valid as well.

If you already have a token from a previous version of R-hub, you can reuse that and you don't need to do anything.

Run

rhub:::email_file()

to see the file rhub uses to store your tokens.

Submit a package to the R Consortium runners

Description

Submit a package to the R Consortium runners

Usage

rc_submit(path = ".", platforms = NULL, email = NULL, confirmation = NULL)

Arguments

path

Path to package file or package directory.

platforms

Platforms to checks. See rhub_platforms() for a current list. If not specified, then you can select the platforms interactively. Must be specified in non-interactive sessions.

email

Email address. You must have a token on the local machhine, that corresponds to the email address, see rc_new_token(). If not specified (or NULL) then the email address of the package maintainer is used.

confirmation

You must set this to TRUE to submit a package from a non-interactive session.

Value

A list with data about the submission, invisibly. Currently it has:

result: Should be the string "OK".
repo_url: URL to the repository.
actions_url: URL to the builds inside the repository.
id: Build id. This is a string with a randomly generated id.
name: Build name, this is a string, the concatenation of the build platforms.

More fields might be added later.

Check a package on R-hub

Description

Check a package on R-hub

Usage

rhub_check(gh_url = NULL, platforms = NULL, r_versions = NULL, branch = NULL)

Arguments

gh_url

GitHub URL of a package to check, or NULL to check the package in the current directory.

platforms

Platforms to use, a character vector. Use NULL to select from a list in interactive sessions. See rhub_platforms().

r_versions

Which R version(s) to use for the platforms that supports multiple R versions. This argument is not implemented yet.

branch

Branch to use to run R-hub. Defaults to the current branch if gh_url is NULL. Otherwise defaults to "main". Note that this branch also need to include the rhub.yaml workflow file.

Value

TODO

Check if the current or the specified package is ready to use with R-hub

Description

Errors if the package or repository is not set up correctly, and advises on possible solutions.

Usage

rhub_doctor(gh_url = NULL)

Arguments

gh_url

Use NULL for the package in the current working directory. Alternatively, use the URL of a GitHub repository that contains an R package that was set up to use with R-hub.

List R-hub platforms

Description

List R-hub platforms

Usage

rhub_platforms()

Value

Data frame with columns:

name: platform name. Use this in the platforms argument of rhub_check().
aliases: alternative platform names. They can also be used in the platforms argument of rhub_check().
type: "os" or "container".
os_type: Linux, macOS or Windows currently.
container: URL of the container image for container platforms.
github_os: name of the OS on GitHub Actions for non-container platforms.
r_version: R version string. If "*" then any supported R version can be selected for this platform.
os_name: name of the operating system, including Linux distribution name and version for container actions.

Setup the current R package for use with R-hub

Description

It adds or updates the R-hub workflow file to the current package, and advises on next steps.

Usage

rhub_setup(overwrite = FALSE)

Arguments

overwrite

if TRUE, rhub_setup() will overwrite an already existing workflow file.

Value

Nothing.

R-hub v2

Description

Start here to learn about R-hub v2, especially if you used the previous version of R-hub before.

R-hub v2

Introduction

R-hub v2, i.e. version 2 or later of the rhub package, is a completely new check system. In this article we highlight the differences between the old and the new system.

There are two ways to use R-hub v2. The recommended way is to store your R package in a GitHub repository and use the ⁠rhub_*()⁠ functions to start checks on GitHub Actions, using your own GitHub account.

Alternatively, if you don't want to store your R package at GitHub, you can use the ⁠rc_*()⁠ functions to run checks in a shared GitHub organization at https://github.com/r-hub2, using the R Consortium runners. See more about the R Consortium runners below.

Transitioning from R-hub v1

Requirements for using R-hub v2

First, you need a GitHub account.
Second, you need to have your R package in a GitHub repository. In your local git clone make sure that the origin git remote is set to the GitHub repository.
Third, you need a GitHub Personal Access Token and you need to store it in the git credential store on your machine. You can use gitcreds::gitcreds_set() to add the token to the git credential store.

Call rhub_setup() from the local git clone to set up R-hub v2 for your package. This adds a GitHub Actions workflow to your local repository. Push this change to GitHub, into your default git branch and then you are ready to call start checks with rhub_check().

Differences from R-hub v1

The check picks up the package from GitHub, so it does not use changes in your local git clone. You need to push the changes to GitHub first. You can use a non-default branch, with the branch argument of rhub_check().
You won't get an email about the check results. But you'll receive regular GitHub notifications about check failures, unless you opt out. Github can also turn these into emails if you like.
There is no live output from the check at the R console. See the 'Actions' tab of your repository on GitHub for a live check log.
Many more specialized platforms are available.
Most platforms use binary packages, so checks and in particular installing dependencies is much faster.

Private repositories

GitHub Actions is free for public repositories. For private repositories you also get some minutes for free, depending on the GitHub subscription you have. See About billing for GitHub Actions for details.

Branches

You can run checks on any branch that you push to GitHub, but you'll need to add the R-hub workflow file (.github/workflows/rhub.yaml within your repo) must be present in both the default branch (usually main) and also in the branch you want to run the check on.

The R Consortium runners

The process is similar to the first version of R-hub:

Set your working directory to the R package you want to check.
Obtain a token from R-hub, to verify your email address:
```
rc_new_token()
```
(You do not need to do this, if you already submitted packages to a previous version of R-hub from the same machine, using the same email address. Call rc_list_local_tokens() to check if you already have tokens.)
Submit a build with
```
rc_submit()
```
Select the platforms you want to use, and follow the instructions and the link provided to see your check results.

Limitations of the R Consortium runners

You package will be public for the world, and will be stored in the https://github.com/r-hub2 organization. Your check output and results will be public for anyone with a GitHub account. If you want to keep your package private, you can put it in a private GitHub repository, and use the rhub_setup() and rhub_check() functions instead.
The R Consortium runners are shared among all users, so you might need to wait for your builds to start.
You have to wait at least five minutes between submissions with rc_submit().
Currently you need to create a GitHub account to see the check logs of your package. You don't need a GitHub account to submit the checks.

This function is deprecated and defunct. Please see rhubv2.

Description

This function is deprecated and defunct. Please see rhubv2.

Usage

validate_email(...)

Arguments

...

Deprecated.

The rhub package

Description

Details

Installation

Usage

Requirements

Private repositories

Setup

Run checks

The R Consortium runners

Limitations of the R Consortium runners

Code of Conduct

License

This function is deprecated and defunct. Please see rhubv2.

Description

Usage

Arguments

This function is deprecated and defunct. Please see rhubv2.

Description

Usage

Arguments

This function is deprecated and defunct. Please see rhubv2.

Description

Usage

Arguments

This function is deprecated and defunct. Please see rhubv2.

Description

Usage

Arguments

This function is deprecated and defunct. Please see rhubv2.

Description

Usage

Arguments

This function is deprecated and defunct. Please see rhubv2.

Description

Usage

Arguments

This function is deprecated and defunct. Please see rhubv2.

Description

Usage

Arguments

This function is deprecated and defunct. Please see rhubv2.

Description

Usage

Arguments

This function is deprecated and defunct. Please see rhubv2.

Description

Usage

Arguments

This function is deprecated and defunct. Please see rhubv2.

Description

Usage

Arguments

This function is deprecated and defunct. Please see rhubv2.

Description

Usage

Arguments

Show your tokens for the R Consortium runners

Description

Usage

Value

See Also

List your repositories created by the R Consortium runners

Description

Usage

Arguments

Value

See Also

Request a new token for submissions to the R Consortium runners

Description

Usage

Arguments

Details

See Also

Submit a package to the R Consortium runners

Description

Usage

Arguments

Value

See Also