intro.rmd

---
layout: default
title: Introduction
output: bookdown::html_chapter
---

# Introduction

## Why build a package?

In R, the fundamental unit of shareable code is the package. A package bundles together code, data, documentation and tests, and it's easy to share with others. Packages actually make your life easier because they're a set of conventions for how to structure your code. The first convention is a no-brainer:

* Put your R code in a directory called `R/`.

The second is a little bit more work:

* Describe what your package needs to work in a `DESCRIPTION` file
  If the package is to share, also describe what it does, who can use it 
  (the license) and who to contact if things go wrong.

These conventions are helpful because:

* They save you time --- you don't need to think about the best way to organise
  a project, you can just follow a template.

* Standardised conventions lead to standardised tools --- if you buy into
  the R's package conventions, you get many tools for free.

As Hilary Parker puts it in her [introduction to packages](http://hilaryparker.com/2014/04/29/writing-an-r-package-from-scratch/): "Seriously, it doesn't have to be about sharing your code (although that is an added benefit!). It is about saving yourself time."

A package doesn't need to be complicated. You can start with a minimal subset of useful features and slowly build up over time. While there are strict requirements if you want to publish a package to the world on CRAN (and many of those requirements are useful even for your own packages), most packages won't end up on CRAN. You can even use packages to structure your data analyses, as Robert M Flight discusses in a [series of blog posts](http://rmflight.github.io/posts/2014/07/analyses_as_packages.html). Packages are really easy to create and use once you have the right set of tools.

Anytime you create some reusable set of functions you should put it in a package. It's the easiest path because packages come with conventions: you don't need to figure them out for yourself. You'll start with just your R code in the `R/` directory, and over time you can flesh it out with documentation (in `man/`), vignettes (in `vignettes/`), compiled code (in `src/`), data sets (in `data/`), and tests (in `inst/tests`).

The most accurate resource for up-to-date details on package development is always the official [writing R extensions][r-ext] guide. However, it's rather hard to understand if you're not already familiar with the basics of packages. It's also exhaustive, covering every possible package component, rather than focussing on the most common and useful components as this package does. It's a useful resource once you've mastered the basics and need to check on more esoteric facts.

## Philosophy

This book espouses my philosophy of package development: is anything that can be automated, should be automated. You will do as little as possible by hand, instead relying on R functions to do as much work as possible. You should spend your time worrying about the specific details of your code, not fighting to get it in the right form.

This philosophy is realised primarily in the devtools package, which provides a suite of R functions to automate common development tasks. The goal of the devtools package is to make package development as painless as possible by encoding package building best practices in functions (so you don't have to remember, or even know about them), and by minimising the iteration time when you're developing a package. As I discover better ways of doing things, all you need to do to reap the benefits is to upgrade your devtools install.

If you've developed packages in the past without these tools, they may take a bit of getting used to. However, I strongly believe that mastering them will save you much much more time than it will take. There's no way I could have authored so many packages without devtools to help automate the humdrum task.

## RStudio

Devtools works particularly well in conjunction with RStudio projects.

## Getting started

To get started, make sure you have the latest version of R, then run the following code to get the packages you'll use in this book:

```{r, eval = FALSE}
install.packages(c("devtools", "roxygen2", "testthat", "knitr"))
```

During the development of the book, you'll probably want at least the development version of devtools:

```{r, eval = FALSE}
devtools::install_github("hadley/devtools")
```

You'll also need to make sure you have the appropriate development tools installed. If you're on windows or the mac, Rstudio will install these for you if you don't have them already. Otherwise:

* On Windows, download and install [Rtools](http://cran.r-project.org/bin/windows/Rtools/). NB: this is not an R package!

* On Mac, make sure you have either XCode (free, available in the app store)
  or the ["Command Line Tools for Xcode"](http://developer.apple.com/downloads)
  (needs a free apple id).

* On Linux, make sure you've installed not only R, but the R development
  devtools. This is a Linux package called something like `r-base-dev`.

You can check you have everything installed and working by running this code:

```{r, eval = FALSE}
library(devtools)
has_devel()
#> '/Library/Frameworks/R.framework/Resources/bin/R' --vanilla CMD SHLIB foo.c 
#> 
#> clang -I/Library/Frameworks/R.framework/Resources/include -DNDEBUG 
#>   -I/usr/local/include -I/usr/local/include/freetype2 -I/opt/X11/include
#>   -fPIC  -Wall -mtune=core2 -g -O2  -c foo.c -o foo.o
#> clang -dynamiclib -Wl,-headerpad_max_install_names -undefined dynamic_lookup
#>   -single_module -multiply_defined suppress -L/usr/local/lib -o foo.so foo.o 
#>   -F/Library/Frameworks/R.framework/.. -framework R -Wl,-framework 
#>   -Wl,CoreFoundation
[1] TRUE
```

It will print out some compilation code (this is needed to help diagnose problems), but you're only interested in whether it returns `TRUE` (everything's ok) or an error (which you need to investigate further).

## Package basics

This book is arranged according to the structure of an R package. It starts with the most commonly used components, and then gets more esoteric.

* `R/`: where your R code lives in `.R` files.

* `DESCRIPTION`: metadata about the package

* `man/`: function documentation

* `vignettes/`: long-form documentation which show how to combine multiple 
  parts of your package to solve real problems.

* `NAMESPACE`: ensures that your package plays nicely with others.

* `tests/`: stores unit tests that ensure that your package is operating as
  designed.

* `data/`: sample datasets (or other R objects)

* `src/`: compiled C, C++ and fortran source code

## Conventions

Throughout this book I use `f()` to refer to functions, `g` to refer to variables and function parameters, and `h/` to paths. 

Larger code blocks intermingle input and output. Output is commented so that you if you have an electronic version of the book, e.g., <http://r-pkgs.had.co.nz>, you can easily copy and paste examples into R. Output comments look like `#>` to distinguish them from regular comments.

## Colophon

This book was written in [Rmarkdown](http://rmarkdown.rstudio.com/) inside [RStudio](http://www.rstudio.com/ide/). [knitr](http://yihui.name/knitr/) and [pandoc](http://johnmacfarlane.net/pandoc/) converted the raw Rmarkdown to html and pdf. The [website](http://adv-r.had.co.nz) was made with [jekyll](http://jekyllrb.com/), styled with [bootstrap](http://getbootstrap.com/), and automatically published to Amazon's [S3](http://aws.amazon.com/s3/) by [travis-ci](https://travis-ci.org/). The complete source is available from [github](https://github.com/hadley/r-pkgs).

[r-ext]:http://cran.r-project.org/doc/manuals/R-exts.html#Creating-R-packages