All non-text content that is presented to the user has a text alternative that serves the equivalent purpose, except for the situations listed below.
Controls, Input: If non-text content is a control or accepts user input, then it has a name that describes its purpose. (Refer to Guideline 4.1 for additional requirements for controls and content that accepts user input.)
Time-Based Media: If non-text content is time-based media, then text alternatives at least provide descriptive identification of the non-text content. (Refer to Guideline 1.2 for additional requirements for media.)
Test: If non-text content is a test or exercise that would be invalid if presented in text, then text alternatives at least provide descriptive identification of the non-text content.
Sensory: If non-text content is primarily intended to create a specific sensory experience, then text alternatives at least provide descriptive identification of the non-text content.
CAPTCHA: If the purpose of non-text content is to confirm that content is being accessed by a person rather than a computer, then text alternatives that identify and describe the purpose of the non-text content are provided, and alternative forms of CAPTCHA using output modes for different types of sensory perception are provided to accommodate different disabilities.
Decoration, Formatting, Invisible: If non-text content is pure decoration, is used only for visual formatting, or is not presented to users, then it is implemented in a way that it can be ignored by assistive technology.
Writing R Extensions
Table of Contents
Writing R Extensions
This is a guide to extending R, describing the process of creating R add-on packages, writing R documentation, R’s system and foreign language interfaces, and the R .
This manual is for R, version 3.4.3 (2017-11-30).
Copyright © 1999–2016 R Core Team
Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.
Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.
Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the R Core Team.
The contributions to early versions of this manual by Saikat DebRoy (who wrote the first draft of a guide to using and ) and Adrian Trapletti (who provided information on the C++ interface) are gratefully acknowledged.
1 Creating R packages
Packages provide a mechanism for loading optional code, data and documentation as needed. The R distribution itself includes about 30 packages.
In the following, we assume that you know the command, including its argument, and we also assume basic knowledge of the utility. Otherwise, please look at R’s help pages on
before reading on.
For packages which contain code to be compiled, a computing environment including a number of tools is assumed; the “R Installation and Administration” manual describes what is needed for each OS.
Once a source package is created, it must be installed by the command . See Add-on-packages in R Installation and Administration.
Other types of extensions are supported (but rare): See Package types.
Some notes on terminology complete this introduction. These will help with the reading of this manual, and also in describing concepts accurately when asking for help.
A package is a directory of files which extend R, a source package (the master files of a package), or a tarball containing the files of a source package, or an installed package, the result of running on a source package. On some platforms (notably macOS and Windows) there are also binary packages, a zip file or tarball containing the files of an installed package which can be unpacked rather than installing from sources.
A package is not1 a library. The latter is used in two senses in R documentation.
- A directory into which packages are installed, e.g. : in that sense it is sometimes referred to as a library directory or library tree (since the library is a directory which contains packages as directories, which themselves contain directories).
- That used by the operating system, as a shared, dynamic or static library or (especially on Windows) a DLL, where the second L stands for ‘library’. Installed packages may contain compiled code in what is known on Unix-alikes as a shared object and on Windows as a DLL. The concept of a shared library (dynamic library on macOS) as a collection of compiled code to which a package might link is also used, especially for R itself on some platforms. On most platforms these concepts are interchangeable (shared objects and DLLs can both be loaded into the R process and be linked against), but macOS distinguishes between shared objects (extension ) and dynamic libraries (extension ).
There are a number of well-defined operations on source packages.
- The most common is installation which takes a source package and installs it in a library using or .
- Source packages can be built. This involves taking a source directory and creating a tarball ready for distribution, including cleaning it up and creating PDF documentation from any vignettes it may contain. Source packages (and most often tarballs) can be checked, when a test installation is done and tested (including running its examples); also, the contents of the package are tested in various ways for consistency and portability.
- Compilation is not a correct term for a package. Installing a source package which contains C, C++ or Fortran code will involve compiling that code. There is also the possibility of ‘byte’ compiling the R code in a package (using the facilities of package compiler): already base and recommended packages are normally byte-compiled and this can be specified for other packages. So compiling a package may come to mean byte-compiling its R code.
- It used to be unambiguous to talk about loading an installed package using , but since the advent of package namespaces this has been less clear: people now often talk about loading the package’s namespace and then attaching the package so it becomes visible on the search path. Function performs both steps, but a package’s namespace can be loaded without the package being attached (for example by calls like ).
The concept of lazy loading of code or data is mentioned at several points. This is part of the installation, always selected for R code but optional for data. When used the R objects of the package are created at installation time and stored in a database in the directory of the installed package, being loaded into the session at first use. This makes the R session start up faster and use less (virtual) memory. (For technical details, see Lazy loading in R Internals.)
is a network of WWW sites holding the R distributions and contributed code, especially R packages. Users of R are encouraged to join in the collaborative project and to submit their own packages to : current instructions are linked from https://CRAN.R-project.org/banner.shtml#submitting.
1.1 Package structure
The sources of an R package consists of a subdirectory containing a files and , and the subdirectories , , , , , , , , , and (some of which can be missing, but which should not be empty). The package subdirectory may also contain files , , , , and . Other files such as (for non-standard installation instructions), /2, or will be ignored by R, but may be useful to end users. The utility may add files in a directory (but this should not be used for other purposes).
Except where specifically mentioned,3 packages should not contain Unix-style ‘hidden’ files/directories (that is, those whose name starts with a dot).
The and files are described in the subsections below. The file is described in the section on Package namespaces.
The optional files and are (Bourne) shell scripts which are, respectively, executed before and (if option was given) after installation on Unix-alikes, see Configure and cleanup. The analogues on Windows are and .
For the conventions for files and in the project see https://www.gnu.org/prep/standards/standards.html#Documentation.
The package subdirectory should be given the same name as the package. Because some file systems (e.g., those on Windows and by default on OS X) are not case-sensitive, to maintain portability it is strongly recommended that case distinctions not be used to distinguish different packages. For example, if you have a package named , do not also create a package named .
To ensure that file names are valid across file systems and supported operating systems, the control characters as well as the characters ‘’, ‘’, ‘’, ‘’, ‘’, ‘’, ‘’, ‘’, and ‘’ are not allowed in file names. In addition, files with names ‘’, ‘’, ‘’, ‘’, ‘’, ‘’ to ‘’, and ‘’ to ‘’ after conversion to lower case and stripping possible “extensions” (e.g., ‘’), are disallowed. Also, file names in the same directory must not differ only by case (see the previous paragraph). In addition, the basenames of ‘’ files may be used in URLs and so must be and not contain . For maximal portability filenames should only contain only characters not excluded already (that is — we exclude space as many utilities do not accept spaces in file paths): non-English alphabetic characters cannot be guaranteed to be supported in all locales. It would be good practice to avoid the shell metacharacters : is also used as part of ‘8.3’ filenames on Windows. In addition, packages are normally distributed as tarballs, and these have a limit on path lengths: for maximal portability 100 bytes.
A source package if possible should not contain binary executable files: they are not portable, and a security risk if they are of the appropriate architecture. will warn about them4 unless they are listed (one filepath per line) in a file at the top level of the package. Note that will not accept submissions containing binary files even if they are listed.
The R function can help to create the structure for a new package: see its help page for details.
1.1.1 The file
The file contains basic information about the package in the following format:
Package: pkgname Version: 0.5-1 Date: 2015-01-01 Title: My First Collection of Functions Authors@R: c(person("Joe", "Developer", role = c("aut", "cre"), email = "Joe.Developer@some.domain.net"), person("Pat", "Developer", role = "aut"), person("A.", "User", role = "ctb", email = "A.User@whereever.net")) Author: Joe Developer [aut, cre], Pat Developer [aut], A. User [ctb] Maintainer: Joe Developer <Joe.Developer@some.domain.net> Depends: R (>= 3.1.0), nlme Suggests: MASS Description: A (one paragraph) description of what the package does and why it may be useful. License: GPL (>= 2) URL: https://www.r-project.org, http://www.another.url BugReports: https://pkgname.bugtracker.url
The format is that of a version of a ‘Debian Control File’ (see the help for ‘’ and https://www.debian.org/doc/debian-policy/ch-controlfields.html: R does not require encoding in UTF-8 and does not support comments starting with ‘’). Fields start with an name immediately followed by a colon: the value starts after the colon and a space. Continuation lines (for example, for descriptions longer than one line) start with a space or tab. Field names are case-sensitive: all those used by R are capitalized.
For maximal portability, the file should be written entirely in — if this is not possible it must contain an ‘’ field (see below).
Several optional fields take logical values: these can be specified as ‘’, ‘’, ‘’ or ‘’: capitalized values are also accepted.
The ‘’, ‘’, ‘’, ‘’, ‘’, ‘’, and ‘’ fields are mandatory, all other fields are optional. Fields ‘’ and ‘’ can be auto-generated from ‘’, and may be omitted if the latter is provided: however if they are not we recommend that they are provided.
The mandatory ‘’ field gives the name of the package. This should contain only () letters, numbers and dot, have at least two characters and start with a letter and not end in a dot. If it needs explaining, this should be done in the ‘’ field (and not the ‘’ field).
The mandatory ‘’ field gives the version of the package. This is a sequence of at least two (and usually three) non-negative integers separated by single ‘’ or ‘’ characters. The canonical form is as shown in the example, and a version such as ‘’ or ‘’ will be handled as if it were ‘’. It is not a decimal number, so for example since .
The mandatory ‘’ field is discussed in the next subsection.
The mandatory ‘’ field should give a short description of the package. Some package listings may truncate the title to 65 characters. It should use title case (that is, use capitals for the principal words: can help you with this), not use any markup, not have any continuation lines, and not end in a period (unless part of …). Do not repeat the package name: it is often used prefixed by the name. Refer to other packages and external software in single quotes, and to book titles (and similar) in double quotes.
The mandatory ‘’ field should give a comprehensive description of what the package does. One can use several (complete) sentences, but only one paragraph. It should be intelligible to all the intended readership (e.g. for a package to all users). It is good practice not to start with the package name, ‘This package’ or similar. As with the ‘’ field, double quotes should be used for quotations (including titles of books and articles), and single quotes for non-English usage, including names of other packages and external software. This field should also be used for explaining the package name if necessary. URLs should be enclosed in angle brackets, e.g. ‘’: see also Specifying URLs.
The mandatory ‘’ field describes who wrote the package. It is a plain text field intended for human readers, but not for automatic processing (such as extracting the email addresses of all listed contributors: for that use ‘’). Note that all significant contributors must be included: if you wrote an R wrapper for the work of others included in the directory, you are not the sole (and maybe not even the main) author.
The mandatory ‘’ field should give a single name followed by a valid (RFC 2822) email address in angle brackets. It should not end in a period or comma. This field is what is reported by the function and used by . For a package it should be a person, not a mailing list and not a corporate entity: do ensure that it is valid and will remain valid for the lifetime of the package.
Note that the display name (the part before the address in angle brackets) should be enclosed in double quotes if it contains non-alphanumeric characters such as comma or period. (The current standard, RFC 5322, allows periods but RFC 2822 did not.)
Both ‘’ and ‘’ fields can be omitted if a suitable ‘’ field is given. This field can be used to provide a refined and machine-readable description of the package “authors” (in particular specifying their precise roles), via suitable R code. It should create an object of class , by either a call to or a series of calls (one per “author”) concatenated by : see the example file above. The roles can include ‘’ (author) for full authors, ‘’ (creator) for the package maintainer, and ‘’ (contributor) for other contributors, ‘’ (copyright holder), among others. See for more information. Note that no role is assumed by default. Auto-generated package citation information takes advantage of this specification. The ‘’ and ‘’ fields are auto-generated from it if needed when building5 or installing.
An optional ‘’ field can be used where the copyright holder(s) are not the authors. If necessary, this can refer to an installed file: the convention is to use file .
The optional ‘’ field gives the release date of the current version of the package. It is strongly recommended6 to use the ‘’ format conforming to the ISO 8601 standard.
The ‘’, ‘’, ‘’, ‘’, ‘’ and ‘’ fields are discussed in a later subsection.
Dependencies external to the R system should be listed in the ‘’ field, possibly amplified in a separate file.
The ‘’ field may give a list of s separated by commas or whitespace, for example the homepage of the author or a page where additional material describing the software can be found. These s are converted to active hyperlinks in package listings. See Specifying URLs.
The ‘’ field may contain a single to which bug reports about the package should be submitted. This will be used by instead of sending an email to the maintainer. A browser is opened for a ‘’ or ‘’ . As from R 3.4.0, will try to extract an email address (preferably from a ‘’ URL or enclosed in angle brackets).
Base and recommended packages (i.e., packages contained in the R source distribution or available from and recommended to be included in every binary distribution of R) have a ‘’ field with value ‘’ or ‘’, respectively. These priorities must not be used by other packages.
A ‘’ field can be used for controlling the collation order for the R code files in a package when these are processed for package installation. The default is to collate according to the ‘’ locale. If present, the collate specification must list all R code files in the package (taking possible OS-specific subdirectories into account, see Package subdirectories) as a whitespace separated list of file paths relative to the subdirectory. Paths containing white space or quotes need to be quoted. An OS-specific collation field (‘’ or ‘’) will be used in preference to ‘’.
The ‘’ logical field controls whether the R datasets use lazy-loading. A ‘’ field was used in versions prior to 2.14.0, but now is ignored.
The ‘’ logical field controls if the package code is sourced using or : it might be needed exceptionally for a package designed to always be used with .
The ‘’ logical field controls if the package code is to be byte-compiled on installation: the default is currently not to, so this may be useful for a package known to benefit particularly from byte-compilation (which can take quite a long time and increases the installed size of the package). It is used for the recommended packages, as they are byte-compiled when R is installed and for consistency should be byte-compiled when updated. This can be overridden by installing with flag .
The ‘’ logical field was used to control whether the automatic Windows build would zip up the data directory or not prior to R 2.13.0: it is now ignored.
The ‘’ logical field is used on Windows to select the option for this package.
The ‘’ logical field can be set to a false value to stop from attempting to build the vignettes, as well as preventing7 from testing this. This should only be used exceptionally, for example if the PDFs include large figures which are not part of the package sources (and hence only in packages which do not have an Open Source license).
The ‘’ field names (in a comma-separated list) packages that provide an engine for building vignettes. These may include the current package, or ones listed in ‘’, ‘’ or ‘’. The utils package is always implicitly appended. See Non-Sweave vignettes for details.
If the file is not entirely in it should contain an ‘’ field specifying an encoding. This is used as the encoding of the file itself and of the and files, and as the default encoding of files. The examples are assumed to be in this encoding when running , and it is used for the encoding of the file. Only encoding names , and are known to be portable. (Do not specify an encoding unless one is actually needed: doing so makes the package less portable. If a package has a specified encoding, you should run etc in a locale using that encoding.)
The ‘’ field should be set to if the package contains code which to be compiled, otherwise (when the package could be installed from source on any platform without additional tools). This is used by in R >= 2.15.2 on platforms where binary packages are the norm: it is normally set by or the repository assuming compilation is required if and only if the package has a directory.
The ‘’ field specifies the OS(es) for which the package is intended. If present, it should be one of or , and indicates that the package can only be installed on a platform with ‘’ having that value.
The ‘’ field specifies the type of the package: see Package types.
One can add subject classifications for the content of the package using the fields ‘’ or ‘’ (using the Computing Classification System of the Association for Computing Machinery, http://www.acm.org/about/class/; the former refers to the 1998 version), ‘’ (the Journal of Economic Literature Classification System, https://www.aeaweb.org/econlit/jelCodes.php, or ‘’ or ‘’ (the Mathematics Subject Classification of the American Mathematical Society, http://www.ams.org/msc/; the former refers to the 2000 version). The subject classifications should be comma-separated lists of the respective classification codes, e.g., ‘’.
A ‘’ field can be used to indicate if the package documentation is not in English: this should be a comma-separated list of standard (not private use or grandfathered) IETF language tags as currently defined by RFC 5646 (https://tools.ietf.org/html/rfc5646, see also https://en.wikipedia.org/wiki/IETF_language_tag), i.e., use language subtags which in essence are 2-letter ISO 639-1 (https://en.wikipedia.org/wiki/ISO_639-1) or 3-letter ISO 639-3 (https://en.wikipedia.org/wiki/ISO_639-3) language codes.
An ‘’ field can be used to hold a comma-separated list of packages from which the current package will import macro definitions. These will be imported after the system macros, in the order listed in the ‘’ field, before any macro definitions in the current package are loaded. Macro definitions in individual files in the directory are loaded last, and are local to later parts of that file. In case of duplicates, the last loaded definition will be used8 Both and have an optional flag . The option is also a comma-separated list of package names, and has priority over the value given in . Packages using macros should depend on R 3.2.0 or later.
Note: There should be no ‘’ or ‘’ fields, as these are added by the package management tools.
There is no restriction on the use of other fields not mentioned here (but using other capitalizations of these field names would cause confusion). Fields , (for contacting the authors/developers9) and are in common use. Some repositories (including and R-forge) add their own fields.
Licensing for a package which might be distributed is an important but potentially complex subject.
It is very important that you include license information! Otherwise, it may not even be legally correct for others to distribute copies of the package, let alone use it.
The package management tools use the concept of ‘free or open source software’ (FOSS, e.g., https://en.wikipedia.org/wiki/FOSS) licenses: the idea being that some users of R and its packages want to restrict themselves to such software. Others need to ensure that there are no restrictions stopping them using a package, e.g. forbidding commercial or military use. It is a central tenet of FOSS software that there are no restrictions on users nor usage.
Do not use the ‘’ field for information on copyright holders: if needed, use a ‘’ field.
The mandatory ‘’ field in the file should specify the license of the package in a standardized form. Alternatives are indicated via vertical bars. Individual specifications must be one of
- One of the “standard” short specifications GPL-2 GPL-3 LGPL-2 LGPL-2.1 LGPL-3 AGPL-3 Artistic-2.0 BSD_2_clause BSD_3_clause MIT
as made available viahttps://www.R-project.org/Licenses/ and contained in subdirectory of the R source or home directory.
- The names or abbreviations of other licenses contained in the license data base in file in the R source or home directory, possibly (for versioned licenses) followed by a version restriction of the form ‘’ with ‘’ one of the comparison operators ‘’, ‘’, ‘’, ‘’, ‘’, or ‘’ and ‘’ a numeric version specification (strings of non-negative integers separated by ‘’), possibly combined via ‘’ (see below for an example). For versioned licenses, one can also specify the name followed by the version, or combine an existing abbreviation and the version with a ‘’.
Abbreviations and are ambiguous and usually10 taken to mean any version of the license: but it is better not to use them.
- One of the strings ‘’ or ‘’ referring to a file named or in the package (source and installation) top-level directory.
- The string ‘’, meaning that there are no restrictions on distribution or use other than those imposed by relevant laws (including copyright laws).
If a package license restricts a base license (where permitted, e.g., using GPL-3 or AGPL-3 with an attribution clause), the additional terms should be placed in file (or ), and the string ‘’ (or ‘’, respectively) should be appended to the corresponding individual license specification. Note that several commonly used licenses do not permit restrictions: this includes GPL-2 and hence any specification which includes it.
Examples of standardized specifications include
Please note in particular that “Public domain” is not a valid license, since it is not recognized in some jurisdictions.
Please ensure that the license you choose also covers any dependencies (including system dependencies) of your package: it is particularly important that any restrictions on the use of such dependencies are evident to people reading your file.
Fields ‘’ and ‘’ may be added by repositories where information cannot be computed from the name of the license. ‘’ is used for licenses which are known to be FOSS, and ‘’ can have values ‘’ or ‘’ if the file is known to restrict users or usage, or known not to. These are used by, e.g., the filters.
The optional file / contains a copy of the license of the package. To avoid any confusion only include such a file if it is referred to in the ‘’ field of the file.
Whereas you should feel free to include a license file in your source distribution, please do not arrange to install yet another copy of the or files but refer to the copies on https://www.R-project.org/Licenses/ and included in the R distribution (in directory ). Since files named or will be installed, do not use these names for standard license files. To include comments about the licensing rather than the body of a license, use a file named something like .
A few “standard” licenses are rather license templates which need additional information to be completed via ‘’.
1.1.3 Package Dependencies
The ‘’ field gives a comma-separated list of package names which this package depends on. Those packages will be attached before the current package when or is called. Each package name may be optionally followed by a comment in parentheses specifying a version requirement. The comment should contain a comparison operator, whitespace and a valid version number, e.g. ‘’.
The ‘’ field can also specify a dependence on a certain version of R — e.g., if the package works only with R version 3.0.0 or later, include ‘’ in the ‘’ field. You can also require a certain SVN revision for R-devel or R-patched, e.g. ‘’ requires a version later than R-devel of late July 2011 (including released versions of 2.14.0).
It makes no sense to declare a dependence on without a version specification, nor on the package base: this is an R package and package base is always available.
A package or ‘’ can appear more than once in the ‘’ field, for example to give upper and lower bounds on acceptable versions.
Both and the R package checking facilities use this field: hence it is an error to use improper syntax or misuse the ‘’ field for comments on other software that might be needed. The R facilities check if the version of R used is recent enough for the package being installed, and the list of packages which is specified will be attached (after checking version requirements) before the current package.
The ‘’ field lists packages whose namespaces are imported from (as specified in the file) but which do not need to be attached. Namespaces accessed by the ‘’ and ‘’ operators must be listed here, or in ‘’ or ‘’ (see below). Ideally this field will include all the standard packages that are used, and it is important to include S4-using packages (as their class definitions can change and the file is used to decide which packages to re-install when this happens). Packages declared in the ‘’ field should not also be in the ‘’ field. Version requirements can be specified and are checked when the namespace is loaded (since R >= 3.0.0).
The ‘’ field uses the same syntax as ‘’ and lists packages that are not necessarily needed. This includes packages used only in examples, tests or vignettes (see Writing package vignettes), and packages loaded in the body of functions. E.g., suppose an example11 from package foo uses a dataset from package bar. Then it is not necessary to have bar use foo unless one wants to execute all the examples/tests/vignettes: it is useful to have bar, but not necessary. Version requirements can be specified but should be checked by the code which uses the package.
Finally, the ‘’ field lists packages “enhanced” by the package at hand, e.g., by providing methods for classes from these packages, or ways to handle objects from these packages (so several packages have ‘’ because they can handle datetime objects from chron even though they prefer R’s native datetime functions). Version requirements can be specified, but are currently not used. Such packages cannot be required to check the package: any tests which use them must be conditional on the presence of the package. (If your tests use e.g. a dataset from another package it should be in ‘’ and not ‘’.)
The general rules are
- A package should be listed in only one of these fields.
- Packages whose namespace only is needed to load the package using should be listed in the ‘’ field and not in the ‘’ field. Packages listed in or directives in the file should almost always be in ‘’ and not ‘’.
- Packages that need to be attached to successfully load the package using must be listed in the ‘’ field.
- All packages that are needed12 to successfully run on the package must be listed in one of ‘’ or ‘’ or ‘’. Packages used to run examples or tests conditionally (e.g. via) should be listed in ‘’ or ‘’. (This allows checkers to ensure that all the packages needed for a complete check are installed.)
In particular, packages providing “only” data for examples or vignettes should be listed in ‘’ rather than ‘’ in order to make lean installations possible.
Version dependencies in the ‘’ and ‘’ fields are used by when it loads the package, and checks versions for the ‘’, ‘’ and (for ) ‘’ fields.
It is increasingly important that the information in these fields is complete and accurate: it is for example used to compute which packages depend on an updated package and which packages can safely be installed in parallel.
This scheme was developed before all packages had namespaces (R 2.14.0 in October 2011), and good practice changed once that was in place.
Field ‘’ should nowadays be used rarely, only for packages which are intended to be put on the search path to make their facilities available to the end user (and not to the package itself): for example it makes sense that a user of package latticeExtra would want the functions of package lattice made available.
Almost always packages mentioned in ‘’ should also be imported from in the file: this ensures that any needed parts of those packages are available when some other package imports the current package.
The ‘’ field should not contain packages which are not imported from (via the file or or operators), as all the packages listed in that field need to be installed for the current package to be installed. (This is checked by .)
R code in the package should call or only exceptionally. Such calls are never needed for packages listed in ‘’ as they will already be on the search path. It used to be common practice to use calls for packages listed in ‘’ in functions which used their functionality, but nowadays it is better to access such functionality via calls.
A package that wishes to make use of header files in other packages needs to declare them as a comma-separated list in the field ‘’ in the file. For example
The ‘’ field can have a version requirement which is checked at installation.
Specifying a package in ‘’ suffices if these are C++ headers containing source code or static linking is done at installation: the packages do not need to be (and usually should not be) listed in the ‘’ or ‘’ fields. This includes package BH and almost all users of RcppArmadillo and RcppEigen.
For another use of ‘’ see Linking to native routines in other packages.
The ‘’ field is a comma-separated list of repository URLs where the packages named in the other fields may be found. It is currently used by to check that the packages can be found, at least as source packages (which can be installed on any platform).
188.8.131.52 Suggested packages
Note that someone wanting to run the examples/tests/vignettes may not have a suggested package available (and it may not even be possible to install it for that platform). The recommendation used to be to make their use conditional via: this is OK if that conditioning is done in examples/tests/vignettes, although using is preferred, if possible.
However, using for conditioning in package code is not good practice as it alters the search path for the rest of the session and relies on functions in that package not being masked by other or calls. It is better practice to use code like
Note the use of as that object would not necessarily be visible (and if it is, it need not be the one from that namespace: occurs in several other packages). If the intention is to give an error if the suggested package is not available, simply use e.g. .
Note that the recommendation to use suggested packages conditionally in tests does also apply to packages used to manage test suites: a notorious example was testthat which in version 1.0.0 contained illegal C++ code and hence could not be installed on standards-compliant platforms.
Some people have assumed that a ‘recommended’ package in ‘’ can safely be used unconditionally, but this is not so. (R can be installed without recommended packages, and which packages are ‘recommended’ may change.)
As noted above, packages in ‘’ must be used conditionally and hence objects within them should always be accessed via.
1.1.4 The file
The optional file contains a line for each sufficiently interesting object in the package, giving its name and a description (functions such as print methods not usually called explicitly might not be included). Normally this file is missing and the corresponding information is automatically generated from the documentation sources (using ) when installing from source.
The file is part of the information given by .
Rather than editing this file, it is preferable to put customized information about the package into an overview help page (see Documenting packages) and/or a vignette (see Writing package vignettes).
1.1.5 Package subdirectories
The subdirectory contains R code files, only. The code files to be installed must start with an (lower or upper case) letter or digit and have one of the extensions13, , , , or . We recommend using , as this extension seems to be not used by any other software. It should be possible to read in the files using , so R objects must be created by assignments. Note that there need be no connection between the name of the file and the R objects created by it. Ideally, the R code files should only directly assign R objects and definitely should not call functions with side effects such as and . If computations are required to create objects these can use code ‘earlier’ in the package (see the ‘’ field) plus functions in the ‘’ packages provided that the objects created do not depend on those packages except via namespace imports.
Two exceptions are allowed: if the subdirectory contains a file (a saved image of one or more R objects: please use suitable compression as suggested by , and see also the ‘’ field.) this will be lazy-loaded into the namespace environment – this is intended for system datasets that are not intended to be user-accessible via. Also, files ending in ‘’ will be allowed in the directory to allow a script to generate suitable files.
Only characters (and the control characters tab, formfeed, LF and CR) should be used in code files. Other characters are accepted in comments14, but then the comments may not be readable in e.g. a UTF-8 locale. Non- characters in object names will normally15 fail when the package is installed. Any byte will be allowed in a quoted character string but escapes should be used for non- characters. However, non- character strings may not be usable in some locales and may display incorrectly in others.
Various R functions in a package can be used to initialize and clean up. See Load hooks.
The subdirectory should contain (only) documentation files for the objects in the package in R documentation (Rd) format. The documentation filenames must start with an (lower or upper case) letter or digit and have the extension (the default) or . Further, the names must be valid in ‘’ URLs, which means16 they must be entirely and not contain ‘’. See Writing R documentation files, for more information. Note that all user-level objects in a package should be documented; if a package contains user-level objects which are for “internal” use only, it should provide a file which documents all such objects, and clearly states that these are not meant to be called by the user. See e.g. the sources for package grid in the R distribution. Note that packages which use internal objects extensively should not export those objects from their namespace, when they do not need to be documented (see Package namespaces).
Having a directory containing no documentation files may give an installation error.
The subdirectory may contain a subdirectory named ; this will contain source for user-defined Rd macros. (See User-defined macros.) These use the Rd format, but may not contain anything but macro definitions, comments and whitespace.
The and subdirectories may contain OS-specific subdirectories named or .
The sources and headers for the compiled code are in , plus optionally a file or . When a package is installed using , is used to control compilation and linking into a shared object for loading into R. There are default variables and rules for this (determined when R is configured and recorded in ), providing support for C, C++, FORTRAN 77, Fortran 9x17, Objective C and Objective C++18 with associated extensions , or , , or , , and , respectively. We recommend using for headers, also for C++19 or Fortran 9x include files. (Use of extension for C++ is no longer supported.) Files in the directory should not be hidden (start with a dot), and hidden files will under some versions of R be ignored.
It is not portable (and may not be possible at all) to mix all these languages in a single package, and we do not support using both C++ and Fortran 9x. Because R itself uses it, we know that C and FORTRAN 77 can be used together and mixing C and C++ seems to be widely successful.
If your code needs to depend on the platform there are certain defines which can used in C or C++. On all Windows builds (even 64-bit ones) ‘’ will be defined: on 64-bit Windows builds also ‘’, and on macOS ‘’ is defined.20
The default rules can be tweaked by setting macros21 in a file (see Using Makevars). Note that this mechanism should be general enough to eliminate the need for a package-specific . If such a file is to be distributed, considerable care is needed to make it general enough to work on all R platforms. If it has any targets at all, it should have an appropriate first target named ‘’ and a (possibly empty) target ‘’ which removes all files generated by running (to be used by ‘’ and ‘’). There are platform-specific file names on Windows: takes precedence over and must be used. Some programs require makefiles to have a complete final line, including a newline.
A few packages use the directory for purposes other than making a shared object (e.g. to create executables). Such packages should have files and (unless intended for only Unix-alikes or only Windows).
In very special cases packages may create binary files other than the shared objects/DLLs in the directory. Such files will not be installed in a multi-architecture setting since is used to merge multiple sub-architectures and it only copies shared objects/DLLs. If a package wants to install other binaries (for example executable programs), it should provide an R script which will be run as part of the installation in the build directory instead of copying the shared objects/DLLs. The script is run in a separate R environment containing the following variables: (the name of the package), (the path to the source directory of the package), (the path of the target installation directory of the package), (the arch-dependent part of the path, often empty), (the extension of shared objects) and ( on Windows, elsewhere). Something close to the default behavior could be replicated with the following file:
On the other hand, executable programs could be installed along the lines of
Note the use of architecture-specific subdirectories of where needed.
The subdirectory is for data files: See Data in packages.
The subdirectory is for R scripts (for running via) that demonstrate some of the functionality of the package. Demos may be interactive and are not checked automatically, so if testing is desired use code in the directory to achieve this. The script files must start with a (lower or upper case) letter and have one of the extensions or . If present, the subdirectory should also have a file with one line for each demo, giving its name and a description separated by a tab or at least three spaces. (This index file is not generated automatically.) Note that a demo does not have a specified encoding and so should be an file (see Encoding issues). Function will use the package encoding if there is one, but this is mainly useful for non- comments.
The contents of the subdirectory will be copied recursively to the installation directory. Subdirectories of should not interfere with those used by R (currently, , , , , , , , and , and earlier versions used , ). The copying of the happens after is built so its can create files to be installed. To exclude files from being installed, one can specify a list of exclude patterns in file in the top-level source directory. These patterns should be Perl-like regular expressions (see the help for in R for the precise details), one per line, to be matched case-insensitively against the file and directory paths, e.g. will exclude all PNG files in based on the extension.
Note that with the exceptions of , / and , information files at the top level of the package will not be installed and so not be known to users of Windows and macOS compiled packages (and not seen by those who use or on the tarball). So any information files you wish an end user to see should be included in . Note that if the named exceptions also occur in , the version in will be that seen in the installed package.
Things you might like to add to are a file for use by the function, and a file for use by the function. See its help page for the specific format restrictions of the file.
Another file sometimes needed in is or to specify the authors or copyright holders when this is too complex to put in the file.
Subdirectory is for additional package-specific test code, similar to the specific tests that come with the R distribution. Test code can either be provided directly in a (or as from R 3.4.0) file, or via a file containing code which in turn creates the corresponding file (e.g., by collecting all function objects in the package and then calling them with the strangest arguments). The results of running a file are written to a file. If there is a corresponding22 file, these two are compared, with differences being reported but not causing an error. The directory is copied to the check area, and the tests are run with the copy as the working directory and with set to ensure that the copy of the package installed during testing will be found by . Note that the package-specific tests are run in a vanilla R session without setting the random-number seed, so tests which use random numbers will need to set the seed to obtain reproducible results (and it can be helpful to do so in all cases, to avoid occasional failures when tests are run).
If directory has a subdirectory containing a file , this is compared to the output file for running the examples when the latter are checked. Reference output should be produced without having the option set (and note that sets it).
Subdirectory could contain additional executable scripts the package needs, typically scripts for interpreters such as the shell, Perl, or Tcl. NB: only files (and not directories) under are installed (and those with names starting with a dot are ignored), and they are all marked as executable (mode , moderated by ‘’) on POSIX platforms. Note too that this is not suitable for executable programs since some platforms (including Windows) support multiple architectures using the same installed package directory.
Subdirectory is used for files related to localization: see Internationalization.
Subdirectory is the preferred place for auxiliary files needed during configuration, and also for sources need to re-create scripts (e.g. M4 files for ).
1.1.6 Data in packages
The subdirectory is for data files, either to be made available via lazy-loading or for loading using . (The choice is made by the ‘’ field in the file: the default is not to do so.) It should not be used for other data files needed by the package, and the convention has grown up to use directory for such files.
Data files can have one of three types as indicated by their extension: plain R code ( or ), tables (, , or , see for the file formats, and note that is not the standard23