B Developing R packages
This appendix collects various notes and resources on developing R packages.
B.1 Basics
Having created various R projects, an R user may be tempted to become an R developer by wrapping up an R project into an R package. The main idea behind R packages is to make collections of R code available to other users.
As with all things R, the process of writing R packages is mostly learned by doing and will always remain a continuous journey, rather than a destination. Embarking on this journey requires acquiring some new terminology and skills, but is supported by helpful instructions and tools.
B.1.1 What are R packages?
Using R implies relying on vast amounts of R code that is structured and provided in the form of R packages. Whenever we run R, a set of core R packages — including base, datasets, graphics, stats, and utils — is being loaded and provides a common collection of data objects and functions. When we use existing functions to create new data objects or functions, developing a new R package provide a great way of bundling and sharing code with other R users.
B.1.2 Contents and structure
R packages contain collections of R code (data and functions) and auxiliary files (e.g., documentation and images) in one directory. Standard files include
-
DESCRIPTION
to define metadata and organize functions -
NAMESPACE
to list imported and exported objects
and the following subdirectories:
-
R/
for storing R scripts -
data/
for storing data files -
man/
for storing documentation files and images -
vignettes/
for storing articles on package use -
tests/
for storing code verification scripts
B.1.3 Rules and tools
R packages are governed by many rules and conventions (see CRAN’s guidelines on Writing R Extensions). For instance, any R object (e.g., all arguments of all functions) must be documented and the package must work without errors on various R systems.
Fortunately, other R developers have created many useful tools — mostly in the form of other R packages (e.g., devtools, roxygen2, usethis, etc.) — to facilitate R package development (see Resources below).
B.1.4 Private vs. published R packages
R packages come in many forms and dwell in many different locations.
Package habitats
R packages can be entirely private: Many users maintain collections of useful functions in the form of an R package that is only stored on their personal system. On the other end of the spectrum, The Comprehensive R Archive Network (CRAN) currently hosts over 21,000 published R packages on a network of servers around the world. The collection of packages hosted on CRAN (and the related Bioconductor site) comprise the official canon of the currently available R packages.
An intermediary option consists in creating an R package that is hosted on another server and hence can be downloaded and installed by those R users who have access to this server. Popular web platforms for hosting such semi-public packages are R-Forge and GitHub.com.
CRAN
Publishing a package on CRAN involves considerable effort, regular monitoring and occasional updates by a person identifying as the package’s maintainer. For instance, the package must run without errors or warnings on multiple R versions and software platforms (including Mac OS, Microsoft Windows, and various Unix systems). The main benefit of hosting a package on CRAN is that the package is easily made available to R users worldwide.
B.2 Resources
This section collects links to various resources for R package development.
B.2.1 Instructions
Many manuals and books provide comprehensive instructions on developing R packages:
The manuals on CRAN provide the official guidelines on Writing R Extensions
The best book on package development is R packages (Wickham, 2015) and its 2nd edition (Wickham & Bryan, in progress), freely available at https://r-pkgs.org/
The Posit cheatsheet on R package development:
![Cheatsheet on R package development from Posit cheatsheets.](images/cheat/dev_package.png)
Figure B.1: Cheatsheet on R package development from Posit cheatsheets.
B.2.2 Tools
Tools for package development include the following R packages:
The R package devtools (Wickham et al., 2022, see its online documentation)
-
Other R packages addressing package development topics include:
- usethis for automating package setup (Wickham, Bryan, et al., 2024)
- roxygen2 for function and package documentation (Wickham, Danenberg, et al., 2024)
- pkgbuild for building binary packages (Wickham, Hester, & Csárdi, 2024)
- testthat for writing and running tests (Wickham, 2024)
- hexSticker for creating hexagon logos (G. Yu, 2020)
B.2.3 Miscellaneous resources
Other useful resources on R package development include:
All R packages available on CRAN
The source code of many R packages is hosted on GitHub.com
R-Forge is another platform for developing of R packages and R-related software projects