What is R-hub?

R-hub is a collection of services to help R package development, free for all members of the community thanks to support from the R Consortium.

Its most prominent service is the package builder that allows building and checking any R package on several platforms and R versions, with submission happening via a webform or an R client.

What R-hub is not

  • A replacement of CRAN

Overview of R-hub components

Diagram showing R-hub components

The “coming soon” GitHub part is the future R-hub CI (continuous integration).

More details about R-hub services

Other services built around the package builder include:

  • R-hub Docker containers that allow local debugging on Linux
  • the possibility to deploy R-hub locally (not yet)
  • Continuous integration (not there yet either)

R-hub also includes:

  • A database (and API) of system requirements, accessible via an API, used by the package builder and usable by other external tools such as containerit and codemetar,
  • A database (and API) of CRAN downloads from the RStudio CRAN mirror, useful to assess packages’ popularity,
  • A database (and API) of R versions,
  • A database (and API) of CRAN packages, that’s searchable,
  • An unofficial mirror of all CRAN packages on GitHub, useful to search for code.

What is this website?

You are now reading R-hub documentation website, currently a work in progress. You can find its source on GitHub where your feedback is welcome. In particular, do get in touch if you find something unclear, or wish a topic were added. By contributing to this project you agree to its code of conduct. Thank you!

Except where otherwise noted, content on this site is licensed under the CC-BY license.

Package builder

R-hub package builder

What platform to use?

With R-hub you can build and check your package on 20 platforms (different operating systems/architectures, different R versions). It is very easy to check all boxes in the webform or to use rhub::platforms()[,1] as value for the platform argument of rhub::check(), but probably useless, a waste of R-hub resources and a waste of time for you (20 emails with very similar results!). Just because you can doesn’t mean you should! Here are a few tips to help you choose not too many platforms.

If you want to be confident your package works on all platforms, in particular for a CRAN submission

Use the R-hub 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, 3264 bit,
  • and, if your package needs compilation, Debian Linux, R-devel, GCC ASAN/UBSAN.

In general you’ll be better off using rhub rather than the web form. In particular, running rhub::check_for_cran() will automatically select the platforms mentioned above, including guessing whether your package needs compilation.

If you want to reproduce a CRAN error on an exotic platform

Choose the platform that’s closest to the CRAN platform.

R-hub package

You can interact with the R package builder via its API client, rhub, which is documented on its dedicated website.

Submit your package with the webform or the package?

You can submit a package using either the webform’s simple interface or with advanced options; or via the R package rhub. We strongly recommend using the package for a smoother workflow and more customization.

In more details, why rather use rhub?

  • Using the package is quite natural whilst you’re developing an R package in your favorite IDE. You might be used to devtools::check() to run checks locally, and devtools::check_win_devel() to bundle and send the package to Winbuilder. rhub::check() works very similarly: it can take the path to your package folder as argument (by default the current directory!), and will build and upload it. You can then watch the live log from your console, or wait until you get an email after the build.

  • When using the web interface you can set neither extra arguments for the R CMD check command nor environment variables to set on the builder machine, which you might actually need for finer control of the check, or e.g. to provide your secret web API key.

  • While you can select several platforms to build your package on via the web interface, you need to choose those by hand, whereas the package has handy shortcuts (even handier when using an editor with autocompletion like RStudio) such as rhub::check_on_windows() and the very useful rhub::check_on_cran().

What if you are not the package maintainer?

By default, R-hub builder (webform, package) will use the email address of the package maintainer listed in DESCRIPTION to identify you and send you an email after the build. You can however override this, via the advanced tab of the webform, and the email argument of the rhub::check() functions.

How do R-hub and CRAN platforms compare?

You might want to know how R-hub and CRAN platforms compare in general, but that’s especially crucial when you’re using R-hub to reproduce a failure for submitting or keeping your package on CRAN. For different reasons, including the constant evolution of CRAN platforms, R-hub platforms are not exactly similar.

If you run into an issue on CRAN that you want to reproduce we recommend

  • Looking at settings of CRAN platforms via https://cran.r-project.org/web/checks/check_flavors.html,

  • Looking at settings of R-hub platforms via tibble::as.tibble(rhub::platforms()),

  • Running a check on the closest R-hub platform to the problematic CRAN platform.

  • If that does not work,

    • If you guess what causes the issue is e.g. the particular compiler and your package has compiled code, download the compiler and try reproducing the issue locally.
    • Ask for help.

Good luck!

How to send my secret API key, token, etc. to R-hub?

You can do that with the rhub package, via the check_args argument of check functions.

You cannot do that with the web interface. See more reasons to use the package rather than the web interface.

How to build R packages for distributing them?

Imagine you want to share your package with colleague working on a different operating system, without access to tools for building packages on that platform. How do you create an appropriate binary for your package?

Once in a while

If you’re only doing this sporadically, you can use R-hub builder to build your package on the platform corresponding to your colleague’s computer. In the email you’ll receive after a (hopefully successful) build, there’s a link to artefacts i.e. the built package that you can download and send to your colleague; and rhub itself should soon get a method for retrieving artefacts. Be careful, artefacts only remain online for a few days so download them as soon as you can.

Regularly

If you want to regularly build and deploy your package on different platforms, what you are looking for is continuous integration.

  • R-hub CI. Not at the moment, but eventually R-hub will offer a CI service, unsurprisingly specific to R packages.

  • Appveyor (Windows). Each build has a tab with artefacts, and you could automate the workflow with scripts. Refer to Appveyor docs.

  • Travis (MacOS, Linux, soon Windows). Refer to Travis docs, for instance the page about uploading artefacts.

  • Other CI services surely support similar options.

Looking for help with one of these non R-hub CI services? Read our section about getting help.

How to inform R-hub of system requirements for my package?

To make sure system requirements are met for your package,

We hope to soon use sysreqsdb for all platforms. At the moment, R-hub only uses sysreqsdb to install system requirements on Linux platforms. For macOS and Windows, at the moment, to ensure system requirements are installed, you might open an issue asking for its installation on the platform directly especially for commonly used third-party software (see e.g. this CRAN list), and in general, if you have trouble getting the system requirements met on any R-hub platform, get in touch.

How to reproduce a bug uncovered by R-hub?

You could in theory experiment with your package, tinker with the code, submit it to R-hub again until the bug disappears but this would have a high turnaroud so is not optimal for debugging.

You can debug locally for Linux platforms, with R-hub Docker containers, no matter your operating system, granted you were able to install Docker itself.

https://github.com/r-hub/rhub-linux-builders#rhub-linux-builders

For other platforms that you do not have access to locally, you might need to ask for help. And if you think the problem is due to R-hub rather than due to your package, get in touch.

Where to get help?

About R-hub in particular

About R package development in general

Learning resources

Books
Further resources

Refer to lists of resources in

Read CRAN submission tips on ThinkR’s collaborative prepare-for-cran repo.

Places to ask questions

There are several relevant places to ask questions related to R package development. Do not cross post your question simultaneously in several places, but obviously you can re-post your question elsewhere if you have not got any answer after a while.

Here’s external guidance on how to ask questions and where to get R help in general.

Code of Conduct

As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.

We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, or religion.

Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.

This Code of Conduct is adapted from the Contributor Covenant (https://www.contributor-covenant.org), version 1.0.0, available at https://contributor-covenant.org/version/1/0/0/.