GitHub - r-lib/usethis: Set up commonly used 📦 components (original) (raw)

usethis

usethis is a workflow package: it automates repetitive tasks that arise during project setup and development, both for R packages and non-package projects.

Installation

Install the released version of usethis from CRAN:

install.packages("usethis")

Or install the development version from GitHub with:

install.packages("pak")

pak::pak("r-lib/usethis")

Usage

Most use_*() functions operate on the active project: literally, a directory on your computer. If you’ve just used usethis to create a new package or project, that will be the active project. Otherwise, usethis verifies that current working directory is or is below a valid project directory and that becomes the active project. Use proj_get() orproj_sitrep() to manually query the project and read more in the docs.

A few usethis functions have no strong connections to projects and will expect you to provide a path.

usethis is quite chatty, explaining what it’s doing and assigning you tasks. ✔ indicates something usethis has done for you. ☐ indicates that you’ll need to do some work yourself.

Below is a quick look at how usethis can help to set up a package. But remember, many usethis functions are also applicable to analytical projects that are not packages.

library(usethis)

Create a new package -------------------------------------------------

path <- file.path(tempdir(), "mypkg") create_package(path) #> ✔ Creating '/tmp/RtmpPZsquk/mypkg/'. #> ✔ Setting active project to "/private/tmp/RtmpPZsquk/mypkg". #> ✔ Creating 'R/'. #> ✔ Writing 'DESCRIPTION'. #> Package: mypkg #> Title: What the Package Does (One Line, Title Case) #> Version: 0.0.0.9000 #> Authors@R (parsed): #> * First Last first.last@example.com [aut, cre] #> Description: What the package does (one paragraph). #> License: use_mit_license(), use_gpl3_license() or friends to pick a #> license #> Encoding: UTF-8 #> Roxygen: list(markdown = TRUE) #> RoxygenNote: 7.3.2 #> ✔ Writing 'NAMESPACE'. #> ✔ Setting active project to "".

only needed since this session isn't interactive

proj_activate(path) #> ✔ Setting active project to "/private/tmp/RtmpPZsquk/mypkg". #> ✔ Changing working directory to '/tmp/RtmpPZsquk/mypkg/'

Modify the description ----------------------------------------------

use_mit_license("My Name") #> ✔ Adding "MIT + file LICENSE" to 'License'. #> ✔ Writing 'LICENSE'. #> ✔ Writing 'LICENSE.md'. #> ✔ Adding "^LICENSE\.md$" to '.Rbuildignore'.

use_package("rmarkdown", "Suggests") #> ✔ Adding rmarkdown to 'Suggests' field in DESCRIPTION. #> ☐ Use requireNamespace("rmarkdown", quietly = TRUE) to test if rmarkdown is #> installed. #> ☐ Then directly refer to functions with rmarkdown::fun().

Set up other files -------------------------------------------------

use_readme_md() #> ✔ Writing 'README.md'. #> ☐ Update 'README.md' to include installation instructions.

use_news_md() #> ✔ Writing 'NEWS.md'.

use_test("my-test") #> ✔ Adding testthat to 'Suggests' field in DESCRIPTION. #> ✔ Adding "3" to 'Config/testthat/edition'. #> ✔ Creating 'tests/testthat/'. #> ✔ Writing 'tests/testthat.R'. #> ✔ Writing 'tests/testthat/test-my-test.R'. #> ☐ Edit 'tests/testthat/test-my-test.R'.

x <- 1 y <- 2 use_data(x, y) #> ✔ Adding R to 'Depends' field in DESCRIPTION. #> ✔ Creating 'data/'. #> ✔ Setting 'LazyData' to "true" in 'DESCRIPTION'. #> ✔ Saving "x" and "y" to "data/x.rda" and "data/y.rda". #> ☐ Document your data (see https://r-pkgs.org/data.html).

Use git ------------------------------------------------------------

use_git() #> ✔ Initialising Git repo. #> ✔ Adding ".Rproj.user", ".Rhistory", ".Rdata", ".httr-oauth", ".DS_Store", and #> ".quarto" to '.gitignore'.

Code of Conduct

Please note that the usethis project is released with a Contributor Code of Conduct. By contributing to this project, you agree to abide by its terms.