Package Development : : CHEATSHEET

Package Structure Workflow

A package is a convention for organizing files into directories.
This cheat sheet shows how to work with the 7 most common
parts of an R package: Edit code Edit tests Edit roxygen  DESCRIPTION
The  DESCRIPTION file describes your work, sets up how your
package-name Set up metadata and organize package will work with other packages, and applies a license.
package functions
 DESCRIPTION
 NAMESPACE Write R code for your package ☑ Pick a license with use_mit_license(), use_gpl3_license(),
R/ use_proprietary_license().
load_all() test() document()
tests/ Verify your code is correct
man/ ☑ Add packages that you need with use_package().
vignettes/ Document your code and write
data/
tutorials and how-tos Run code ?fun
Include datasets in your package Import packages that your Suggest packages that
check() package requires to work. R developers of your package
will install them when it installs need. Users can install or not,
There are multiple packages useful to package development, your package. as they like.
including usethis which handily automates many of the more
repetitive tasks. Install and load devtools, which wraps together git commit use_package(x, type = "imports") use_package(x, type = "suggests")
several of these packages to access everything in one step. git push

Getting Started • load_all() (Ctrl/Cmd + Shi + L) — Load code

 NAMESPACE
Once per machine: • document() (Ctrl/Cmd + Shi + D) — Rebuild docs and NAMESPACE The  NAMESPACE file helps you make your package self-
• test() (Ctrl/Cmd + Shi + T) — Run tests contained: it won’t interfere with other packages, and other
• Get set up with use_devtools() so devtools is always loaded in
packages won’t interfere with it.
interactive R sessions • check() (Ctrl/Cmd + Shi + E) — Check complete package

if (interactive()) {
require("devtools", quietly = TRUE)
☑ Export functions for users by placing @export in their
# automatically attaches usethis R/ roxygen comments.
}
☑ Use objects from other packages with package::object or
All of the R code in your package goes in R/. A package with just @importFrom package object (recommended) or
• create_github_token() — Set up GitHub credentials an R/ directory is still a very useful package. @import package (use with caution).
• git_vaccinate() — Ignores common special files
☑ Call document() to generate NAMESPACE and load_all() to
☑ Create a new package project with reload.
Once per package: create_package("path/to/name").
• create_package() — Create a project with package sca olding
• use_git() — Activate git ☑ Create R files with use_r("file-name").
DESCRIPTION NAMESPACE
• use_github() — Connect to GitHub
Makes packages available Makes function available
• use_github_action() — Set up automated package checks • Follow the tidyverse style guide at style.tidyverse.org
Mandatory Optional (can use :: instead)
• Click on a function and press F2 to go to its definition
Having problems with git? Get a situation report with git_sitrep(). use_package() use_import_from()
• Find a function or file with Ctrl + .

CC BY SA Posit So ware, PBC • [email protected] • posit.co • Learn more at r-pkgs.org • HTML cheatsheets at pos.it/cheatsheets • devtools 2.4.5 • usethis 2.2.2 • testthat 3.2.1.1 • roxygen2 7.3.1 • Updated: 2024-05
folder
folder
folder
folder
folder
folder
ft
ft
ft
ft
ft
folder
ff
 man/ ROXYGEN2 data/
The documentation will become the help pages in your package. The roxygen2 package lets you write documentation
inline in your .R files with shorthand syntax. ☑ Record how a data set was prepared as an R script and save
☑ Document each function with a roxygen block above its
• Add roxygen documentation as comments beginning with #'. that script to data-raw/ with use_data_raw().
definition in R/. In RStudio, Code > Insert Roxygen Skeleton
helps (Ctrl/Cmd + Alt + Shi + R). • Place a roxygen @ tag (right) a er #' to supply a specific section ☑ Save a prepared data object to data/ with use_data().
of documentation.
☑ Document each dataset with roxygen block above the name
• Untagged paragraphs will be used to generate a title,
of the dataset in quotes.
description, and details section (in that order).
☑ Document the package with use_package_doc(). Package States
#' Add together two numbers
☑ Build documentation in man/ from Roxygen blocks with #' The contents of a package can be stored on disk as a:
document(). #' @param x A number.
• source - a directory with sub-directories (as shown in
#' @param y A number.
#' @returns The sum of `x` and `y`.
Package structure)

vignettes/ #' @export

#' @examples
• bundle - a single compressed file (.tar.gz)
• binary - a single compressed file optimized for a specific OS
#' add(1, 1)
☑ Create a vignette that is included with your package with add <- function(x, y) { Packages exist in those states locally or remotely, e.g. on CRAN or
use_vignette().
x + y on GitHub.
}
From those states, a package can be installed into an R library and
☑ Create an article that only appears on the website with then loaded into memory for use during an R session.
use_article(). COMMON ROXYGEN TAGS
Use the functions below to move between these states.
☑ Write the body of your vignettes in R Markdown. @description @family @returns
@examples @inheritParams @seealso

Repository

In memory
Installed
@examplesIf @param
Websites with pkgdown

Bundle
Source

Binary
@export @rdname

☑ Use GitHub and use_pkgdown_github_pages()

to set up pkgdown and configures an automated workflow
 README.Rmd + NEWS.md Internet On disk Library Memory

library()
using GitHub Actions and Pages.
☑ Create a README and NEWS markdown files with install.packages() CRAN
☑ If you're not using GitHub, call use_pkgdown() to configure
use_readme_rmd() and use_news_md().
pkgdown. Then build locally with pkgdown::build_site(). install.packages(type = "source") CRAN

install_github() GitHub

install()
tests/ Expect statement Tests build()

expect_equal() Is equal? (within numerical tolerance) build(binary = TRUE)

☑ Set up test infrastructure with use_testthat().
expect_error() Throws specified error? load_all()
☑ Create a test file with use_test().
expect_snapshot() Output is unchanged?
☑ Write tests with test_that() and expect_().

☑ Run all tests with test() and run tests for current file Visit r-pkgs.org to learn
test_that("Math works", {
with test_active_file(). expect_equal(1 + 1, 2)
much more about
expect_equal(1 + 2, 3) writing and publishing
☑ See coverage of all files with test_coverage() and expect_equal(1 + 3, 4) packages for R.
see coverage of current file with test_coverage_active_file(). })

CC BY SA Posit So ware, PBC • [email protected] • posit.co • Learn more at r-pkgs.org • HTML cheatsheets at pos.it/cheatsheets • devtools 2.4.5 • usethis 2.2.2 • testthat 3.2.1.1 • roxygen2 7.3.1 • Updated: 2024-05
folder
folder
folder
folder
ft
folder
folder
ft
ft
folder