---
title: "Writing Packages"
date-meta: 2022-12-12
---

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](https://roxygen2.r-lib.org/) aware editing.

-   Integration with [devtools](https://devtools.r-lib.org/) package development functions.

-   Support for [Rcpp](http://dirk.eddelbuettel.com/code/rcpp.html) 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](https://r-pkgs.org/) provides a deeper overview of general R package development strategies.

::: {.callout-tip}

The [**Command Palette**](../ui/command-palette.html), accessed by <kbd>Ctrl+Shift+P</kbd>, can also execute `devtools`, `usethis`, or Package Development specific commands:

![](images/command-palette-pkgs.png){fig-alt="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()`](https://usethis.r-lib.org/reference/create_package.html).

-   In RStudio, do **File** \> **New Project** \> **New Directory** \> **R Package**. This ultimately calls [`usethis::create_package()`](https://usethis.r-lib.org/reference/create_package.html), 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:

-   [Writing R Extensions](https://rstudio.github.io/r-manuals/)

-   [R Packages (Hadley Wickham)](https://r-pkgs.org/)

### Software prerequisites

There are two main prerequisites for building R packages:

1.  GNU software development tools including a C/C++ compiler; and

2.  LaTeX for building R manuals and vignettes.

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

``` r
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](https://r-pkgs.org/Setup.html#setup-tools) 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**:

![](images/create-r-pkg.png){fig-alt="A screenshot of the New Project Wizard"}

::: callout-tip

## 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:

1.  Create a new [RStudio Project](../code/projects.html) associated with the package's directory.

2.  If the package `DESCRIPTION` file is located either in the project's root directory or at `pkg/DESCRIPTION`, then it will be automatically discovered.

3.  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:

![](images/build-reload-pkg.png){fig-alt="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:

1.  Unloads any existing version of the package (including shared libraries if necessary).

2.  Builds and installs the package using `R CMD INSTALL`.

3.  Restarts the underlying R session to ensure a clean environment for re-loading the package.

4.  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 <kbd>Ctrl+Shift+P</kbd> (<kbd>Cmd+Shift+P</kbd> 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:  

![](images/build-pane.png){fig-alt="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/>.
