Chapter 8 Tools

The behavior of R CMD check can be controlled through a variety of command line arguments and environment variables.

There is an internal –install=value command line argument not shown by R CMD check –help, with possible values

check:file

Assume that installation was already performed with stdout/stderr to file, the contents of which need to be checked (without repeating the installation). This is useful for checks applied by repository maintainers: it reduces the check time by the installation time given that the package has already been installed. In this case, one also needs to specify where the package was installed to using command line option –library.

fake

Fake installation, and turn off the run-time tests.

skip

Skip installation, e.g., when testing recommended packages bundled with R.

no

The same as –no-install : turns off installation and the tests which require the package to be installed.

The following environment variables can be used to customize the operation of check: a convenient place to set these is the check environment file (default, ~/.R/check.Renviron).

R_CHECK_ALL_NON_ISO_C

If true, do not ignore compiler (typically GCC) warnings about non ISO C code in system headers. Note that this may also show additional ISO C++ warnings. Default: false.

R_CHECK_FORCE_SUGGESTS

If true, give an error if suggested packages are not available. Default: true (but false for CRAN submission checks).

R_CHECK_RD_CONTENTS

If true, check Rd files for auto-generated content which needs editing, and missing argument documentation. Default: true.

R_CHECK_RD_LINE_WIDTHS

If true, check Rd line widths in usage and examples sections. Default: false (but true for CRAN submission checks).

R_CHECK_RD_STYLE

If true, check whether Rd usage entries for S3 methods use the full function name rather than the appropriate \method markup. Default: true.

R_CHECK_RD_XREFS

If true, check the cross-references in .Rd files. Default: true.

R_CHECK_SUBDIRS_NOCASE

If true, check the case of directories such as R and man. Default: true.

R_CHECK_SUBDIRS_STRICT

Initial setting for –check-subdirs. Default: ‘default’ (which checks only tarballs, and checks in the src only if there is no configure file).

R_CHECK_USE_CODETOOLS

If true, make use of the codetools package, which provides a detailed analysis of visibility of objects (but may give false positives). Default: true (if recommended packages are installed).

R_CHECK_USE_INSTALL_LOG

If true, record the output from installing a package as part of its check to a log file (00install.out by default), even when running interactively. Default: true.

R_CHECK_VIGNETTES_NLINES

Maximum number of lines to show from the bottom of the output when reporting errors in running or re-building vignettes. (As from R 3.4.0, 0 means all lines will be shown.) Default: 10 for running, 25 for re-building.

R_CHECK_CODOC_S4_METHODS

Control whether codoc() testing is also performed on S4 methods. Default: true.

R_CHECK_DOT_INTERNAL

Control whether the package code is scanned for .Internal calls, which should only be used by base (and occasionally by recommended) packages. Default: true.

R_CHECK_EXECUTABLES

Control checking for executable (binary) files. Default: true.

R_CHECK_EXECUTABLES_EXCLUSIONS

Control whether checking for executable (binary) files ignores files listed in the package’s BinaryFiles file. Default: true (but false for CRAN submission checks). However, most likely this package-level override mechanism will be removed eventually.

R_CHECK_PERMISSIONS

Control whether permissions of files should be checked. Default: true iff .Platform$OS.type == “unix”.

R_CHECK_FF_CALLS

Allows turning off checkFF() testing. If set to ‘registration’, checks the registration information (number of arguments, correct choice of .C/.Fortran/.Call/.External) for such calls provided the package is installed. Default: true.

R_CHECK_FF_DUP

Controls checkFF(check_DUP) Default: true (and forced to be true for CRAN submission checks).

R_CHECK_LICENSE

Control whether/how license checks are performed. A possible value is ‘maybe’ (warn in case of problems, but not about standardizable non-standard license specs). Default: true.

R_CHECK_RD_EXAMPLES_T_AND_F

Control whether check_T_and_F() also looks for “bad” (global) ‘T’/‘F’ uses in examples. Off by default because this can result in false positives.

R_CHECK_RD_CHECKRD_MINLEVEL

Controls the minimum level for reporting warnings from checkRd. Default: -1.

R_CHECK_XREFS_REPOSITORIES

If set to a non-empty value, a space-separated list of repositories to use to determine known packages. Default: empty, when the CRAN and Bioconductor repositories known to R is used.

R_CHECK_SRC_MINUS_W_IMPLICIT

Control whether installation output is checked for compilation warnings about implicit function declarations (as spotted by GCC with command line option -Wimplicit-function-declaration, which is implied by -Wall). Default: false.

R_CHECK_SRC_MINUS_W_UNUSED

Control whether installation output is checked for compilation warnings about unused code constituents (as spotted by GCC with command line option -Wunused, which is implied by -Wall). Default: true.

R_CHECK_WALL_FORTRAN

Control whether gfortran 4.0 or later -Wall warnings are used in the analysis of installation output. Default: false, even though the warnings are justifiable.

R_CHECK_ASCII_CODE

If true, check R code for non-ascii characters. Default: true.

R_CHECK_ASCII_DATA

If true, check data for non-ascii characters. Default: true.

R_CHECK_COMPACT_DATA

If true, check data for ascii and uncompressed saves, and also check if using bzip2 or xz compression would be significantly better. Default: true.

R_CHECK_SKIP_ARCH

Comma-separated list of architectures that will be omitted from checking in a multi-arch setup. Default: none.

R_CHECK_SKIP_TESTS_ARCH

Comma-separated list of architectures that will be omitted from running tests in a multi-arch setup. Default: none.

R_CHECK_SKIP_EXAMPLES_ARCH

Comma-separated list of architectures that will be omitted from running examples in a multi-arch setup. Default: none.

R_CHECK_VC_DIRS

Should the unpacked package directory be checked for version-control directories (CVS, .svn …)? Default: true for tarballs.

R_CHECK_PKG_SIZES

Should du be used to find the installed sizes of packages? R CMD check does check for the availability of du. but this option allows the check to be overruled if an unsuitable command is found (including one that does not respect the -k flag to report in units of 1Kb, or reports in a different format – the GNU, macOS and Solaris du commands have been tested). Default: true if du is found.

R_CHECK_DOC_SIZES

Should qpdf be used to check the installed sizes of PDFs? Default: true if qpdf is found.

R_CHECK_DOC_SIZES2

Should gs be used to check the installed sizes of PDFs? This is slower than (and in addition to) the previous check, but does detect figures with excessive detail (often hidden by over-plotting) or bitmap figures with too high a resolution. Requires that R_GSCMD is set to a valid program, or gs (or on Windows, gswin32.exe or gswin64c.exe) is on the path. Default: false (but true for CRAN submission checks).

R_CHECK_ALWAYS_LOG_VIGNETTE_OUTPUT

By default the output from running the R code in the vignettes is kept only if there is an error. This also applies to the build_vignettes.log log from the re-building of vignettes. Default: false.

R_CHECK_CLEAN_VIGN_TEST

Should the vign_test directory be removed if the test is successful? Default: true.

R_CHECK_REPLACING_IMPORTS

Should warnings about replacing imports be reported? These sometimes come from auto-generated NAMESPACE files in other packages, but most often from importing the whole of a namespace rather than using importFrom. Default: true.

R_CHECK_UNSAFE_CALLS

Check for calls that appear to tamper with (or allow tampering with) already loaded code not from the current package: such calls may well contravene CRAN policies. Default: true.

R_CHECK_TIMINGS

Optionally report timings for installation, examples, tests and running/re-building vignettes as part of the check log. The format is ‘[as/bs]’ for the total CPU time (including child processes) ‘a’ and elapsed time ‘b’, except on Windows, when it is ‘[bs]’. In most cases timings are only given for ‘OK’ checks. Times with an elapsed component over 10 mins are reported in minutes (with abbreviation ‘m’). The value is the smallest numerical value in elapsed seconds that should be reported: non-numerical values indicate that no report is required, a value of ‘0’ that a report is always required. Default: “”. (10 for CRAN checks.)

R_CHECK_INSTALL_DEPENDS

If set to a true value and a test installation is to be done, this is done with .libPaths() containing just a temporary library directory and .Library. The temporary library is populated by symbolic links²² to the installed copies of all the Depends/Imports/LinkingTo packages which are not in .Library. Default: false (but true for CRAN submission checks).

Note that this is actually implemented in R CMD INSTALL, so it is available to those who first install recording to a log, then call R CMD check.

R_CHECK_DEPENDS_ONLY
R_CHECK_SUGGESTS_ONLY

If set to a true value, running examples, tests and vignettes is done with .libPaths() containing just a temporary library directory and .Library. The temporary library is populated by symbolic links²³ to the installed copies of all the Depends/Imports and (for the second only) Suggests packages which are not in .Library. (As an exception, packages in a ‘VignetteBuilder’ field are always made available.) Default: false (but R_CHECK_SUGGESTS_ONLY is true for CRAN checks).

R_CHECK_NO_RECOMMENDED

If set to a true value, augment the previous checks to make recommended packages unavailable unless declared. Default: false (but true for CRAN submission checks).

This may give false positives on code which uses grDevices::densCols and stats:::asSparse as these invoke KernSmooth and Matrix respectively.

R_CHECK_CODETOOLS_PROFILE

A string with comma-separated name=value pairs (with value a logical constant) giving additional arguments for the codetools functions used for analyzing package code. E.g., use R_CHECK_CODETOOLS_PROFILE=“suppressLocalUnused=FALSE” to turn off suppressing warnings about unused local variables. Default: no additional arguments, corresponding to using skipWith = TRUE, suppressPartialMatchArgs = FALSE and suppressLocalUnused = TRUE.

R_CHECK_CRAN_INCOMING

Check whether package is suitable for publication on CRAN. Default: false, except for CRAN submission checks.

R_CHECK_CRAN_INCOMING_REMOTE

Include checks that require remote access among the above. Default: same as R_CHECK_CRAN_INCOMING

R_CHECK_XREFS_USE_ALIASES_FROM_CRAN

When checking anchored Rd xrefs, use Rd aliases from the CRAN package web areas in addition to those in the packages installed locally. Default: false.

R_SHLIB_BUILD_OBJECTS_SYMBOL_TABLES

Make the checks of compiled code more accurate by recording the symbol tables for objects (.o files) at installation in a file symbols.rds. (Only currently supported on Linux, Solaris, macOS, Windows and FreeBSD.) Default: true.

R_CHECK_CODE_ASSIGN_TO_GLOBALENV

Should the package code be checked for assignments to the global environment? Default: false (but true for CRAN submission checks).

R_CHECK_CODE_ATTACH

Should the package code be checked for calls to attach()? Default: false (but true for CRAN submission checks).

R_CHECK_CODE_DATA_INTO_GLOBALENV

Should the package code be checked for calls to data() which load into the global environment? Default: false (but true for CRAN submission checks).

R_CHECK_DOT_FIRSTLIB

Should the package code be checked for the presence of the obsolete function .First.lib()? Default: false (but true for CRAN submission checks).

R_CHECK_DEPRECATED_DEFUNCT

Should the package code be checked for the presence of recently deprecated or defunct functions (including completely removed functions). Also for platform-specific graphics devices. Default: false (but true for CRAN submission checks).

R_CHECK_SCREEN_DEVICE

If set to ‘warn’, give a warning if examples etc open a screen device. If set to ‘stop’, give an error. Default: empty (but ‘stop’ for CRAN submission checks).

R_CHECK_WINDOWS_DEVICE

If set to ‘stop’, give an error if a Windows-only device is used in example etc. This is only useful on Windows: the devices do not exist elsewhere. Default: empty (but ‘stop’ for CRAN submission checks on Windows).

R_CHECK_TOPLEVEL_FILES

Report on top-level files in the package sources that are not described in ‘Writing R Extensions’ nor are commonly understood (like ChangeLog). Variations on standard names (e.g. COPYRIGHT) are also reported. Default: false (but true for CRAN submission checks).

R_CHECK_GCT_N

Should the –use-gct use gctorture2(n) rather than gctorture(TRUE)? Use to a positive integer to enable this. Default: 0.

R_CHECK_LIMIT_CORES

If set, check the usage of too many cores in package parallel. If set to ‘warn’ gives a warning, to ‘false’ or ‘FALSE’ the check is skipped, and any other non-empty value gives an error when more than 2 children are spawned. Default: unset (but ‘TRUE’ for CRAN submission checks).

R_CHECK_CODE_USAGE_VIA_NAMESPACES

If set, check code usage (via codetools) directly on the package namespace without loading and attaching the package and its suggests and enhances. Default: true (and true for CRAN submission checks).

R_CHECK_CODE_USAGE_WITH_ONLY_BASE_ATTACHED

If set, check code usage (via codetools) with only the base package attached. Default: true.

R_CHECK_EXIT_ON_FIRST_ERROR

If set to a true value, the check will exit on the first error. Default: false.

R_CHECK_S3_METHODS_NOT_REGISTERED

If set to a true value, report (apparent) S3 methods exported but not registered. Default: false (but true for CRAN submission checks).

R_CHECK_OVERWRITE_REGISTERED_S3_METHODS

If set to a true value, report already registered S3 methods in base/recommended packages which are overwritten when this package’s namespace is loaded. Default: false (but true for CRAN submission checks).

R_CHECK_TESTS_NLINES

Number of trailing lines of test output to reproduce in the log. If 0 all lines except the R preamble are reproduced. Default: 13.

R_CHECK_NATIVE_ROUTINE_REGISTRATION

If set to a true value, report if the entry points to register native routines and to suppress dynamic search are not found in a package’s DLL. (NB: this requires system commands nm and on Windows, objdump.exe to be on the PATH. This would be normal when using a package with compiled code (which are the only ones this checks), but Windows’ users should check.) Default: false (but true for CRAN submission checks).

CRAN’s submission checks use something like

_R_CHECK_CRAN_INCOMING_=TRUE
_R_CHECK_CRAN_INCOMING_REMOTE_=TRUE
_R_CHECK_VC_DIRS_=TRUE
_R_CHECK_TIMINGS_=10
_R_CHECK_INSTALL_DEPENDS_=TRUE
_R_CHECK_SUGGESTS_ONLY_=TRUE
_R_CHECK_NO_RECOMMENDED_=TRUE
_R_CHECK_EXECUTABLES_EXCLUSIONS_=FALSE
_R_CHECK_DOC_SIZES2_=TRUE
_R_CHECK_CODE_ASSIGN_TO_GLOBALENV_=TRUE
_R_CHECK_CODE_ATTACH_=TRUE
_R_CHECK_CODE_DATA_INTO_GLOBALENV_=TRUE
_R_CHECK_CODE_USAGE_VIA_NAMESPACES_=TRUE
_R_CHECK_DOT_FIRSTLIB_=TRUE
_R_CHECK_DEPRECATED_DEFUNCT_=TRUE
_R_CHECK_REPLACING_IMPORTS_=TRUE
_R_CHECK_SCREEN_DEVICE_=stop
_R_CHECK_TOPLEVEL_FILES_=TRUE
_R_CHECK_S3_METHODS_NOT_REGISTERED_=TRUE
_R_CHECK_OVERWRITE_REGISTERED_S3_METHODS_=TRUE

These are turned on by R CMD check –as-cran: the incoming checks also use

_R_CHECK_FORCE_SUGGESTS_=FALSE

since some packages do suggest other packages not available on CRAN or other commonly-used repositories.

Another variable which enables stricter checks is to set R_CHECK_CONSTANTS to 5. This checks that nothing²⁴ changes the values of ‘constants’²⁵ in R code. This is best used in conjunction with setting R_JIT_STRATEGY to 3, which checks code on first use (by default most code is only checked after byte-compilation on second use). Unfortunately these checks slow down checking of examples, tests and vignettes, typically two-fold but in the worst cases at least a hundred-fold.

---