description.rmd

---
title: Package basics
layout: default
output: bookdown::html_chapter
---

# Package metadata {#description}

The job of the `DESCRIPTION` file is to store important metadata about your package. In the early stages of package development, the most important thing that the `DESCRIPTION` does is store which other packages your package needs to work. The `DESCRIPTION` becomes more important if you plan to release your package to others because it also lays out who can use it (the license), and who to contact (you!) if there are any problems.

## A minimal `DESCRIPTION` file

When you create a new package with `create()` devtools automatically adds a minimal `DESCRIPTION` that contains everything you need to get started. This means you don't need to worry about the `DESCRIPTION` in the early stages of package development. The minimal description looks something like this:

    Package: package-name
    Title: What the package does (short line)
    Version: 0.1
    Authors@R: "First Last <first.last@example.com> [aut, cre]"
    Description: What the package does (paragraph)
    Depends: R (>= 3.1.0)
    License: What license is it under?
    LazyData: true

This is the critical subset of package metadata: what it's called (`Package`), what it does (`Title`, `Description`), what version it is (`Version`), who's allowed to use and distribute it (`License`), and who wrote it (`Author@R`).

## Naming tips {#naming}

The `Package` field defines the name of the package. This should be same as the name of directory. Often the hardest thing about creating a new package is coming up with a good name. There's only one formal requirement: the package name can only consist of letters and numbers, and must start with a letter. 

If you're planning on releasing your package to the wild, I think it's worth spending a few minutes to come up with a good name. I have two recommendations:

* Pick a unique name so you can easily google it. This makes it easy for 
  potential users to find your package, and it makes it easier for you to
  see who's using your package.

* Avoid using both upper and lower case letters: they make the package name
  hard to type and hard to remember. For example, I can never remember if it's
  `Rgtk2` or `RGTK2` or `RGtk2`.

Some strategies I've used in the past to create packages names:

* Find a name evocative of the problem and modify it so that it's unique:
  `plyr` (generalisation of apply tools), `lubridate` (makes dates and times
  easier), `mutatr` (mutable objects), `classifly` (high-dimensional views of
  classification).

* Use abbreviations: `lvplot` (letter value plots), `meifly` (models explored
  interactively).

* Add an extra R: `stringr` (string processing), `tourr` (grand tours), `httr`
  (HTTP requests).

## What does the package do?

There are two fields that describe the package. They differ in length:

* `Title` is a one line description of the package, and is often shown in 
  package listing. It should be plain text (no markup), be capitalised like a 
  sentence, but not end in a period. Keep it short: listings will often 
  truncate the title to 65 characters.

* `Description` is more detailed: you can use multiple sentences, but still 
  only one paragraph. The most common place to see the description is on the
  CRAN download page.
  
  If your description spans multiple lines (and it should!), keep each
  line at most 80 characters wide, and indent subsequent lines with 4 spaces.

The `Title` and `Description` for ggplot2 are:

```
Title: An implementation of the Grammar of Graphics
Description: An implementation of the grammar of graphics
    in R. It combines the advantages of both base and
    lattice graphics: conditioning and shared axes are
    handled automatically, and you can still build up a
    plot step by step from multiple data sources. It also
    implements a sophisticated multidimensional
    conditioning system and a consistent interface to map
    data to aesthetic attributes. See the ggplot2 website
    for more information, documentation and examples.
```

And these are rendered on the CRAN download page as follows:

```{r, echo = FALSE}
bookdown::embed_png("diagrams/cran-package.png")
```

## What does the package need?

It's also the job of the `DESCRIPTION` to list which other packages that your package needs to work. R has a rich set of ways of describing potential dependencies. Each takes a comma separated list of packages with optional version dependencies.

There are two important options:

* `Imports`: your package requires these packages to work.

* `Suggests`: you don't absolutely need these packages but they might be
  helpful. Maybe they provide datasets for examples, or only used by one
  function in your package.

Three others are useful in more specialised circumstances:

* `Depends`: used to specify version of R needed, and for a few other 
  special cases. Other mostly historical and should not be used.

* `LinkingTo`: needs to link to or compile against the C code included in
  this package.
  
* `Enhances`: these packages are "enhanced" by your package, typically because
  you provide methods for classes defined in the package. It's a sort of reverse
  suggests. But it's hard to define what that actually means, so I recommend 
  that you don't use it.
  
http://cran.r-project.org/doc/manuals/R-exts.html#Package-Dependencies

```{r, eval = FALSE}
# Default to imports
use_package("Rcpp")
use_package("Rcpp", "LinkingTo")
```

You can also list other requirements (outside of R) in `SystemRequirements`. But this is basically only useful as a quick reference - you'll also need to include detailed information in a readme.

## Who wrote the package?

Instead of `Maintainer` and `Author`, you can `Authors@R`, which takes a vector of `person()` elements.  Each person object specifies the name of the person and their role in creating the package:

* `aut`: full authors who have contributed much to the package

* `ctb`: people who have made smaller contributions, like patches.

* `cre`: the package creator/maintainer, the person you should bother if you
  have problems

Other roles are listed in the help for person. Using `Authors@R` is useful when your package gets bigger and you have multiple contributors that you want to acknowledge appropriately. The equivalent `Authors@R` syntax for plyr would be:

      Authors@R: person("Hadley", "Wickham", role = c("aut", "cre"))

As well as providing your email address, it's also a good idea to list other resources avaialble for help. You can list urls in `URL` Multiple urls can be separated with a comma. `BugReports` takes a url to where bug reports should be submitted.

## Who can use it? (`LICENSE`)

`License`: a standard abbreviation for an open source license, like `GPL-2` or `BSD`.

A complete list of abbreviations (as of `r R.version.string`) is:

```{r, results='asis', echo = FALSE}
licenses <- read.dcf(file.path(R.home("share"), "licenses", "license.db"))
licenses <- as.data.frame(licenses, stringsAsFactors = FALSE)
licenses <- licenses[order(licenses$Name, licenses$Version), ]
licenses[is.na(licenses)] <- ""
has_abbrev <- subset(licenses, Abbrev != "")
knitr::kable(has_abbrev[c("Name", "Version", "Abbrev")], row.names = FALSE)
```

If you are using a non-standard license, put `file LICENSE` and then include the full text of the license in a `LICENSE`.

## Other components

* `Version`: the version number, which should be of the the form 
  `major.minor.patchlevel`. This is most important when releasing your package. 
  See [version numbers](#version) for more deatils.

* `LazyData`. Described in [external data](#data).

There are a number of other less commonly used fields like `KeepSource`, `OS_type` and `Language`. A complete list can be found in the [R extensions manual][description].

## Collation order {#collate}

R loads files in alphabetical order. Unfortunately not every alphabet puts letters in the same order, so you can't rely on alphabetic ordering if you need one file loaded before another. The order in which files are loaded doesn't matter for most packages. But if you're using S4, you'll need to make sure that classes are loaded before subclasses and generics are defined before methods.

Rather than relying on alphabetic ordering, roxygen2 provides an explicit way of saying that one file must be loaded before another: `@include`. The `@include` tag gives a space separated list of file names that should be loaded before the current file:

```{r, eval = FALSE}
#' @include class-a.r
setClass("B", contains = "A")
```

If any `@include` tags are present in the package, roxygen2 will set the `Collate` field in the `DESCRIPTION`, which ensures that files are always loaded in the same order.

[description]: http://cran.r-project.org/doc/manuals/R-exts.html#The-DESCRIPTION-file