Paragraphasing Writing R Extensions, an R package is “directory of files which extend R”. These files have to follow a standard structure: you can’t store everything that suits your fancy in a tarball you submit to CRAN. In this post we shall go through what directories and files can go on CRAN and how to navigate this while shipping everything you want to CRAN and keeping some things in the package source only.
At the moment of writing, what a built package can contain is this list called known defined in the R source, in tools/R/check.R.
Non-standard files Now, in a package folder, you might have all sorts of different things * some configuration files for continuous integration, for a pkgdown website, etc; * the source of a Shiny app; * cran-comments.md for your CRAN submissions.
Note that sometimes R CMD check could complain about files you don’t see in the source because they are created by the checking process. In that case, take a step back and try to fix your code, e.g. cleaning after yourself if examples create files. Now, how do you keep the items that sparkle joy in the bundled package and in your package source, without endangering R CMD check passing?
Excluding files from the bundled package There are files that don’t need to make it into a built package (e.g., your CRAN comments, your pkgdown config.). R CMD build filtering To prevent files and folders from making it from the package source to the bundled package, we need to understand how things work: How do files and directories end up, or not, in the tarball/bundled package, from the source package? That’s one job of R CMD build possibly via a wrapper like devtools::build(). It will copy your whole package source and then remove files in three “steps”
.Rbuildignore So, if your package source features any file or directory that is not known, not standard, and also not listed in the common exclusions, then you need to add it to .Rbuildignore. As written in “Writing R extensions”, “To exclude files from being put into the package, one can specify a list of exclude patterns in file .Rbuildignore in the top-level source directory. These patterns should be Perl-like regular expressions (see the help for regexp in R for the precise details), one per line, to be matched case-insensitively against the file and directory names relative to the top-level package source directory.”.
Often, you’ll see stuff is stored in inst/: classic elements such as citation information in inst/CITATION, raw data in inst/extdata/ but also more modern or exotic elements such as RStudio addins.
What about .Rinstignore? .Rbuildignore has a sibling called .Rinstignore for another use case: “The contents of the inst subdirectory will be copied recursively to the installation directory. Subdirectories of inst should not interfere with those used by R (currently, R, data, demo, exec, libs, man, help, html and Meta, and earlier versions used latex, R-ex). The copying of the inst happens after src is built so its Makefile can create files to be installed. To exclude files from being installed, one can specify a list of exclude patterns in file .Rinstignore in the top-level source directory. These patterns should be Perl-like regular expressions (see the help for regexp in R for the precise details), one per line, to be matched case-insensitively against the file and directory paths, e.g. doc/.*[.]png$ will exclude all PNG files in inst/doc based on the extension.”
“Keep only those things that speak to your heart.” … that we need to amend… “Keep only those things that speak to your R CMD check.”