devtools v1.13.2
Monthly downloads
Tools to Make Developing R Packages Easier
Collection of package development tools.
Readme
devtools
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:
Install the release version of
devtools
from CRAN withinstall.packages("devtools")
.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).
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 inR/
, compiled shared objects insrc/
and data files indata/
. During development you usually want to access all functions soload_all()
ignores the packageNAMESPACE
.load_all()
will automatically create aDESCRIPTION
if needed.document()
updates documentation, file collation andNAMESPACE
.test()
reloads your code, then runs alltestthat
tests.
Building and installing:
install()
reinstalls the package, detaches the currently loaded version then reloads the new version withlibrary()
. Reloading a package is not guaranteed to work: see the documentation tounload()
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 andinstall_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 ofR CMD check
.check_man()
runs most of the documentation checking components ofR 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 emailsdevtools.desc.author
: your R author string, in the form of"Hadley Wickham <h.wickham@gmail.com> [aut, cre]"
. Used when creating defaultDESCRIPTION
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. | |
compiler_flags | Default compiler flags used by devtools. | |
create | Creates a new package, following all devtools package conventions. | |
check_failures | Parses R CMD check log file for ERRORs, WARNINGs and NOTEs | |
check_man | Check documentation, as R CMD check does. | |
clean_dll | Remove compiled objects from /src/ directory | |
clean_source | Sources an R file in a clean environment. | |
dev_help | Read the in-development help for a package loaded with devtools. | |
dev_meta | Return devtools metadata environment | |
devtest | Return the path to one of the packages in the devtools test dir | |
in_dir | Deprecated Functions | |
dr_devtools | Diagnose potential devtools issues | |
dr_github | Diagnose potential GitHub issues | |
eval_clean | Evaluate code in a clean R session. | |
find_topic | Find the rd file that documents a topic. | |
check_cran | Check a package from CRAN. | |
check_dep_version | Check that the version of an imported package satisfies the requirements | |
dev_mode | Activate and deactivate development mode. | |
imports_env | Return imports environment for a package | |
infrastructure | Add useful infrastructure to a package. | |
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 | |
run_examples | Run all examples in a package. | |
run_pkg_hook | Run user and package hooks. | |
dev_packages | Return a vector of names of packages loaded by devtools | |
has_tests | Was devtools installed with tests? | |
help | Drop-in replacements for help and ? functions | |
inst | Get the installation path of a package | |
install_cran | Attempts to install a package from CRAN. | |
install_deps | Install package dependencies if needed. | |
is.package | Is the object a package? | |
lint | Lint all source files in a package. | |
clean_vignettes | Clean built vignettes. | |
compile_dll | Compile a .dll/.so from source. | |
git_checks | Git checks. | |
github_pat | Retrieve Github personal access token. | |
install | Install a local development package. | |
load_all | Load complete package. | |
load_code | Load R code. | |
on_path | Test if an object is on the path. | |
pkg_env | Return package environment | |
r_env_vars | Environment variables to set when calling R | |
system_check | Run a system command and check if it succeeds. | |
system_output | Run a system command and capture the output. | |
github_pull | GitHub references | |
has_devel | Check if you have a development environment installed. | |
install_local | Install a package from a local file | |
install_svn | Install a package from a SVN repository | |
package_deps | Find all dependencies of a CRAN or dev package. | |
release | Release package to CRAN. | |
release_checks | Custom devtools release checks. | |
show_news | Show package news | |
install_url | Install a package from a url | |
install_version | Install specified version of a CRAN package. | |
parse_ns_file | Parses the NAMESPACE file for a package | |
path | Get/set the PATH variable. | |
unload | Unload a package | |
update_packages | Update packages that are missing or out-of-date. | |
use_package | Use specified package. | |
use_readme_rmd | Create README files. | |
source_gist | Run a script on gist | |
missing_s3 | Find missing s3 exports. | |
ns_env | Return the namespace environment for a package. | |
reload | Unload and reload package. | |
revdep | Reverse dependency tools. | |
build_win | Build windows binary package. | |
check | Build and check a package, cleaning up automatically on success. | |
create_description | Create a default DESCRIPTION file for a package. | |
dev_example | Run a examples for an in-development function. | |
submit_cran | Submit a package to CRAN. | |
system.file | Replacement version of system.file | |
use_build_ignore | Add a file to .Rbuildignore | |
use_data | Use data in a package. | |
use_data_raw | Use data-raw to compute package datasets. | |
use_git | Initialise a git repository. | |
devtools | Package development tools for R. | |
document | Use roxygen to document a package. | |
install_bioc | Install a package from a Bioconductor repository | |
install_bitbucket | Install a package directly from bitbucket | |
load_data | Load data. | |
load_dll | Load a compiled DLL | |
package_file | Find file in a package. | |
parse_deps | Parse package dependency strings. | |
session_info | Print session information | |
setup_rtools | Find rtools. | |
test | Execute all test_that tests in a package. | |
revdep_check_save_summary | Run R CMD check on all downstream dependencies. | |
revdep_email | Experimental email notification system. | |
source_url | Run a script through some protocols such as http, https, ftp, etc. | |
spell_check | Spell checking | |
use_git_hook | Add a git hook. | |
uninstall | Uninstall a local development package. | |
use_news_md | Use NEWS.md | |
wd | Set working directory. | |
with_debug | Temporarily set debugging compilation flags. | |
use_github | Connect a local repo with GitHub. | |
use_github_links | Add GitHub links to DESCRIPTION. | |
No Results! |
Vignettes of devtools
Name | ||
dependencies.Rmd | ||
No Results! |
Last month downloads
Details
Encoding | UTF-8 |
URL | https://github.com/hadley/devtools |
BugReports | https://github.com/hadley/devtools/issues |
License | GPL (>= 2) |
VignetteBuilder | knitr |
RoxygenNote | 6.0.1 |
NeedsCompilation | no |
Packaged | 2017-06-02 17:26:24 UTC; jhester |
Repository | CRAN |
Date/Publication | 2017-06-02 19:11:03 UTC |
suggests | BiocInstaller , bitops , covr , crayon , curl (>= 0.9) , evaluate , gmailr (> 0.7.0) , hunspell (>= 2.0) , knitr , lintr (>= 0.2.1) , MASS , Rcpp (>= 0.10.0) , rmarkdown , roxygen2 (>= 5.0.0) , rversions , testthat (>= 1.0.2) |
imports | digest , git2r (>= 0.11.0) , httr (>= 0.4) , jsonlite , memoise (>= 1.0.0) , methods , rstudioapi (>= 0.2.0) , stats , tools , utils , whisker , withr |
depends | R (>= 3.0.2) |
Contributors | RStudio, Winston Chang, R Core team |
Include our badge in your README
[](http://www.rdocumentation.org/packages/devtools)