3.6 Passing CRAN checks
The objective of this section is:
- Categorize errors in the R CMD check process
Before submitting a package to CRAN, you must pass a battery of tests that are run by the R itself via the R CMD check
program. In RStudio, if you are in an R Package “Project” you can run R CMD check
by clicking the Check
button in the build tab. This will run a series of tests that check the metadata in your package, the NAMESPACE file, the code, the documentation, run any tests, build any vignettes, and many others.
Here is an example of the output form R CMD check
for the filehash
package which currently passes all tests.
* using R version 3.3.2 (2016-10-31)
* using platform: x86_64-apple-darwin13.4.0 (64-bit)
* using session charset: UTF-8
* checking for file 'filehash/DESCRIPTION' ... OK
* this is package 'filehash' version '2.3'
* checking package namespace information ... OK
* checking package dependencies ... OK
* checking if this is a source package ... OK
* checking if there is a namespace ... OK
* checking for executable files ... OK
* checking for hidden files and directories ... OK
* checking for portable file names ... OK
* checking for sufficient/correct file permissions ... OK
* checking whether package 'filehash' can be installed ... OK
* checking installed package size ... OK
* checking package directory ... OK
* checking 'build' directory ... OK
* checking DESCRIPTION meta-information ... OK
* checking top-level files ... OK
* checking for left-over files ... OK
* checking index information ... OK
* checking package subdirectories ... OK
* checking R files for non-ASCII characters ... OK
* checking R files for syntax errors ... OK
* checking whether the package can be loaded ... OK
* checking whether the package can be loaded with stated dependencies ... OK
* checking whether the package can be unloaded cleanly ... OK
* checking whether the namespace can be loaded with stated dependencies ... OK
* checking whether the namespace can be unloaded cleanly ... OK
* checking loading without being on the library search path ... OK
* checking dependencies in R code ... OK
* checking S3 generic/method consistency ... OK
* checking replacement functions ... OK
* checking foreign function calls ... OK
* checking R code for possible problems ... OK
* checking Rd files ... OK
* checking Rd metadata ... OK
* checking Rd cross-references ... OK
* checking for missing documentation entries ... OK
* checking for code/documentation mismatches ... OK
* checking Rd \usage sections ... OK
* checking Rd contents ... OK
* checking for unstated dependencies in examples ... OK
* checking line endings in C/C++/Fortran sources/headers ... OK
* checking compiled code ... OK
* checking sizes of PDF files under 'inst/doc' ... OK
* checking installed files from 'inst/doc' ... OK
* checking files in 'vignettes' ... OK
* checking examples ... OK
* checking for unstated dependencies in 'tests' ... OK
* checking tests ...
OK* checking for unstated dependencies in vignettes ... OK
* checking package vignettes in 'inst/doc' ... OK
* checking running R code from vignettes ...
'filehash.Rnw' ... OK
OK* checking re-building of vignette outputs ... OK
* checking PDF version of manual ... OK
* DONE
: OK Status
Here is an example from the mvtsplot
package where we’ve deliberately introduced some problems to the package in order to show the check output. Checks that have passed are not shown below.
* checking foreign function calls ... OK
* checking R code for possible problems ... NOTE
: no visible global function definition for ‘Axis’
drawImage: no visible global function definition for ‘lm’
drawImageMargin: no visible global function definition for ‘Axis’
drawImageMargin: no visible global function definition for ‘lm’
splineFillIn:
Undefined global functions or variables
Axis lm
Consider addingimportFrom("graphics", "Axis")
importFrom("stats", "lm")
to your NAMESPACE file.
Here, it appears that the functions Axis()
and lm()
are needed by the package but are not available because they are not imported from their respective packages. In this case, R CMD check
provides a suggestion of how you can modify the NAMESPACE package, but you are probably better off modifying the roxygen2
documentation in the code file instead.
Moving on the rest of the checks, we see:
* checking for missing documentation entries ... OK
* checking for code/documentation mismatches ... WARNING
'mvtsplot':
Codoc mismatches from documentation object
mvtsplot: function(x, group = NULL, xtime = NULL, norm = c("internal",
Code"global"), levels = 3, smooth.df = NULL, margin =
TRUE, sort = NULL, main = "", palette = "PRGn",
rowstat = "median", xlim, bottom.ylim = NULL,
right.xlim = NULL, gcol = 1)
: function(y, group = NULL, xtime = NULL, norm = c("internal",
Docs"global"), levels = 3, smooth.df = NULL, margin =
TRUE, sort = NULL, main = "", palette = "PRGn",
rowstat = "median", xlim, bottom.ylim = NULL,
right.xlim = NULL, gcol = 1)
in code not in docs:
Argument names
xin docs not in code:
Argument names
yin argument names:
Mismatches : 1 Code: x Docs: y Position
Here the problem is that the code has the first argument named x
while the documentation has the first argument named y
.
* checking Rd \usage sections ... WARNING
in documentation object 'mvtsplot'
Undocumented arguments
‘y’in \usage in documentation object 'mvtsplot':
Documented arguments not
‘x’
Functions with \usage entries need to have the appropriate \alias
entries, and all their arguments documented.
The \usage entries must correspond to syntactically valid R code.'Writing R documentation files' in the 'Writing R
See chapter Extensions' manual.
Because of the mismatch in code and documentation for the first argument, we have an argument that is not properly documented (y
) and an argument that is documented but not used (x
).
In case the checks fly by too quickly, you will receive a summary message the end saying what errors and warnings you got.
* DONE
: 2 WARNINGs, 1 NOTE Status
A package cannot be submitted to CRAN if there are any errors or warnings. If there is a NOTE, a package may be submitted if there is a Really Good Reason for that note.