Writing Packages

R packages are an ideal way to package and distribute R code and data for re-use by others. RStudio includes a variety of tools that make developing R packages easier and more productive, including:

Build pane with package development commands and a view of build output and errors
Clean and Install command that rebuilds the package and reloads it in a fresh R session.
R documentation tools including previewing, spell-checking, and Roxygen aware editing.
Integration with devtools package development functions.
Support for Rcpp including syntax highlighting for C/C++ and gcc error navigation.

Getting started

The following documentation covers fundamental R package development workflows inside RStudio. The R packages book provides a deeper overview of general R package development strategies.

Tip

The Command Palette, accessed by Ctrl+Shift+P, can also execute devtools, usethis, or Package Development specific commands:

The Command Palette filtered down to package development specific commands.

Package creation

Once you’ve come up with a name, there are two ways to create the package.

Call usethis::create_package().
In RStudio, do File > New Project > New Directory > R Package. This ultimately calls usethis::create_package(), so really there’s just one way.

Package development basics

If you aren’t already familiar with the basics of R package development, the following links provide additional documentation and tutorials:

Software prerequisites

There are two main prerequisites for building R packages:

GNU software development tools including a C/C++ compiler; and
LaTeX for building R manuals and vignettes.

To easily build and document robust R packages, you will also need the following R packages:

install.packages(c("devtools", "roxygen2", "testthat", "knitr"))

If you don’t already have these tools installed on your system, please consult the “R Packages” chapter on R build toolchain for additional details on how to install these dependencies.

Creating a new package

To create a new package, use the Create Project command (available on the Projects menu and on the global toolbar) and select the New Directory option. Then on the following screen specify the project type as R Package:

A screenshot of the New Project Wizard

Using existing R scripts

If you have existing R scripts that you’d like to use as the basis for the new package, you can specify them here and they’ll be included in the new package.

Working with an existing package

To enable RStudio’s package development tools for an existing package do the following:

Create a new RStudio Project associated with the package’s directory.
If the package DESCRIPTION file is located either in the project’s root directory or at pkg/DESCRIPTION, then it will be automatically discovered.
Alternatively, navigate to Tools > Project Options > Build Tools, select “Package” as the project build tools type, and then specify the the subdirectory containing the package’s DESCRIPTION file.

Building a package

To build the completed package in RStudio, use the Build pane, which includes a variety of tools for building and testing packages. While iteratively developing a package in RStudio, you typically use the Install > Clean and Install command or call Clean and Install from the Command Palette to re-build the package and reinstall it in a fresh R session:

The build pane in RStudio, showing the output of a 'Clean and Install' command.

The Clean and Install command performs several steps in sequence to ensure a clean and correct result:

Unloads any existing version of the package (including shared libraries if necessary).
Builds and installs the package using R CMD INSTALL.
Restarts the underlying R session to ensure a clean environment for re-loading the package.
Reloads the package in the new R session by executing the library function.

You can also execute Clean and Install using the the Command Palette Ctrl+Shift+P (Cmd+Shift+P on Mac) or configure RStudio to automatically save open source files prior to rebuilding from the Tools > Global Options > Packages tab > Development tab > Save all files prior to building packages option.

The Build pane also includes buttons for:

The build pane in RStudio, displaying the buttons available.

Test - run tests for current R package
Check - run R CMD Check to test for package code or documentation problems
Load All - runs devtools::load_all()
Build Source Package - build a source package
Build Binary Package - build a binary package
Configure Build Tools - Opens Project Options > Build Tools

Learning more

Once you’ve built a basic package with RStudio you’ll want to learn about the tools that can be used to test, document, and prepare packages for distribution. Please consult the “R Packages” book at https://r-pkgs.org/.