Chapter 4 Package structure

4.1 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.

4.2 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.

4.3 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

4.4 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.

4.5 Vignettes (vignettes/)

Vignettes are typically longer form examples/documentation on your package, and are linked to on the CRAN page for each package. See 10.3 for more.

4.6 Tests (tests/)

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

See 8 for more.

4.7 Data (data/)

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

4.8 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.

4.9 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")