We’re pleased to announce the release of usethis 1.0.0 on CRAN (now 1.1.0, following some small improvements discovered after release). usethis is designed to smooth package-development workflows by automating everything that can be automated. Many of the functions were previously part of devtools, but have been extracted out in their own package to give them more room to grow.
Get started by loading usethis and running
create_package(). For this blog post, I’m going to create a package in a temporary directory, but normally you’d create it somewhere safe!
library(usethis) # Create a new package ------------------------------------------------- tmp <- file.path(tempdir(), "mypkg") create_package(tmp) #> Changing active project to mypkg #> ✔ Creating 'R/' #> ✔ Creating 'man/' #> ✔ Writing 'DESCRIPTION' #> ✔ Writing 'NAMESPACE'
If you’re using RStudio, this will automatically open a new RStudio session. Generally, usethis is tightly integrated with RStudio but should work with other editors too. The fallbacks for non-RStudio editors aren’t as well tested, so please let us know if you encounter problems.
(If you find yourself using usethis a lot and don’t want to load it everytime, run
use_usethis() and follow the instructions.)
Notice that the output includes “Changing active project to mypkg”. usethis has the concept of an “active project” which is where all usethis functions will have effect. It is usually the working directory, but is changed automatically by the
create_ functions, and can be changed manually with
If you don’t want a package, use
create_project() to create a minimal RStudio project. usethis is gradually evolving towards supporting more general R “projects” but this is still a work in progress. Please let us know if you have ideas or discover a problem!
Code and tests
use_r() will create/edit a script file in
use_r("foo") #> ● Edit 'R/foo.R'
use_test("foo") will set up all the infrastructure you need for unit testing, and create/edit a test file in
use_test("foo") #> ✔ Adding 'testthat' to Suggests field in DESCRIPTION #> ✔ Creating 'tests/testthat/' #> ✔ Writing 'tests/testthat.R' #> ✔ Writing 'tests/testthat/test-foo.R' #> ● Edit 'tests/testthat/test-foo.R'
We recommend that you have paired test and source files. If you use RStudio, you can use
use_test() to create/edit the test file corresponding to the open source file, and
use_r() to create/edit to the source file corresponding to the open test file.
To declare that your project has some dependencies, use
use_package("ggplot2") #> ✔ Adding 'ggplot2' to Imports field in DESCRIPTION #> ● Refer to functions with `ggplot2::fun()` use_package("dplyr") #> ✔ Adding 'dplyr' to Imports field in DESCRIPTION #> ● Refer to functions with `dplyr::fun()`
Or if you want a dependency on a development version of a package, use
Take advantage of these helpers to document your package:
use_roxygen_md()sets up roxygen2 and enables markdown mode so you can use markdown in your roxygen2 comment blocks.
use_package_doc()creates a skeleton documentation file for the complete package, taking the advantage of the latest roxygen2 features to minimise duplication between the
DESCRIPTIONand the documentation.
README.Rmd: use this to describe what your package does and why people should care about it.
use_news_md()creates a basic
NEWS.mdfor you to record changes.
use_vignette("vignette-name")sets you up for success by configuring
DESCRIPTIONand creating a
You can also use usethis to easily create and/or edit important configuration files:
edit_r_profile()(R code run on start up),
edit_r_environ()(environment variables), and
edit_r_makevars()(default configuration for compiled code).
edit_rstudio_snippets(type)(edit language specific snippets).
Most functions have a
scope argument which can be either “user” or “project”. This lets you control the scope of your changes: either to the current project, or for all projects for the current user (the default).
Another set of functions lets you quickly jump to important websites:
These functions take a package name as the first argument; if not supplied they’ll use the current project.