Devtools

Painless package development for R

Devtools makes package development a breeze: it works with R's existing conventions for code structure, adding efficient tools to support the cycle of package development. With devtools, developing a package becomes so easy that it will be your default layout whenever you're writing a significant amount of code.

Getting started

Install devtools by running

install.packages("devtools")

If you’ve never developed a package before, start by reading about package basics. Otherwise, start by reading about the package development cycle.

If you’re developing a package that uses binary code (e.g. C or C++) you’ll also need a set of development tools. On Windows, download and install Rtools, and devtools takes care of the rest. On Mac, install the Xcode command line tools. On Linux, install the R develpoment package, usually called r-devel or r-base-dev.

Devtools provides tools to:

  • facilitate the package development process
  • help release your package into the wild
  • make it easy to install R packages that are not on CRAN

Package development

When developing a package, you perform four main tasks:

  1. Writing code
  2. Loading it into R
  3. Testing that it works (either formally or informally)
  4. Documenting what you’ve done

Devtools doesn’t write code for you, but it does provide a function to make each of the other steps easier:

  1. load_all("path/to/package/") sources all R code in R/, removes and reloads S4 class and method definitions, compiles and attaches any C, C++ or fortran code in src/, loads data files in data/, attaches denpendent packages and respects the NAMESPACE imports, and optionally, the export. In short, load_all() simulates restarting R, then re-installing and re-loading your package, but in much less time.

  2. test("path/to/package/") runs the testthat unit tests found in the inst/test/ directory. Unit testing is a simple progression from the informal interactive testing you’re already doing: it allows you to re-run the same tests every time you change your code and clearly state what you expect the results to be. Learn more about unit testing.

  3. document("path/to/package/") converts inline roxygen document blocks to R’s standard Rd files in the man/ directory. Learn more about documenting your code

Releasing your package to CRAN

R provides an automated test suite for packages in the form of R CMD check. Devtools makes this easy to acccess through check("path/to/package/"). If you want to release your package to CRAN, then you must pass check() without any errors or warnings (and preferrably no messages). Even if you’re not interested in submitting to CRAN, it’s still a good idea to run check: many of the tests pick up poor development practices or outright programming errors.

Because check() is a long process, devtools allows you to run individual components, like check_docs() or run_examples(). You can also use build_win() to use the Windows builder provided by the R-core development team to test your package on Windows.

Installing packages

If you’re developing a package, you probably need some way to make it available to your users. Devtools provides a suite of functions (install_github(), install_bitbucket(), install_gitorious(), and install_git()) to make it easy to install your package from wherever it lives on the internet.