Package Development

with devtools Cheat Sheet

The " DESCRIPTION file describes your work and sets

up how your package will work with other packages.

% You must have a DESCRIPTION file

the packages that yours relies on with
% Adddevtools::use_package()

Package Structure
A package is a convention for organizing files into
directories.

Adds a package to the Imports field (or Suggests

field (if second argument is "Suggests").

This sheet shows how to work with the 7 most common

parts of an R package:
# Package
" DESCRIPTION
$ R/
$ tests/
$ man/
$ vignettes/
$ data/
" NAMESPACE

Setup ( " DESCRIPTION)

Setup
Write code
Test
Document
Teach
Add data
Organize

The contents of a package can be stored on disk as a:

source - a directory with sub-directories (as above)
bundle - a single compressed file (.tar.gz)
binary - a single compressed file optimized for a specific
OS

CC0

MIT

GPL-2

No strings attached.

MIT license applies to

your code if re-shared.

GPL-2 license applies to your

code, and all code anyone
bundles with it, if re-shared.

Write code ( $ R/)

Test
tests/)
Setup
( "( $
DESCRIPTION)

All of the R code in your package goes in $ R/. A package

with just an R/ directory is still a very useful package.

Use
to store unit
tests thatyour
will inform
yousets
if
The$"tests/
DESCRIPTION
file describes
work and
your code
up how your package
willever
workbreaks.
with other packages.

a new package project with

% Create
devtools::create("path/to/name")

Create a template to develop into a package.

% Save your code in $ R/ as scripts (extension .R)

Workflow

CRAN

install.packages(type = "source")

CRAN

Internet

In memory

devtools::load_all()
Re-loads all saved files in $ R/ into memory.
Ctrl/Cmd + Shift + L (keyboard shortcut)
Saves all open files then calls load_all().

R CMD install

github

1. Edit your code.

2. Load your code with one of

devtools::install()
devtools::build()
devtools::install_github()
devtools::load_all()
Build & Reload (RStudio)
library()

Installed

Binary

Bundle

Source

Repository

Or installed into an R library (loaded into memory during an

R session) or archived online in a repository. Use the
functions below to move between these states.

install.packages()

3. Experiment in the console.

4. Repeat.

Use consistent style with r-pkgs.had.co.nz/r.html#style

Click on a function and press F2 to open its definition
Search for a function with Ctrl + .

On disk

library memory

Package: mypackage
Title: Title of Package
Version: 0.1.0
Authors@R: person("Hadley", "Wickham", email =
"[email protected]", role = c("aut", "cre"))
Description: What the package does (one paragraph)
Depends: R (>= 3.1.0)
License: GPL-2
LazyData: true
Import packages that your package
Imports:
must have to work. R will install
dplyr (>= 0.4.0),
them when it installs your package.
ggvis (>= 0.2)
Suggest packages that are not very
Suggests:
essential to yours. Users can install
knitr (>= 0.1.0)
them manually, or not, as they like.

Visit r-pkgs.had.co.nz for more

devtools::add_build_ignore("file")
Adds file to .Rbuildignore, a list of files that will not be included
when package is built.
RStudio is a trademark of RStudio, Inc. CC BY RStudio [email protected] 844-448-1212 rstudio.com

Learn more at http://r-pkgs.had.co.nz devtools 1.6.1 Updated: 1/15

RStudio is a trademark of RStudio, Inc. All rights reserved
[email protected] 844-448-1212 rstudio.com

You amust
have
a DESCRIPTION
file testthat with
Add
tests/
directory
and import
%
% Adddevtools::use_testthat()
the packages that yours relies on with
Sets up package to use automated tests with
% devtools::use_package()
testthat
Adds a package to the Imports file (default) or
fieldcontext(),
(if second test(),
argument
"Suggests").
tests with
andisexpectations
% WriteSuggests
Suggests
your tests as .R files in tests/testthat/
% SaveImports
Import packages that your package
must have to work. R will install
them when it installs your package.

Workflow

Suggest packages that re not really

essential to yours. Users can install
them manually, or not, as they like.

Example test

Package:
1. Modify
yourmypackage
code or tests.
Title: Title of Package
2. Test
your code
with one of
Version:
0.1.0

context("Arithmetic")
Authors@R:
person("Hadley",
"Wickham", email =
devtools::test()
works",
{
"[email protected]", role test_that("Math
= c("aut", "cre",
"cst"))
Runs
all
tests
saved
in
expect_equal(1
+
1,
2)
Description: What the package does (one paragraph)
$ tests/.
expect_equal(1 + 2, 3)
Depends:
R (>= 3.1.0)
expect_equal(1 + 3, 4)
License:
GPL-2
Ctrl/Cmd + Shift + T
})
LazyData: true
(keyboard shortcut)
Imports:
Repeat
until (>=
all tests
pass
dplyr
0.4.0),
ggvis (>= 0.2)
expect_equal()
Suggests: is equal within small numerical tolerance?
knitr (>=
0.1.0)
expect_identical()
is exactly
equal?

3.

expect_match()

matches specified string or regular expression?

expect_output()

prints specified output?

expect_message()

displays specified message?

expect_warning()

displays specified warning?

expect_error()

throws specified error?

expect_is()

output inherits from certain class?

expect_false()

returns FALSE?

expect_true()

returns TRUE?
Learn more at http://r-pkgs.had.co.nz devtools 1.6.1 Updated: 1/15

Add data ( $ data/)

Document ( $ man/)
$ man/ contains the documentation for your functions, the help pages in your package.

%
%
%

Use roxygen comments to document each

function beside its definition
Document the name of each exported data set
Include helpful examples for each function

Workflow

1. Add roxygen comments in your .R files

2. Convert roxygen comments into
documentation with one of

The roxygen package

roxygen lets you write documentation inline in your .R files
with a shorthand syntax.
Add roxygen documentation as comment lines that begin
with #.
Place comment lines directly above the code that defines
the object documented.
Place a roxygen @ tag (right) after # to supply a specific
section of documentation.
Untagged lines will be used to generate a title, description,
and details section (in that order)

devtools::document()
Converts roxygen comments to .Rd files
and places them in $ man/. Also
assembles NAMESPACE.

#' Add together two numbers.

#'
#' @param x A number.
#' @param y A number.
#' @return The sum of \code{x} and \code{y}.
#' @examples
#' add(1, 1)
#' @export
add <- function(x, y) {
x + y
}

Ctrl/Cmd + Shift + D (Keyboard Shortcut)

3. Open help pages with ? to preview

documentation

4. Repeat
.Rd formatting tags
\emph{}
\strong{}
\code{}
\pkg{}

\code{\link{}}
\link{}
\link[package]{}
\linkS4class{}

\dontrun{}
\dontshow{}
\donttest{}

\email{}
\href{}
\url{}

\deqn{}
\eqn{}

\tabular{lcr}
\tab
\cr

@aliases
@concepts
@describeIn
@examples
@export
@family

@inheritParams
@keywords
@param
@rdname
@return
@section

@seealso
@format
@source
@include
@slot
@field

$ vignettes/ holds documents that teach your users how

to solve real problems with your tools.

%
%

Create a $ vignettes/ directory and a template vignette with

devtools::use_vignette()
Adds template vignette as vignettes/my-vignette.Rmd.
Append YAML headers to your vignettes (like right)
Write the body of your vignettes in R Markdown
(rmarkdown.rstudio.com)

RStudio is a trademark of RStudio, Inc. CC BY RStudio [email protected] 844-448-1212 rstudio.com

--title: "Vignette Title"

author: "Vignette Author"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Vignette Title}
%\VignetteEngine{knitr::rmarkdown}
\usepackage[utf8]{inputenc}
---

Store data in one of data/, R/Sysdata.rda, inst/

extdata

%
% Always use LazyData: true in your DESCRIPTION file.
% Save data as .Rdata files (suggested)
devtools::use_data()
Adds a data object to data/
(R/Sysdata.rda if internal = TRUE)
devtools::use_data_raw()
Adds an R Script used to clean a data set to dataraw/. Includes data-raw/ on .Rbuildignore.
Store data in
data/ to make data available to package users
R/sysdata.rda to keep data internal for use by your
functions.
inst/extdata to make raw data available for loading and
parsing examples. Access this data with system.file()

Organize ( " NAMESPACE)

Common roxygen tags

Teach ( $ vignettes/)

The $ data/ directory allows you to include data with

your package.

The " NAMESPACE file helps you make your package

self-contained: it wont interfere with other packages,
and other packages wont interfere with it.
data
S4
RC

%
%

Export functions for users by placing @export in their

roxygen comments
Import objects from other packages with
package::object (recommended) or @import,
@importFrom, @importClassesFrom,
@importMethodsFrom (not always recommended)

Workflow

1. Modify your code or tests.

2. Document your package (devtools::document())
3. Check NAMESPACE
4. Repeat until NAMESPACE is correct

Submit your package

r-pkgs.had.co.nz/release.html

Learn more at http://r-pkgs.had.co.nz devtools 1.6.1 Updated: 1/15