Documentation

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

You are now reading R-hub documentation website, currently a work in progress. The website aims at documenting all R-hub services, of which the table of content on the left gives a good overview.

You can find the source of this website 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.

We use Google Analytics to log data and ultimately improve the docs. Below are the Hugo privacy settings we use for Google Analytics, within the Hugo config file for this website.

  [privacy.googleAnalytics]
    anonymizeIP = true
    disable = false
    respectDoNotTrack = true
    useSessionStorage = true

This means

• IP addresses are anonymized within Google Analytics,

• The GA templates respect the “Do Not Track” HTTP header,

• The use of Cookies is disabled, instead Session Storage to Store the GA Client ID is used.

This website is deployed via Netlify.

For more information, contact admin@rhub.io.

R-hub package builder: Run R CMD check on many different platforms (operating systems, R versions…), for free!

The best way to interact with R-hub package builder is from your R session, via the rhub package that has its own documentation website. The R-hub package builder also has a web interface.

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

• Email validation is easier via the package than via the webform.

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, 32/64 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.

To use the R-hub package builder, your email address needs to be validated. This allows R-hub to send you results after builds, and might be used for adding use quotas later on.

Email validation with the rhub package happens once and for all on each machine. Refer to the package docs.

Via the web interface, the validation happens

• either via email, you’ll need to copy-paste one token per package upload;

• or faster, using GitHub authentication if you have a GitHub account and your email address is listed publicly on your GitHub profile.

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.

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.
  • Refer to this detailed advice for compiled code, by R Core member Tomas Kalibera.
  • Ask for help.

Good luck!

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 artifacts i.e. the built package that you can download and send to your colleague; and in rhub, the output check functions has an urls() method returning the build and artifacts URLs . Be careful, artifacts 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.

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

You can send your secret API key, token, etc. to R-hub package builder when using the rhub package, via the env_vars argument of check functions.

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

The R-hub package builder installs all package dependencies on-demand, at build/check time, from CRAN, and possibly other sources, using the remotes package.

On platforms that make use of binaries, typically Windows and macOS, if your package depends on a package that is on CRAN that was only very recently released and that does not have a binary build yet, R-hub will try to build it. If it requires compilation, then R-hub might not be able to build it. Should this happen, please get in touch.

R-hub supports packages from other sources than CRAN (e.g. a package in development in a GitHub repository), this is useful for testing your package with non-CRAN dependencies. Refer to this remotes vignette for details.

To make sure system requirements are met for your package,

• Put the information in the SystemRequirements field of DESCRIPTION.
• Make sure the system requirements are matched by sysreqsdb. If not, contribute to sysreqsdb. Example: magick's DESCRIPTION, corresponding sysreqsdb entry.

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.

R-hub is not meant for checking reverse dependencies.

For local reverse dependencies checks refer to usethis::use_revdep(), the in-progress revdepcheck package; references like the R packages book, or this blog post.

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.

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.

R-hub Linux images are available on Docker hub, and their source is open, on GitHub.

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. Find more information in the README of R-hub Docker images repo.

The rhub package provides some helpers facilitating the use of R-hub Linux images.

There are other Docker images available online, not from R-hub, that might further help debugging R packages with C/C++ code: https://github.com/wch/r-debug; https://github.com/rocker-org/r-devel-san-clang; https://github.com/rocker-org/r-devel-san.

R-hub unofficially mirrors CRAN packages to the cran GitHub organization. Each CRAN package lives in its own GitHub repository, e.g. package Rcpp is at https://github.com/cran/Rcpp. All versions of all packages are included, and each version is a separate git commit, tagged with the version number. We tried to keep the original dates and authors/maintainers as well.

The main goal of CRAN @ GitHub is the easy access to the source code or CRAN packages. In particular, you can

• See differences between package versions, e.g. what changed between 1.2.0 and 1.2.1 in crayon.

• Fork packages, and create patched versions of them, for your own purposes.

• Use GitHub search functionality.

R-hub mirror of CRAN packages is one of the sources used by Jim Hester’s lookup package, that helps you lookup R full function definitions, including compiled code, S3 and S4 methods.

R-hub simplifies your getting download counts of CRAN packages from RStudio’s CRAN mirror download logs, that RStudio publishes daily at http://cran-logs.rstudio.com. The RStudio CRAN mirror is not the only CRAN mirror, but it’s a popular one: it’s the default choice for RStudio users. The actual number of downloads over all CRAN mirrors is unknown. Therefore, using numbers of downloads from that mirror is a proxy for actual numbers of downloads, and when analysing it one has to assume the observed trends are representative of what happens via other mirrors.

• R-hub provides a web API of the data, documented in its GitHub README. The service includes

  • data: downloads of R itself, downloads of packages over any time period, top downloads over the latest available day/week/month;
  • badges.

• R-hub maintains an official R client for the API, the CRAN cranlogs package. Refer to its documentation website.

R-hub supports the search of CRAN packages. This is different from R-hub’s support of code search in CRAN packages.

The search of CRAN packages, e.g. find all CRAN packages related to GLMs, is powered by R-hub search web service. R-hub also maintains an official R client, the CRAN pkgsearch package.

R-hub provides several types of badges for the README of your CRAN R package.

CRAN versions

These badges show the version number of the package on CRAN, or “not published” if the package is not published on CRAN.

https://www.r-pkg.org/badges/version/{package}

CRAN release dates

Variations on CRAN versions and release dates.

• https://www.r-pkg.org/badges/version-ago/{package}

• https://www.r-pkg.org/badges/version-last-release/{package}

• https://www.r-pkg.org/badges/ago/{package}

• https://www.r-pkg.org/badges/last-release/{package}

CRAN downloads

Shows number of downloads for a given package, see cranlogs.app README for more details and options.

https://cranlogs.r-pkg.org/badges/{summary}/{package}

Related services

Also check out badges from rOpenSci Scott Chamberlain for CRAN checks results https://github.com/ropenscilabs/cchecksapi#badges.

R-hub maintains the rversions CRAN package that queries the main R SVN repository to

• find the versions r-release and r-oldrel refer to,

• and also all previous R versions, their release dates and nicknames.

It can be useful to e.g. automatically assess whether the currently installed R version corresponds to r-release. For more information, refer to the package docs and GitHub repository.

About R-hub in particular

• R-hub community on gitter.

• rhub issue tracker, for any feedback.

• If you need to communicate sensitive information, contact admin@r-hub.io Otherwise please use the two public spaces mentioned above.

About R package development in general

Learning resources

Books

• Official Writing R Extensions guidance.

• R packages book by Hadley Wickham and Jenny Bryan.

Further resources

Refer to lists of resources in

• https://ropensci.github.io/dev_guide/contributingguide.html#prerequisites-for-package-development
• https://masalmon.eu/2017/12/11/goodrpackages/

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.

• R-package-devel mailing list. Perfect if you like emails! Read the archives to get a feel for it.

• RStudio community forum has a “package development” category.

• rOpenSci community forum in particular the Questions category and the Best Practice category.

• Stack Overflow.

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

• R-hub Vimeo channel, for screencasts

• Video recording of the RStudio webinar “R-Hub Overview”. Slides source.

• R-hub blog

• Original R-hub proposal, as submitted to the R Consortium in 2015.

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