03-package-structure.Rmd

```{r echo = FALSE}
knitr::opts_chunk$set(
  comment = "#>",
  warning = FALSE,
  message = FALSE
)
```


# Package structure {#package-structure}

## Package metadata (`DESCRIPTION`)

```
Package: mypackage
Title: What The Package Does (one line, title case required)
Version: 0.1
Authors@R: person("First", "Last", email = "first.last@example.com",
                  role = c("aut", "cre"))
Description: What the package does (one paragraph)
Depends: R (>= 3.1.0)
License: What license is it under?
URL: http://someurl
BugReports: http://someurl
```

gotchas/must do's: 

* no period at end of `Title`!
* single quote words in the `Description` that are likely to not be
known in a simple spell checker.
* ABSOLUTELY make sure to include url for where the source code is and where to report bugs/issues. Seriously, this is not a joke. I do not use packages that don't have URLs.

## Code (`R/`)

The `R/` folder contains any number of `.R` files. 

It's worth thinking about organization, see <http://r-pkgs.had.co.nz/r.html#r-organising> for more.

## Namespaces (`NAMESPACE`)

The `NAMESPACE` file contains:

* what to import from othe packages
* what to export (expose publicly), available via `::` 
    * note that internal fxns are still available via `:::`
* what does `importFrom()` mean? how is it different from `import()`

__Hot tips__

* If you run into namespace problems, delete the lines in `NAMESPACE` and re-document the package
* if you accidentally delete the `NAMESPACE` file, re-document
* it's a good place to look for: 
    * what you're exporting and what you are not exporting
    * same for importing


## Object documentation (`man/`)


`man/` contains files with extension `.Rd`. 

You should not be editing these by hand. 

Use `roxygen2` package with documentation associated with your code in `.R` files.


## Vignettes (`vignettes/`)

Vignettes are typically longer form examples/documentation on your package, and are linked to on the CRAN page for each package. See \@ref(extras-vign) for more.


## Tests (`tests/`)

Tests help you make sure your package does what you expect it to do, including as you make changes. 

See \@ref(tests) for more.

## Data (`data/`)

`data/` holds package data, used in your package functions, and optionally exposed to the user.

## Compiled Code (`src/`)

Typically C or C++ code ... too much detail for now.

This is typically the problem when you see a bunch of stuff printed to the console when you have package installation problems - once a binary is available installation is sorted.

## Installed files (`inst/`)

Holds various files used by the package, e.g., 

`inst/examples` - files you want to use in examples that are not R objects, e.g., csv files

You can access these files with `system.file("examples/file.csv", package = "your_package")`