devtools

The aim of devtools is to make package development easier by providing R functions that simplify and expedite common tasks. R Packages is a book based around this workflow.

Installation

# Install devtools from CRAN
install.packages("devtools")

# Or the development version from GitHub:
# install.packages("devtools")
devtools::install_github("r-lib/devtools")

Cheatsheet

Usage

All devtools functions accept a path as an argument, e.g. load_all("path/to/mypkg"). If you don't specify a path, devtools will look in the current working directory - this is recommended practice.

Frequent development tasks:

• load_all() simulates installing and reloading your package, loading R code in R/, compiled shared objects in src/ and data files in data/. During development you usually want to access all functions (even un-exported internal ones) so load_all() works as if all functions were exported in the package NAMESPACE.

• document() updates generated documentation in man/, file collation and NAMESPACE.

• test() reloads your code with load_all(), then runs all testthat tests.

• test_coverage() runs test coverage on your package with covr. This makes it easy to see what parts of your package could use more tests!

Building and installing:

• install() reinstalls the package, detaches the currently loaded version then reloads the new version with library(). Reloading a package is not guaranteed to work: see the documentation for unload() for caveats.

• build() builds a package file from package sources. You can use it to build a binary version of your package.

• install_* functions install an R package:

  • install_github() from GitHub
  • install_gitlab() from GitLab
  • install_bitbucket() from Bitbucket
  • install_url() from an arbitrary url
  • install_git() and install_svn() from an arbitrary git or SVN repository
  • install_local() from a local file on disk
  • install_version() from a specific version on CRAN

• update_packages() updates a package to the latest version. This works both on packages installed from CRAN as well as those installed from any of the install_* functions.

Check and release:

• check() updates the documentation, then builds and checks the package locally. check_win() checks a package using win-builder, and check_rhub() checks a package using r-hub. This allows you to easily check your package on all systems CRAN uses before submission.

• release() makes sure everything is ok with your package (including asking you a number of questions), then builds and uploads to CRAN.

Learning more

R package development can be intimidating, however there are now a number of valuable resources to help!

1. R Packages is a book that gives a comprehensive treatment of all common parts of package development and uses devtools throughout.

   • The first edition is available at http://r-pkgs.had.co.nz, but note that it has grown somewhat out of sync with the current version of devtools.
   • A second edition is under development and is evolving to reflect the current state of devtools. It is available at https://r-pkgs.org.
   • The Whole Game and Package structure chapters make great places to start.

2. RStudio community - package development is a great place to ask specific questions related to package development.

3. rOpenSci packages has extensive documentation on best practices for R packages looking to be contributed to rOpenSci, but also very useful general recommendations for package authors.

4. There are a number of fantastic blog posts on writing your first package, including

   • Writing an R package from scratch - Hilary Parker
   • How to develop good R packages - Maëlle Salmon
   • Making your first R package - Fong Chun Chan
   • Writing an R package from scratch - Tomas Westlake

5. Writing R Extensions is the exhaustive, canonical reference for writing R packages, maintained by the R core developers.

Conscious uncoupling

devtools started off as a lean-and-mean package to facilitate local package development, but over the years it accumulated more and more functionality. Currently devtools is undergoing a conscious uncoupling to split out functionality into smaller, more tightly focussed packages. This includes:

• testthat: Writing and running tests (i.e. test()).

• roxygen2: Function and package documentation (i.e. document()).

• remotes: Installing packages (i.e. install_github()).

• pkgbuild: Building binary packages (including checking if build tools are available) (i.e. build()).

• pkgload: Simulating package loading (i.e. load_all()).

• rcmdcheck: Running R CMD check and reporting the results (i.e. check()).

• revdepcheck: Running R CMD check on all reverse dependencies, and figuring out what's changed since the last CRAN release (i.e. revdep_check()).

• sessioninfo: R session info (i.e. session_info()).

• usethis: Automating package setup (i.e. use_test()).

Generally, you should not need to worry about these different packages, because devtools installs them all automatically. You will need to care, however, if you're filing a bug because reporting it at the correct place will lead to a speedier resolution.

Code of conduct

Please note that the devtools project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.