devtools v2.0.2

0

Monthly downloads

0th

Percentile

Tools to Make Developing R Packages Easier

Collection of package development tools.

Readme

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

  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.

Functions in devtools

Name Description
build_vignettes Build package vignettes.
clean_vignettes Clean built vignettes.
dev_mode Activate and deactivate development mode.
is.package Is the object a package?
as.package Coerce input to a package.
lint Lint all source files in a package.
build Build package
release Release package to CRAN.
build_manual Create package pdf manual
bash Open bash shell in package directory.
check_rhub Run CRAN checks for package on R-hub
dev_packages Return a vector of names of packages loaded by devtools
check_win Build windows binary package.
install Install a local development package.
github_pat Retrieve GitHub personal access token.
devtest Return the path to one of the packages in the devtools test dir
release_checks Custom devtools release checks.
install_deps Install package dependencies if needed.
submit_cran Submit a package to CRAN.
system_check Run a system command and check if it succeeds.
has_tests Was devtools installed with tests?
run_examples Run all examples in a package.
r_env_vars Environment variables to set when calling R
save_all Save all documents in an active IDE session.
source_url Run a script through some protocols such as http, https, ftp, etc.
spell_check Spell checking
check_failures Parses R CMD check log file for ERRORs, WARNINGs and NOTEs
check_man Check documentation, as R CMD check does.
document Use roxygen to document a package.
reexports Objects exported from other packages
dr_devtools Diagnose potential devtools issues
load_all Load complete package.
loaded_packages Return a vector of names of attached packages
build_readme Build a Rmarkdown README for a package
missing_s3 Find missing s3 exports.
package_file Find file in a package.
system_output Run a system command and capture the output.
test Execute test_that tests in a package.
uninstall Uninstall a local development package.
wd Set working directory.
build_site Execute pkgdown build_site in a package
check_cran Deprecated Functions
devtools Package development tools for R.
dr_github Diagnose potential GitHub issues
git_checks Git checks.
reload Unload and reload package.
revdep Reverse dependency tools.
show_news Show package news
source_gist Run a script on gist
check Build and check a package, cleaning up automatically on success.
No Results!

Vignettes of devtools

Name
dependencies.Rmd
No Results!

Last month downloads

Details

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/devtools)](http://www.rdocumentation.org/packages/devtools)