You are on page 1of 2

Package Development Setup ( " DESCRIPTION)

The " DESCRIPTION file describes your work and sets


with devtools Cheat Sheet up how your package will work with other packages. Package: mypackage
Title: Title of Package

% You must have a DESCRIPTION file Version: 0.1.0


Authors@R: person("Hadley", "Wickham", email =

% Adddevtools::use_package()
"hadley@me.com", role = c("aut", "cre"))
Package Structure the packages that yours relies on with
Description: What the package does (one paragraph)
Depends: R (>= 3.1.0)
A package is a convention for organizing files into Adds a package to the Imports field (or Suggests License: GPL-2
directories. field (if second argument is "Suggests"). 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.
This sheet shows how to work with the 7 most common CC0 MIT GPL-2 ggvis (>= 0.2)
parts of an R package: No strings attached. MIT license applies to GPL-2 license applies to your Suggests: Suggest packages that are not very
your code if re-shared. code, and all code anyone essential to yours. Users can install
knitr (>= 0.1.0)
# Package bundles with it, if re-shared. them manually, or not, as they like.
" DESCRIPTION Setup
$ R/ Write code Write code ( $ R/) Test
Setup ( "( $ tests/)
DESCRIPTION)
$ tests/ Test
$ man/ Document All of the R code in your package goes in $ R/. A package Use
The$"tests/ to store unit
DESCRIPTION tests thatyour
file describes will inform yousets
work and if
$ vignettes/ Teach with just an R/ directory is still a very useful package. your code
up how your package willever
workbreaks.
with other packages.
$ data/ Add data
" NAMESPACE Organize
% Create a new package project with % You amust
Add have
tests/ a DESCRIPTION
% Adddevtools::use_testthat()
directory file testthat with
and import

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


source - a directory with sub-directories (as above)
devtools::create("path/to/name")
Create a template to develop into a package. % devtools::use_package()
the packages that yours relies on with
Sets up package to use automated tests with
testthat
Adds a package to the Imports file (default) or
bundle - a single compressed file (.tar.gz)
binary - a single compressed file optimized for a specific
% Save your code in $ R/ as scripts (extension .R) % WriteSuggests fieldcontext(),
tests with (if second test(),
argumentandisexpectations
"Suggests").

OS
Or installed into an R library (loaded into memory during an
Workflow % SaveImports
Import packages that your package
must have to work. R will install
Suggests
your tests as .R files in tests/testthat/
Suggest packages that re not really
essential to yours. Users can install
R session) or archived online in a repository. Use the
1. Edit your code. them when it installs your package. them manually, or not, as they like.
functions below to move between these states. 2. Load your code with one of Workflow Example test
devtools::load_all() 1. Modify yourmypackage
Package: code or tests.
Repository

In memory

Title: Title of Package


Installed

Re-loads all saved files in $ R/ into memory. 2. Test your code with one of context("Arithmetic")
Bundle

Version: 0.1.0
Source

Binary

devtools::test()
Authors@R: person("Hadley", "Wickham", email =
Ctrl/Cmd + Shift + L (keyboard shortcut) "hadley@me.com", role test_that("Math
= c("aut", "cre", works",
"cst")){
install.packages() CRAN Runs all tests saved in expect_equal(1 + 1, 2)
Saves all open files then calls load_all(). Description: What the package does (one paragraph)
$ tests/.
install.packages(type = "source") CRAN Depends: R (>= 3.1.0) expect_equal(1 + 2, 3)

3. Experiment in the console. Ctrl/Cmd + Shift + T


License: GPL-2 expect_equal(1 + 3, 4)
LazyData: true })
R CMD install 4. Repeat. (keyboard shortcut)
Imports:
3. Repeat until (>=
dplyr all tests pass
0.4.0),
devtools::install() Use consistent style with r-pkgs.had.co.nz/r.html#style ggvis (>= 0.2)
expect_equal()
Suggests: is equal within small numerical tolerance?
devtools::build() Click on a function and press F2 to open its definition
knitr (>=
expect_identical() 0.1.0)
is exactly equal?
devtools::install_github() github Search for a function with Ctrl + . expect_match() matches specified string or regular expression?
devtools::load_all() expect_output() prints specified output?
Build & Reload (RStudio) expect_message() displays specified message?
library()
Internet On disk

library memory
Visit r-pkgs.had.co.nz for more expect_warning()
expect_error()
displays specified warning?
throws specified error?
devtools::add_build_ignore("file") Learn more at http://r-pkgs.had.co.nz devtools 1.6.1 Updated: 1/15 expect_is() output inherits from certain class?
RStudio is a trademark of RStudio, Inc. All rights reserved
Adds file to .Rbuildignore, a list of files that will not be included expect_false() returns FALSE?
info@rstudio.com 844-448-1212 rstudio.com
when package is built. expect_true() returns TRUE?
RStudio is a trademark of RStudio, Inc. CC BY RStudio info@rstudio.com 844-448-1212 rstudio.com Learn more at http://r-pkgs.had.co.nz devtools 1.6.1 Updated: 1/15
Document ( $ man/) Add data ( $ data/)
$ man/ contains the documentation for your functions, the help pages in your package. The $ data/ directory allows you to include data with
your package.
% Use roxygen comments to document each
function beside its definition
The roxygen package
Store data in one of data/, R/Sysdata.rda, inst/
% Document the name of each exported data set
roxygen lets you write documentation inline in your .R files
with a shorthand syntax. % extdata

% Include helpful examples for each function Add roxygen documentation as comment lines that begin
with #.
% Always use LazyData: true in your DESCRIPTION file.
Workflow Place comment lines directly above the code that defines
the object documented.
% Save data as .Rdata files (suggested)
1. Add roxygen comments in your .R files
Place a roxygen @ tag (right) after # to supply a specific devtools::use_data()
2. Convert roxygen comments into documentation section of documentation. Adds a data object to data/
with one of (R/Sysdata.rda if internal = TRUE)
Untagged lines will be used to generate a title, description,
devtools::document() and details section (in that order)
devtools::use_data_raw()
Converts roxygen comments to .Rd files and Adds an R Script used to clean a data set to data-
places them in $ man/. Builds NAMESPACE. #' Add together two numbers.
#' raw/. Includes data-raw/ on .Rbuildignore.
Ctrl/Cmd + Shift + D (Keyboard Shortcut) #' @param x A number.
#' @param y A number. Store data in
3. Open help pages with ? to preview documentation #' @return The sum of \code{x} and \code{y}. data/ to make data available to package users
#' @examples R/sysdata.rda to keep data internal for use by your
4. Repeat #' add(1, 1) functions.
#' @export
inst/extdata to make raw data available for loading and
.Rd formatting tags \email{name@@foo.com} add <- function(x, y) {
x + y
parsing examples. Access this data with system.file()
\href{url}{display}
\emph{italic text} }
\url{url}
\strong{bold text} Organize ( " NAMESPACE)
\code{function(args)} \link[=dest]{display}
Common roxygen tags
The " NAMESPACE file helps you make your package
\pkg{package} \linkS4class{class} @aliases @inheritParams @seealso
self-contained: it wont interfere with other packages,
\code{\link{function}} @concepts @keywords @format and other packages wont interfere with it.
\dontrun{code} \code{\link[package]{function}} @describeIn @param @source data
\dontshow{code} Export functions for users by placing @export in their
\donttest{code} \tabular{lcr}{
@examples
@export
@rdname
@return
@include
@slot
% roxygen comments
left \tab centered \tab right \cr S4 Import objects from other packages with
\deqn{a + b (block)}
\eqn{a + b (inline)} }
cell \tab cell \tab cell \cr @family @section @field RC % package::object (recommended) or @import,
@importFrom, @importClassesFrom,
@importMethodsFrom (not always recommended)
Teach ( $ vignettes/)
$ vignettes/ holds documents that teach your users how
Workflow
to solve real problems with your tools. ---
title: "Vignette Title"
1. Modify your code or tests.
author: "Vignette Author" 2. Document your package (devtools::document())
% Create a $ vignettes/ directory and a template vignette with
devtools::use_vignette()
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette 3. Check NAMESPACE
Adds template vignette as vignettes/my-vignette.Rmd. vignette: >
%\VignetteIndexEntry{Vignette Title}
4. Repeat until NAMESPACE is correct
% Append YAML headers to your vignettes (like right)
Write the body of your vignettes in R Markdown
%\VignetteEngine{knitr::rmarkdown}
\usepackage[utf8]{inputenc}
Submit your package
% (rmarkdown.rstudio.com)
---
r-pkgs.had.co.nz/release.html
RStudio is a trademark of RStudio, Inc. CC BY RStudio info@rstudio.com 844-448-1212 rstudio.com Learn more at http://r-pkgs.had.co.nz devtools 1.6.1 Updated: 1/15