(R-exts.info)Creating R packages

---

Next: Writing R documentation files Prev: Acknowledgements Up: Top

---

Enter node , (file) or (file)node

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 'library()' command,
including its 'lib.loc' argument, and we also assume basic knowledge of
the 'R CMD INSTALL' utility.  Otherwise, please look at R's help pages
on

     ?library
     ?INSTALL

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
'R CMD INSTALL'.  Note: Add-on-packages.

   Other types of extensions are supported (but rare): Note: 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 'R CMD INSTALL' 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 *not*(1) a _library_.  The latter is used in two senses
in R documentation.

   * A directory into which packages are installed, e.g.
     '/usr/lib/R/library': 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
     '.so') and dynamic libraries (extension '.dylib').

   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 'R CMD INSTALL' or
     'install.packages'.

   * 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*): since R 3.5.0 this is enabled by default for all
     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 'library()', 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 'library'
     performs both steps, but a package's namespace can be loaded
     without the package being attached (for example by calls like
     'splines::ns').

   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 'R'
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, *note Lazy loading:
(R-ints)Lazy loading.)

   CRAN 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
CRAN: current instructions are linked from
<https://CRAN.R-project.org/banner.shtml#submitting>.

Package structure

Configure and cleanup

Checking and building packages

Writing package vignettes

Package namespaces

Writing portable packages

Diagnostic messages

Internationalization

CITATION files

Package types

Services

   ---------- Footnotes ----------

   (1) although this is a persistent mis-usage.  It seems to stem from
S, whose analogues of R's packages were officially known as _library
sections_ and later as _chapters_, but almost always referred to as
_libraries_.