R Packages, 2nd Edition

Chapter 9. DESCRIPTION

DESCRIPTION and NAMESPACE are two important files that provide metadata about your package. The DESCRIPTION file provides overall metadata about the package, such as the package name and which other packages it depends on. The NAMESPACE file specifies which functions your package makes available for others to use and, optionally, imports functions from other packages.

In this chapter, you’ll learn about the most important fields found in DESCRIPTION. The next two chapters cover the topic of package dependencies, which is where the importance of the NAMESPACE file will become clear. First, in Chapter 10, we discuss the costs and benefits of dependencies and also provide the relevant technical context around how R finds objects. In Chapter 11, we explain the practical moves necessary to use your dependencies within your package. The metadata part of the book concludes with Chapter 12, which covers licensing.

The DESCRIPTION File

The job of the DESCRIPTION file is to store important metadata about your package. When you first start writing packages, you’ll mostly use this metadata to record what packages are needed to run your package. However, as time goes by, other aspects of the metadata file will become useful to you, such as revealing what your package does (via the Title and DESCRIPTION) and whom to contact (you!) if there are any problems.

Every package must have a DESCRIPTION. In fact, it’s the defining feature of a package (RStudio and devtools consider ...