Making it a proper package
We created a usable package by just
- Creating a directory with a subdirectory
- Putting some
.Rfiles in the
- Creating a
DESCRIPTIONfile with the package name and a version number.
We can build the
.tar.gz package file and give it to friends to
install, but it’s still not a proper R package. We need to do a few
- Fill out the
- Create a
- Add some documentation.
Filling out the
DESCRIPTION file had just two lines. We need to add a few more:
a title, a description, an author, and a maintainer (usually one of
the authors). It’s also a good idea to include the date. It should
look something like this:
Package: brocolors Version: 0.1 Date: 2014-08-27 Title: Karl Broman Colors Description: Colors that Karl Broman uses in figures. Author: Karl W Broman <email@example.com> Maintainer: Karl W Broman <firstname.lastname@example.org>
The title should be short. The description should be a sentence or
two; it can span multiple lines. The
Maintainer field should include
an email address, surrounded by
< >. The author field doesn’t need
A bunch more things can be put in the
DESCRIPTION file, but this is
sufficient for now.
Creating a package
NAMESPACE file has long been one of the more
painful aspects of building an R package.
I dragged my feet on these
NAMESPACE files for years.
(It’s no longer so painful, as we’ll see shortly.)
With the huge growth in the number of R packages, it became important
to avoid naming conflicts among packages: two packages might have the
same name for totally different functions, particularly with little
helper functions. With a
NAMESPACE file, you indicate which
functions are to be available to users and which are to be strictly
internal. By hiding the little helper functions, there’s less chance
of naming conflicts.
NAMESPACE file is pretty easy, though. You just need one
# Export all names exportPattern(".")
Okay, that’s two lines. But the first line is just a comment.
So the simplest step towards making your R package a proper package
is to create a plain text file called
containing these lines and put it in your package directory.
Your package will then look like this.
It’s still not a proper package (in that we still need to write some documentation), but you can now build and install it with devtools.
It’s not a proper package until you’ve added documentation. The
documentation will sit in a
man subdirectory (
“manual”), and has to be in a special
“R documentation”) format, with
.Rd file for each
function in the package. The
.Rd format is rather
LaTeX-like and so ugly to prepare and
But, you don’t have to create those
yourself. Roxygen2 is an R
package that makes it much easier to create R documentation for your
R package. You write comments within your
.R files, in a specially
structured way, describing the inputs and outputs and so forth for
each function, and then Roxygen2 will create the
.Rd files for you.
Roxygen2 will also create the
NAMESPACE file for you.
And actually, there’s one more thing (after the documentation) that
you need to do before your package is proper. You need to pick a
license for the software and specify the license in the
file. This is, perhaps, an even more ugly topic than
files. I’ll explain it a bit later.
Fill out the
DESCRIPTION file for your package and add a minimal
NAMESPACE file. Try building and installing it with
Then go to the page about writing documentation with Roxygen2.