devtools v1.13.3

0

Monthly downloads

0th

Percentile

by Hadley Wickham

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 common tasks.

An R package is actually quite simple. A package is a template or set of conventions that structures your code. This not only makes sharing code easy, it reduces the time and effort required to complete you project: following a template removes the need to have to think about how to organize things and paves the way for the creation of standardised tools that can further accelerate your progress.

While package development in R can feel intimidating, devtools does every thing it can to make it less so. In fact, devtools comes with a small guarantee: if you get an angry e-mail from an R-core member because of a bug in devtools, forward me the email and your address and I'll mail you a card with a handwritten apology.

devtools is opinionated about package development. It requires that you use roxygen2 for documentation and testthat for testing. Not everyone would agree with this approach, and they are by no means perfect. But they have evolved out of the experience of writing over 30 R packages.

I'm always happy to hear about what doesn't work for you and where devtools gets in your way. Either send an email to the rdevtools mailing list or file an issue at the GitHub repository.

Updating to the latest version of devtools

You can track (and contribute to) the development of devtools at https://github.com/hadley/devtools. To install it:

  1. Install the release version of devtools from CRAN with install.packages("devtools").

  2. Make sure you have a working development environment.

    • Windows: Install Rtools.
    • Mac: Install Xcode from the Mac App Store.
    • Linux: Install a compiler and various development libraries (details vary across different flavors of Linux).
  3. Install the development version of devtools.

    devtools::install_github("hadley/devtools")
    

Package development tools

All devtools functions accept a path as an argument, e.g. load_all("path/to/path/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 so load_all() ignores the package NAMESPACE. load_all() will automatically create a DESCRIPTION if needed.

  • document() updates documentation, file collation and NAMESPACE.

  • test() reloads your code, then runs all testthat 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 to 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_bitbucket() from bitbucket,
    • install_url() from an arbitrary url and
    • install_local() from a local file on disk.
    • install_version() installs a specified version from cran.

Check and release:

  • check() updates the documentation, then builds and checks the package. build_win() builds a package using win-builder, allowing you to easily check your package on windows.

  • run_examples() will run all examples to make sure they work. This is useful because example checking is the last step of R CMD check.

  • check_man() runs most of the documentation checking components of R CMD check

  • release() makes sure everything is ok with your package (including asking you a number of questions), then builds and uploads to CRAN. It also drafts an email to let the CRAN maintainers know that you've uploaded a new package.

Other tips

I recommend adding the following code to your .Rprofile:

.First <- function() {
  options(
    repos = c(CRAN = "https://cran.rstudio.com/"),
    browserNLdisabled = TRUE,
    deparse.max.lines = 2)
}

if (interactive()) {
  suppressMessages(require(devtools))
}

See the complete list in ?devtools

This will set up R to:

  • always install packages from the RStudio CRAN mirror
  • ignore newlines when browse()ing
  • give minimal output from traceback()
  • automatically load devtools in interactive sessions

There are also a number of options you might want to set (in .Rprofile) to customise the default behaviour when creating packages and drafting emails:

  • devtools.name: your name, used to sign emails
  • devtools.desc.author: your R author string, in the form of "Hadley Wickham <h.wickham@gmail.com> [aut, cre]". Used when creating default DESCRIPTION files.
  • devtools.desc.license: a default license used when creating new packages

Code of conduct

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

Functions in devtools

Name Description
bash Open bash shell in package directory.
build Build package.
build_github_devtools Build the development version of devtools from GitHub.
build_vignettes Build package vignettes.
RCMD Run R CMD xxx from within R
as.package Coerce input to a package.
build_win Build windows binary package.
check Build and check a package, cleaning up automatically on success.
check_cran Check a package from CRAN.
check_dep_version Check that the version of an imported package satisfies the requirements
compiler_flags Default compiler flags used by devtools.
create Creates a new package, following all devtools package conventions.
devtest Return the path to one of the packages in the devtools test dir
clean_vignettes Clean built vignettes.
compile_dll Compile a .dll/.so from source.
devtools Package development tools for R.
document Use roxygen to document a package.
create_description Create a default DESCRIPTION file for a package.
dev_example Run a examples for an in-development function.
dev_mode Activate and deactivate development mode.
dev_packages Return a vector of names of packages loaded by devtools
imports_env Return imports environment for a package
infrastructure Add useful infrastructure to a package.
install_local Install a package from a local file
install_svn Install a package from a SVN repository
clean_dll Remove compiled objects from /src/ directory
clean_source Sources an R file in a clean environment.
dr_devtools Diagnose potential devtools issues
dr_github Diagnose potential GitHub issues
install_url Install a package from a url
install_version Install specified version of a CRAN package.
package_file Find file in a package.
parse_deps Parse package dependency strings.
check_failures Parses R CMD check log file for ERRORs, WARNINGs and NOTEs
check_man Check documentation, as R CMD check does.
dev_help Read the in-development help for a package loaded with devtools.
dev_meta Return devtools metadata environment
git_checks Git checks.
eval_clean Evaluate code in a clean R session.
find_topic Find the rd file that documents a topic.
install_bioc Install a package from a Bioconductor repository
install_bitbucket Install a package directly from bitbucket
load_all Load complete package.
load_code Load R code.
parse_ns_file Parses the NAMESPACE file for a package
path Get/set the PATH variable.
github_pull GitHub references
has_devel Check if you have a development environment installed.
install_git Install a package from a git repository
install_github Attempts to install a package directly from GitHub.
load_imports Load all of the imports for a package
loaded_packages Return a vector of names of attached packages
pkg_env Return package environment
r_env_vars Environment variables to set when calling R
revdep_check_save_summary Run R CMD check on all downstream dependencies.
revdep_email Experimental email notification system.
test Execute all test_that tests in a package.
uninstall Uninstall a local development package.
release Release package to CRAN.
release_checks Custom devtools release checks.
submit_cran Submit a package to CRAN.
system.file Replacement version of system.file
use_data_raw Use data-raw to compute package datasets.
use_git Initialise a git repository.
github_pat Retrieve Github personal access token.
install_cran Attempts to install a package from CRAN.
install_deps Install package dependencies if needed.
load_data Load data.
in_dir Deprecated Functions
has_tests Was devtools installed with tests?
help Drop-in replacements for help and ? functions
inst Get the installation path of a package
install Install a local development package.
is.package Is the object a package?
lint Lint all source files in a package.
missing_s3 Find missing s3 exports.
unload Unload a package
update_packages Update packages that are missing or out-of-date.
wd Set working directory.
ns_env Return the namespace environment for a package.
run_examples Run all examples in a package.
run_pkg_hook Run user and package hooks.
source_url Run a script through some protocols such as http, https, ftp, etc.
load_dll Load a compiled DLL
on_path Test if an object is on the path.
package_deps Find all dependencies of a CRAN or dev package.
session_info Print session information
use_git_hook Add a git hook.
use_github Connect a local repo with GitHub.
use_package Use specified package.
use_readme_rmd Create README files.
spell_check Spell checking
setup_rtools Find rtools.
system_check Run a system command and check if it succeeds.
system_output Run a system command and capture the output.
use_github_links Add GitHub links to DESCRIPTION.
use_news_md Use NEWS.md
with_debug Temporarily set debugging compilation flags.
reload Unload and reload package.
revdep Reverse dependency tools.
show_news Show package news
source_gist Run a script on gist
use_build_ignore Add a file to .Rbuildignore
use_data Use data in a package.
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)