10 Description File

10.1 Introduction

Every package needs a DESCRIPTION file. This is just a text file containing the metadata about your package. In other words, this type of file contains a set of specifications describing important aspects about your package. In this chapter we discuss some of the main fields in the DESCRIPTION file.

10.2 Sample Description

When creating an “off-the-shelf” package, like the hello world example, the file DESCRIPTION will contain some default lines:

Figure 10.1: Typical default content in a DESCRIPTION file

Although the DESCRIPTION file is a text with no file extension, it does follow a special type of format known as a Debian Control File:

https://www.debian.org/doc/debian-policy/index.html#document-ch-controlfields

If you take a peek at the content of the DESCRIPTION file, you will see that all its fields start with a name immediately followed by a colon :, followed by a space, and then the corresponding value of the field. Notice that all field names are capitalized. Also, keep in mind that field names are case-sensitive! Likewise, when the value of a given field requires continuation lines (for example, for descriptions longer than one line) make sure you use four spaces when indenting new lines.

You will need to customize the field values. Here’s an example of what the customized DESCRIPTION file may look like:

Package: cointoss
Type: Package
Title: Simulates Tossing a Coin
Version: 0.1.0
Author: Gaston Sanchez
Maintainer: Gaston Sanchez <gaston@email.com>
Description: Functions to create a coin object, to toss a coin multiple times,
    and to summarize and visualize frequencies of the tosses.
License: GPL-2
Encoding: UTF-8
LazyData: true

10.3 Mandatory Fields

Because you will need to customize some of the fields of your DESCRIPTION file, we need to review some of the most important ones, especially the seven ones that are mandatory:

Package
Title
Description
Author
Maintainer
Version
License

All other fields are optional.

10.3.1 Package Name

Every R package needs a name, specified in the Package field. The package of our study-case is "cointoss" but you can actually use a different name. However, you need to follow three rules to choose a valid package name:

the name can only consist of (ASCII) letters, numbers and the dot (or period).
it must start with a letter.
it cannot end with a period.

This means that we could have chosen names like COINTOSS, CoinToss, co1nto55, coin.toss, or Cointoss, for example. Unfortunately, this also implies that you can’t use either hyphens - or underscores _ in your package name. For example, you cannot have a name like coin-toss or coin_toss.

In case of doubt about choosing a name, I recommed reading Hadley Wickham’s suggestions for naming a package: r-pkgs: package naming.

10.3.2 Title

The Title field corresponds to a short description of the package. If the idea of short description sounds too vague, you can think of Title simply as a slogan. Here are the (somewhat restrictive) rules to write a valid title value:

it should use title case (that is, use capitals for the principal words).
not use any markup.
not have any continuation lines.
not end in a period.
do not repeat the package name
if you refer to other packages and external software then that has to be done in single quotes.
if you refer to book titles (and similar), then that has to be done in double quotes.

The Title value of our working example is:

Title: Simulates Tossing a Coin

But you could also specify a title like:

Title: Functions for Tossing a Coin

10.3.3 Description

The Description field provides a comprehensive description of what your package is designed for. The entire description must be given with one paragraph, which can contain various sentences.

Description: Functions to create a coin object, to toss a coin multiple times, and to summarize and visualize frequencies of the tosses.

The same rules of double quotes used in Title apply to Description. If you use URLs in your description, these should be enclosed in angle brackets, e.g. <https://www.r-project.org>.

10.3.4 Author and Maintainer

You need to provide the name(s) of the author(s). You also need to designate one (and only one) person who will be in charge of maintaining the package. The role of the maintainer is essentially fixing bugs, and integrate new code and build a new version.

Author: Gaston Sanchez
Maintainer: Gaston Sanchez <gaston@email.com>

10.3.5 Version

Another mandatory field is Version, which as you may guess, gives the version of the package. The version is a sequence of at least two (and usually three) non-negative integers separated by single . (dot) or - (hyphen) characters.

Version: 0.1.0

Among the different versioning schemes, perhaps the most common one consists of <major>.<minor>.<patch>. For example, consider a version number 1.5.3, 1 is the major number, 5 is the minor number, and 3 is the patch number.

Keep in mind that as you keep working on a package, releasing new versions of it, the version number of the package must increase. Another important detail has to do with the fact that version numbers are NOT decimal numbers. For instance, two versions 0.8 and 0.55 does not mean that 0.8 > 0.55. On the contrary, the order is 0.8 < 0.55` because 8 < 55 (again, they are not decimal numbers).

10.3.6 License

Your package needs a license.
You should choose a license intended for software.
Software licenses generally refer to source code.
The explicit reference to source code recognizes the fact that software code can exist in its source form, in addition to its binary form.

What licenses are available? There is a list of suggested licenses in the R-project website: https://www.r-project.org/Licenses.

MIT: MIT license
GPL-2 or GPL-3: GNU General Public License (GPL)
Artistic-2.0: Artistic License version 2.0
apache-2 Apache License 2.0
BSD_3_clause: BSD 3-Clause “New” or “Revised” license
BSD_2_clause: BSD 2-Clause “Simplified” or “FreeBSD” license
LGPL-2: GNU Library or “Lesser” General Public License (LGPL)

You can find more user friendly information about these and other popular licenses in the website of the Open Source Initiative. Likewise, you can also check the “Choose a license” guidelines available at https://choosealicense.com/licenses/.

Although R-project suggests the “Creative Commons Attribution-ShareAlike International License” version 4.0, I discourage the use of any Creative Commons (CC) license for software. CC licenses are good for media content (e.g. arrative, images, music), but not for source code.

To know more about the different fields in a description file, see r-pkgs: Package metadata.

10.4 Optional Fields

In addition to the previous seven mandatory fields, DESCRIPTION files can contain other optional fields. Here’s a few of them.

10.4.1 Encoding

Ideally, the DESCRIPTION file should be written entirely in ASCII characters. Sometimes, though, you need to use non-ASCII characters like accents, umlauts, cedillas, etc. Using the Encoding: UTF-8 allows you to use unicode characters. For example, had I decided to use my name in its Spanish version, I would specify author as Author: Gastón Sánchez, which has acute accents.

10.4.2 LazyData

The LazyData field is a logical field that controls whether the R datasets use lazy-loading. This implies that your package contains data files ("cointoss" does not have any data files).

10.4.3 Type

Another optional field is Type, which specifies the type of the package. This field is kind of a historical left-over. In the past, there used to be a Translation type (no longer used). If you don’t include Type, then it is assumed to be Package.

10.4.4 VignetteBuilder

If your package includes vignettes (i.e. there’s a vignettes/ subdirectory) written with .Rmd files, then DESCRIPTION needs a field and value VignetteBuilder: knitr.

Make a donation

If you find this resource useful, please consider making a one-time donation in any amount. Your support really matters.