Building your own packages is a good idea if you want to share code or data with other people, or if you just want to pack it up in a form that’s easy to reuse. This section explains the easy way to create your own packages.
To build a package, you need to place all the package
files (code, data, documentation, etc.) inside a single directory. You
can create an appropriate directory structure using the R function
package.skeleton
:
package.skeleton(name = "anRpackage", list, environment = .GlobalEnv, path = ".", force = FALSE, namespace = FALSE, code_files = character())
This function can also copy a set of R objects into that
directory. Here’s a description of the arguments to package.skeleton
.
Argument | Description | Default |
---|---|---|
name | A character value specifying a name for the new package | “anRpackage” (as a side note, this may be the least-useful default value for any R function) |
list | A character vector containing names of R objects to add to the package | |
environment | The environment in which to evaluate list | .GlobalEnv |
path | A character vector specifying the path in the file system | “.” |
force | A Boolean value specifying whether to overwrite files, if
a directory name already
exists at path | FALSE |
namespace | A Boolean value specifying whether to add a namespace to the package | FALSE |
code_files | A character vector specifying the paths of files containing R code | character() |
For this book, I created a package called nutshell
containing most of the data sets used
in this book:
> package.skeleton(name="nutshell",path="~/Documents/book/current/")
Creating directories ...
Creating DESCRIPTION ...
Creating Read-and-delete-me ...
Saving functions and data ...
Making help files ...
Done.
Further steps are described in
'~/Documents/book/current//nutshell/Read-and-delete-me'.
The package.skeleton
function
creates a number of files. There are directories named “man” (for help
files), “R” (for R source files), and “data” (for data files). One of
the most important is the DESCRIPTION file, at the root of the created
directory. Here is the file that was generated by the package.skeleton
function:
Package: nutshell Type: Package Title: What the package does (short line) Version: 1.0 Date: 2012-03-13 Author: Who wrote it Maintainer: Whom to complain to <yourfault@somewhere.net> Description: More about what it does (maybe more than one line) License: What license is it under?
Many of these items are self-explanatory, although a couple of items require more explanation. Additionally, there are a few useful optional items:
- LazyLoad
LazyLoad
controls how objects (including data) are loaded into R. If you setLazyLoad
to yes (the default), then data files in the packages are not loaded into memory. Instead, promise objects are loaded for each data package. You can still access the objects, but they take up (almost) no space.- LazyData
LazyData
works likeLazyLoad
but specifies what to do (specifically) with data files.- Depends
If your package depends on other packages to be installed (or on certain versions of R), you can specify them with this line. For example, to specify that your package requires R 2.8 or later and the
nnet
package, you would add the line:Depends: R(>= 2.8), nnet
R includes a set of functions that help automate the creation of
help files for packages: prompt
(for
generic documentation), promptData
(for documenting data files), promptMethods
(for documenting methods of a
generic function), and promptClass
(for documenting a class). See the help files for these functions for
additional information.
You can add data files to the data directory in several different
forms: as R data files (created by the save
function and named with either a
.rda or a .Rdata suffix), as comma-separated value
files (with a .csv suffix), or as
an R source file containing R code (with a .R
suffix).
After you’ve added all the materials to the package, you
can build it from the command line on your computer (not the R shell).
To make sure that the package complies with CRAN rules and builds
correctly, use the check
command. For
the previous example, we would use the following command:
$ R CMD check nutshell
You can get more information about the CMD check command by
entering R CMD CHECK --help
on the
command line. To build the package, you would use the following
command:
$ R CMD build nutshell
As above, help is available through the --help
option. If you’re really interested in
how to build R packages, see the manual Writing R
Extensions, available at http://cran.r-project.org/doc/manuals/R-exts.pdf.
Get R in a Nutshell, 2nd Edition now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.