4 Running R CMD check
R includes a command-line tool called R CMD check
whose purpose is to check
whether an R package meets key requirements. At minimum, any package submitted
to CRAN must pass R CMD check
without producing any errors.
R CMD check
includes the regression tests discussed in the
“Running the testthat Tests” sectionbut is also more
expansive. Key components of R CMD check
are:
It runs the regression tests in the
tests
directory. For more information about using thetestthat
package for regression tests, see the Testing section of the “R Packages” textbook.It runs all of the examples, which are short pieces of code in the documentation for individual functions in the package. The examples can be found in the
examples
sections of the.Rd
files in theman
directory. For more information about examples, see the Examples section of the “R Packages” textbook.It builds the vignettes, which are long-form pieces of documentation that can be found in the
vignettes
directory. For more information about vignettes, see the Vignettes section of the “R Packages” textbook. Note that any vignettes inside thevignettes/web_only
directory are excluded from this check because that directory has been added to BioCro’s.Rbuildignore
file.
For more information about the individual checks that compose R CMD check
,
please see its entry in the “R Packages” textbook.
In the course of BioCro development, we frequently run R CMD check
to make
sure our code meets these requirements. Since R CMD check
is so thorough, it
is an important tool for identifying issues that may occur when changes are made
to the code.
R CMD check
identifies issues with a range of severity. Anything labeled as an
“error” is a serious issue and must be addressed. “Warnings” should almost
always be addressed, and “notes” are the least serious.
There are several ways to run R CMD check
, as described below.
4.1 Running R CMD check online
There is a GitHub action for running R CMD check
on multiple operating systems
and versions of R. It runs automatically in several situations (such as creating
a pull request), but also can be triggered manually on any branch. See the
“Continuous integration workflow” section for more details.
Running R CMD check
online tends to be slower than running it locally.
4.2 Running R CMD check locally
4.2.1 From the command line
Since R CMD check
is a command line tool, a basic way to run it is from the
command line. It is necessary to run R CMD build
first; this “builds” the
package by building the vignettes and compiling all the files into a single
archive.
To do this, open a terminal running in the parent directory of a local copy of
the BioCro repository, and then run the following command, assuming that the
BioCro repository is stored in a directory called biocro
:
R CMD build --compact-vignettes=both biocro
If there are any issues with the vignettes, one or more errors will occur at
this stage. They must be addressed to actually “build” the package. If this
command is successful, it will create a new file called BioCro_X.Y.Z.tar.gz
,
where X.Y.Z
is the version of the BioCro package that was built. Then the
package can be checked with
R CMD check --as-cran BioCro_X.Y.Z.tar.gz
In these commands, --compact-vignettes=both
and --as-cran
are optional
arguments. We usually compact the vignettes before submitting to CRAN to ensure
we meet package size requirements, while the “as-cran” option ensures that the
R CMD check
behavior matches the checks actually used by CRAN.
4.2.2 From within R
There are also options for running R CMD check
from within R. These R
functions generally build and check the package, so they can be simpler than the
command line approach.
The central option is the rcmdcheck
function from the rcmdcheck
package. To
use it, start an R session running in the parent directory of a local copy of
the BioCro repository, and then run the following command, assuming that the
BioCro repository is stored in a directory called biocro
:
Here the “as-cran” and “error on warning” options ensure that the R CMD check
behavior matches the checks actually used by CRAN.
It also possible to use the check
function from the devtools
package,
although that command is essentially just a wrapper for rcmdcheck::rcmdcheck
.