No Clocks

Package development workflows make much more sense if you understand the five states an R package can be in: source bundled binary installed in-memory

You already know some of the functions that put packages into these states. For example, install.packages() can move a package from the source, bundled, or binary states into the installed state. devtools::install_github() takes a source package on GitHub and moves it into the installed state. The library() function loads an installed package into memory, making it available for immediate and direct use.

A source package is just a directory of files with a specific structure. It includes particular components, such as a DESCRIPTION file, an R/ directory containing .R files, and so on. Most of the remaining chapters in this book are dedicated to detailing these components.

A bundled package is a package that’s been compressed into a single file. By convention (from Linux), package bundles in R use the extension .tar.gz and are sometimes referred to as “source tarballs”. This means that multiple files have been reduced to a single file (.tar) and then compressed using gzip (.gz). While a bundle is not that useful on its own, it’s a platform-agnostic, transportation-friendly intermediary between a source package and an installed package.

In the rare case that you need to make a bundle from a package you’re developing locally, use devtools::build(). Under the hood, this calls pkgbuild::build() and, ultimately, R CMD build, which is described further in the Building package tarballs section of Writing R Extensions.

This should tip you off that a package bundle or “source tarball” is not simply the result of making a tar archive of the source files, then compressing with gzip. By convention, in the R world, a few more operations are carried out when making the .tar.gz file and this is why we’ve elected to refer to this form as a package bundle, in this book.

Every CRAN package is available in bundled form, via the “Package source” field of its landing page.

The main differences between a source package and an uncompressed bundle are: Vignettes have been built, so rendered outputs, such as HTML, appear below inst/doc/ and a vignette index appears in the build/ directory. A local source package might contain temporary files used to save time during development, like compilation artefacts in src/. These are never found in a bundle. Any files listed in .Rbuildignore are not included in the bundle. These are typically files that facilitate your development process, but that should be excluded from the distributed product.

Each line of .Rbuildignore is a Perl-compatible regular expression that is matched, without regard to case, against the path to each file in the source package1. If the regular expression matches, that file or directory is excluded. Note there are some default exclusions implemented by R itself, mostly relating to classic version control systems and editors, such as SVN, Git, and Emacs.

We usually modify .Rbuildignore with the usethis::use_build_ignore() function, which takes care of easy-to-forget details, such as regular expression anchoring and escaping. To exclude a specific file or directory (the most common use case), you MUST anchor the regular expression. For example, to exclude a directory called “notes”, the .Rbuildignore entry must be ^notes$, whereas the unanchored regular expression notes will match any file name containing “notes”, e.g. R/notes.R, man/important-notes.R, data/endnotes.Rdata, etc. We find that use_build_ignore() helps us get more of our .Rbuildignore entries right the first time.

.Rbuildignore is a way to resolve some of the tension between the practices that support your development process and CRAN’s requirements for submission and distribution (Chapter 22). Even if you aren’t planning to release on CRAN, following these conventions will allow you to make the best use of R’s built-in tooling for package checking and installation. The files you should .Rbuildignore fall into two broad, semi-overlapping classes: Files that help you generate package contents programmatically. Examples: Using README.Rmd to generate an informative and current README.md (Section 18.1). Storing .R scripts to create and update internal or exported data (Section 7.1.1). Files that drive package development, checking, and documentation, outside of CRAN’s purview. Examples: Files relating to the RStudio IDE (Section 4.2). Using the pkgdown package to generate a website (Chapter 19). Configuration files related to continuous integration/deployment (Section 20.2).

Here is a non-exhaustive list of typical entries in the .Rbuildignore file for a package in the tidyverse: ^.*\.Rproj$ # Designates the directory as an RStudio Project ^\.Rproj\.user$ # Used by RStudio for temporary files ^README\.Rmd$ # An Rmd file used to generate README.md ^LICENSE\.md$ # Full text of the license ^cran-comments\.md$ # Comments for CRAN submission ^data-raw$ # Code used to create data included in the package ^pkgdown$ # Resources used for the package website ^_pkgdown\.yml$ # Configuration info for the package website ^\.github$ # GitHub Actions workflows

If you want to distribute your package to an R user who doesn’t have package development tools, you’ll need to provide a binary package. The primary maker and distributor of binary packages is CRAN, not individual maintainers. But even if you delegate the responsibility of distributing your package to CRAN, it’s still important for a maintainer to understand the nature of a binary package.

Binary packages for macOS are stored as .tgz, whereas Windows binary packages end in .zip. If you need to make a binary package, use devtools::build(binary = TRUE) on the relevant operating system. Under the hood, this calls pkgbuild::build(binary = TRUE) and, ultimately, R CMD INSTALL --build, which is described further in the Building binary packages section of Writing R Extensions. If you choose to release your package on CRAN (Chapter 22), you submit your package in bundled form, then CRAN creates and distributes the package binaries.

An installed package is a binary package that’s been decompressed into a package library (described in Section 3.7). Figure 3.2 illustrates the many ways a package can be installed, along with a few other functions for converting a package from one state to another. This diagram is complicated! In an ideal world, installing a package would involve stringing together a set of simple steps: source -> bundle, bundle -> binary, binary -> installed. In the real world, it’s not this simple because there are often (faster) shortcuts available.