/devtools

Tools to make an R developer's life easier

Primary LanguageR

devtools

Build Status AppVeyor Build Status Coverage Status CRAN_Status_Badge

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 gives a comprehensive treatment of all common parts of package development and uses devtools throughout. The Package structure chapter is a great place to get started understanding the parts of a package and how they work together.

  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

  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.