R CMD CHECK
The R CMD CHECK is a process that runs through about 50+ checklists to verify that an R package is “well-developed” after it has been developed, including whether a function’s usage is well-written, whether a function’s parameters are well-written, etc.
Of course, there is nothing wrong with distributing and running your package via github without strictly performing an R CMD CHECK, but you should only share your package via an official repository like CRAN once you have proven that you can minimize errors in your package and deliver a stable package to your users.
This post won’t go into specifics, but if you’re interested, Hadley Wickham’s R Packages is a good place to start.
In any case, R CMD CHECK can be done with the devtools::check() function or the Check button in Rstudio if you have created an R package using the devtools package, and you can check for issues that are recommended to be fixed with Warnings, Errors, Notes, etc.
However, one of the features of R CMD CHECK is that it checks based on the environment of the PC on which the package is developed. In the image below, the package is tested and guaranteed to run in the macOS (Apple clang) environment, but if the user’s OS is not mac, such as window or linux, the package may not work properly.
Developing R packages often involves testing on a variety of OSes, as CRAN does not specify a preferred OS, but requires tests to work on at least two of Windows, macOS, and linux.
For this purpose, it would be great to have a variety of OS hardware, i.e. windows PC, mac, linux servers, but this is rarely the case and most of the time we use CI/CD services like Github actions, AppVeyor, Travis CI, etc. to perform testing on different OS.
Github action
In this post, I will introduce GitHub action as a reference, but the process is similar for other services.
Github action is a CI/CD service provided by Github that allows you to perform automated testing, builds, deployments, and more (by running commands on a server provided by github) using various actions provided by Github.
An Action can be thought of as a collection of commands organized in a yml file, such as installing R on a server, installing an R package, or running R CMD CHECK. R-hub actions, R-lib actions for references.
In other words, the actions including this R CMD CHECK are executed on the server through github action, and the results are checked and uploaded to CRAN. One of the problems with github action is that the yml syntax for using actions is quite heterogeneous, as shown in the example below.
r-hub2
The r-hub project is one of the projects of the R Consortium, whose purpose is to help R developers better develop R packages. One of its roles is to help perform testing on different OSes, and it does this by developing the Github actions mentioned above, providing infrastructure, and helping the community solve problems.
However, the R-hub project has recently developed and released an R package, rhub, to help you set up this GHA.
As explained in the official blog, you can use it to set up a Github Action that allows you to easily perform R CMD CHECK on various OS, even if you didn’t already used a Github Action.
The first thing we need to do is, of course, install the rhub package. Here, pak is recommended to replace traditional package installation methods such as install.packages and remotes::install_github with a function that provides unified support for installing R packages from various sources.
pak::pkg_install("rhub")Note that the rhub package should be installed and run as rhub, not rhub2, although the official version is 2.
In this post, I will refer to it as rhub.To run this rhub package, you need the following three things, but if you have experience developing R packages and sharing them on github, you don’t need to prepare anything new.
- A github account.
- A repository where you uploaded the R package. If you want to CRAN it, it should be public.
- Github PAT (Personal Access Token), which can be obtained from github, or you can use another R package called
gitcreds.
Setup
The first thing to do after finishing the rhub package is to run the rhub_setup function in the R package directory, which recognizes the git repository in the directory and generates a yml file for the Github Action.
We used the gemini.R package we created earlier as an example in the image below.
If all goes well, the rhub package will also walk you through the next steps, which is to commit the added yml file to github to reflect the update and then run the rhub_doctor function.
Doctor
The rhub_doctor function checks if the Github PAT is set properly. The rhub_check function of rhub, which will be introduced later, is responsible for manually executing Github Actions using the mentioned Github PAT in Rstudio’s console, so it is necessary to check the PAT settings.
The Github PAT can be created from the link “https://github.com/settings/tokens”, but only if you create it with the repo and workflow permissions granted.
To set the Github PAT for Rstudio, use the set_github_pat function in the credential package. See this
If the rhub_doctor function worked correctly, all that’s left is to run the rhub_check function.
Check
The previous steps were not an exaggeration to say that they were preparatory work for this function.
The rhub_check function recognizes the github repository and PAT, and then takes an input value on which OS to perform R CMD CHECK.
At this time, in addition to Windows, macOS, and Linux, you can select various OS (provided by the rhub project) by separating them with numbers and commas as shown in the image.
After running the function, it provides a link that can be connected to the GHA page, so you can check the progress through it.
Finally, when you add a test pass using rhub and GHA to the repository as a badge, it will look like the image below.
To add a badge icon to the readme, you need to write as follows.
In the example used, replace
Please note that this R CMD CHECK through Github Action takes some time, so it is recommended to run it after completing R CMD CHECK on the PC under development.
Of course, rhub also provides guidance for cases other than github or public repositories, but this is not described separately because it is not closely related to most R packages, especially CRAN.
Summary
In this post, I introduced the rhub package for R package developers to use Github Action. Through this, R package developers can minimize package errors and create better packages through R CMD CHECK on various OS, not only in the local environment.
For more detailed information, including the original text, you can also check the rhub blog.
Content Translated with DeepL Translator and Github Copilot
Reuse
Citation
@online{kim2024,
author = {Kim, Jinhwan},
title = {Rhub와 {Github} {action를} {활용한} {OS별} {R} {패키지}
{검증}},
date = {2024-05-13},
url = {https://blog.zarathu.com/en/posts/2024-05-13-rhub},
langid = {en}
}