10 Description File
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:
DESCRIPTION file is a text with no file extension, it does follow a special type of format known as a Debian Control File:
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 <email@example.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:
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, 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
In case of doubt about choosing a name, I recommed reading Hadley Wickham’s suggestions for naming a package: r-pkgs: package naming.
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.
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
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.
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.
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.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).
- 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-3: GNU General Public License (GPL)
Artistic-2.0: Artistic License version 2.0
apache-2Apache 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.
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.
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).
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
If your package includes vignettes (i.e. there’s a
vignettes/ subdirectory) written with
.Rmd files, then
DESCRIPTION needs a field and value
Make a donation
If you find this resource useful, please consider making a one-time donation in any amount. Your support really matters.