This is R-exts.info, produced by makeinfo version 4.8 from R-exts.texi.

INFO-DIR-SECTION Programming
START-INFO-DIR-ENTRY
* R Extensions: (R-exts).      Writing R Extensions.
END-INFO-DIR-ENTRY


File: R-exts.info,  Node: Top,  Next: Acknowledgements,  Prev: (dir),  Up: (dir)

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 API.

   The current version of this document is 3.0.1 Patched (2013-05-26).



   Copyright (C) 1999-2013 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.

* Menu:

* Acknowledgements::
* Creating R packages::
* Writing R documentation files::
* Tidying and profiling R code::
* Debugging::
* System and foreign language interfaces::
* The R API::
* Generic functions and methods::
* Linking GUIs and other front-ends to R::
* Function and variable index::
* Concept index::


File: R-exts.info,  Node: Acknowledgements,  Next: Creating R packages,  Prev: Top,  Up: Top

Acknowledgements
****************

The contributions to early versions of this manual by Saikat DebRoy
(who wrote the first draft of a guide to using `.Call' and `.External')
and Adrian Trapletti (who provided information on the C++ interface)
are gratefully acknowledged.


File: R-exts.info,  Node: Creating R packages,  Next: Writing R documentation files,  Prev: Acknowledgements,  Up: Top

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: (R-admin)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, either 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 OS X 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 OS X) 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 DLL can both be loaded into the R process and
     be linked against), but OS X 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*): already the base and recommended packages are
     byte-compiled.  At some future time this might be done routinely,
     so _compiling_ a package may come to mean 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
`http://CRAN.R-project.org/banner.shtml#submitting'.

* Menu:

* 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_.


File: R-exts.info,  Node: Package structure,  Next: Configure and cleanup,  Prev: Creating R packages,  Up: Creating R packages

1.1 Package structure
=====================

The sources of an R package consists of a subdirectory containing a
files `DESCRIPTION' and `NAMESPACE', and the subdirectories `R',
`data', `demo', `exec', `inst', `man', `po', `src', `tests' and
`vignettes' (some of which can be missing, but which should not be
empty).  The package subdirectory may also contain files `INDEX',
`configure', `cleanup', `LICENSE', `LICENCE' and `NEWS'.  Other files
such as `INSTALL' (for non-standard installation instructions),
`README' or `ChangeLog' will be ignored by R, but may be useful to end
users.

   Except where specifically mentioned,(1) packages should not contain
Unix-style `hidden' files/directories (that is, those whose name starts
with a dot).

   The `DESCRIPTION' and `INDEX' files are described in the subsections
below.  The `NAMESPACE' file is described in the section on *Note
Package namespaces::.

   The optional files `configure' and `cleanup' are (Bourne shell)
script files which are, respectively, executed before and (provided
that option `--clean' was given) after installation on Unix-alikes, see
*Note Configure and cleanup::.  The analogues on Windows are
`configure.win' and `cleanup.win'.

   For the conventions for files `NEWS' and `ChangeLog' in the GNU
project see
`http://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 `foo', do
not also create a package named `Foo'.

   To ensure that file names are valid across file systems and supported
operating systems, the ASCII control characters as well as the
characters `"', `*', `:', `/', `<', `>', `?', `\', and `|' are not
allowed in file names.  In addition, files with names `con', `prn',
`aux', `clock$', `nul', `com1' to `com9', and `lpt1' to `lpt9' after
conversion to lower case and stripping possible "extensions" (e.g.,
`lpt5.foo.bar'), are disallowed.  Also, file names in the same
directory must not differ only by case (see the previous paragraph).
In addition, the basenames of `.Rd' files may be used in URLs and so
must be ASCII and not contain `%'.  For maximal portability filenames
should only contain only ASCII characters not excluded already (that is
`A-Za-z0-9._!#$%&+,;=@^(){}'[]' -- 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 `(){}'[]$~'.  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.  `R CMD check' will warn about them(2) unless
they are listed (one filepath per line) in a file `BinaryFiles' at the
top level of the package.  Note that CRAN will not accept submissions
containing binary files even if they are listed.

   The R function `package.skeleton' can help to create the structure
for a new package: see its help page for details.

* Menu:

* The DESCRIPTION file::
* Licensing::
* The INDEX file::
* Package subdirectories::
* Data in packages::
* Non-R scripts in packages::

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

   (1) currently, top-level files `.Rbuildignore' and `.Rinstignore',
and `vignettes/.install_extras'.

   (2) false positives are possible, but only a handful have been seen
so far.


File: R-exts.info,  Node: The DESCRIPTION file,  Next: Licensing,  Prev: Package structure,  Up: Package structure

1.1.1 The `DESCRIPTION' file
----------------------------

The `DESCRIPTION' file contains basic information about the package in
the following format:

          Package: pkgname
          Version: 0.5-1
          Date: 2004-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 and Pat Developer, with contributions from A. User
          Maintainer: Joe Developer <Joe.Developer@some.domain.net>
          Depends: R (>= 1.8.0), nlme
          Suggests: MASS
          Description: A short (one paragraph) description of what
            the package does and why it may be useful.
          License: GPL (>= 2)
          URL: http://www.r-project.org, http://www.another.url
          BugReports: http://pkgname.bugtracker.url

The format is that of a version of a `Debian Control File' (see the help
for `read.dcf' and
`http://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 ASCII 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 `DESCRIPTION' file should be written
entirely in ASCII -- if this is not possible it must contain an
`Encoding' field (see below).

   Several optional fields take _logical values_: these can be
specified as `yes', `true', `no' or `false': capitalized values are
also accepted.

   The `Package', `Version', `License', `Description', `Title',
`Author', and `Maintainer' fields are mandatory, all other fields are
optional.  Fields `Author' and `Maintainer' can be auto-generated from
`Authors@R', and may be omitted if the latter is provided: however if
they are not ASCII we recommend that they are provided.

   The mandatory `Package' field gives the name of the package.  This
should contain only (ASCII) letters, numbers and dot, have at least two
characters and start with a letter and not end in a dot.

   The mandatory `Version' 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 `0.01' or `0.01.0'
will be handled as if it were `0.1-0'.  It is *not* a decimal number,
so for example `0.9 < 0.75' since `9 < 75'.

   The mandatory `License' field is discussed in the next subsection.

   The mandatory `Description' field should give a comprehensive
description of what the package does.  One can use several (complete)
sentences, but only one paragraph.

   The mandatory `Title' field should give a short description of the
package. Some package listings may truncate the title to 65 characters.
It should be capitalized, not use any markup, not have any continuation
lines, and not end in a period.

   The mandatory `Author' 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 `Authors@R').  Note that all significant
contributors must be included: if you wrote an R wrapper for the work
of others included in the `src' directory, you are not the sole (and
maybe not even the main) author.

   The mandatory `Maintainer' field should give a _single_ name
followed 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 `maintainer' function and used by `bug.report'.  For a CRAN 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.

   Both `Author' and `Maintainer' fields can be omitted if a suitable
`Authors@R' 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.  The
roles can include `"aut"' (author) for full authors, `"cre"' (creator)
for the package maintainer, and `"ctb"' (contributor) for other
contributors, `"cph"' (copyright holder), among others.  See `?person'
for more information.  Note that no role is assumed by default.
Auto-generated package citation information takes advantage of this
specification. The `Author' and `Maintainer' fields are auto-generated
from it if needed when building(1) or installing.

   An optional `Copyright' 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 `inst/COPYRIGHTS'.

   The `Date' field gives the release date of the current version of
the package.  It is strongly recommended to use the yyyy-mm-dd format
conforming to the ISO 8601 standard.

   The `Depends' field gives a comma-separated list of package names
which this package depends on.  The package name may be optionally
followed by a comment in parentheses.  The comment should contain a
comparison operator, whitespace and a valid version number.  You can
also use the special package name `R' if your package depends on a
certain version of R -- e.g., if the package works only with R version
3.0.0 or later, include `R (>= 3.0.0)' in the `Depends' field.  You can
also require a certain SVN revision for R-devel or R-patched, e.g. `R
(>= 2.14.0), R (>= r56550)' requires a version later than R-devel of
late July 2011 (including released versions of 2.14.0).  Both `library'
and the R package checking facilities use this field: hence it is an
error to use improper syntax or misuse the `Depends' field for comments
on other software that might be needed.  Other dependencies (external
to the R system) should be listed in the `SystemRequirements' field,
possibly amplified in a separate `README' file.  The R `INSTALL'
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, both when `library' is called and when preparing for
lazy-loading during installation.

   A package (or `R') can appear more than once in the `Depends' field.

   It makes no sense to declare a dependence on `R' without a version
specification, nor on the package *base*: this is an R package and
*base* is always available.

   The `Imports' field lists packages whose namespaces are imported
from (as specified in the `NAMESPACE' file) but which do not need to be
attached.  Namespaces accessed by the `::' and `:::' operators must be
listed here, or in `Suggests' or `Enhances' (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 `DESCRIPTION' file is used to decide which packages to
re-install when this happens).  Packages declared in the `Depends'
field should not also be in the `Imports' field.  Version requirements
can be specified and are checked when the namespace is loaded (but only
in R >= 3.0.0).

   The `Suggests' field uses the same syntax as `Depends' and lists
packages that are not necessarily needed.  This includes packages used
only in examples, tests or vignettes (*note Writing package
vignettes::), and packages loaded in the body of functions.  E.g.,
suppose an example 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, and
will be used by `R CMD check'.  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), so
it is desirable that the use of suggested packages is made conditional
_via_ `if(require(PKGNAME))').

   Finally, the `Enhances' 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 `Enhances: chron' because they can handle datetime
objects from *chron* (http://CRAN.R-project.org/package=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
`Suggests' and not `Enhances'.)

   The general rules are

   * Packages whose namespace only is needed to load the package using
     `library(PKGNAME)' must be listed in the `Imports' field and not
     in the `Depends' field.

   * Packages that need to be attached to successfully load the package
     using `library(PKGNAME)' must be listed in the `Depends' field,
     only.

   * All packages that are needed(2) to successfully run `R CMD check'
     on the package must be listed in one of `Depends' or `Suggests' or
     `Imports'.  Packages used to run examples or tests conditionally
     (e.g. _via_ `if(require(PKGNAME))') should be listed in `Suggests'
     or `Enhances'.  (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 `Suggests' rather than `Depends' in order to make
lean installations possible.

   Version dependencies in the `Depends' and `Imports' fields are used
by `library' when it loads the package, and `install.packages' checks
versions for the `Depends', `Imports' and (for `dependencies = TRUE')
`Suggests' 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.

   The `URL' field may give a list of URLs 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 URLs
are converted to active hyperlinks in CRAN package listings.

   The `BugReports' field may contain a single URL to which bug reports
about the package should be submitted.  This URL will be used by
`bug.reports' instead of sending an email to the maintainer.

   Base and recommended packages (i.e., packages contained in the R
source distribution or available from CRAN and recommended to be
included in every binary distribution of R) have a `Priority' field
with value `base' or `recommended', respectively.  These priorities
must not be used by other packages.

   A `Collate' 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 `C' locale.
If present, the collate specification must list _all_ R code files in
the package (taking possible OS-specific subdirectories into account,
see *Note Package subdirectories::) as a whitespace separated list of
file paths relative to the `R' subdirectory.  Paths containing white
space or quotes need to be quoted.  An OS-specific collation field
(`Collate.unix' or `Collate.windows') will be used in preference to
`Collate'.

   The `LazyData' logical field controls whether the R datasets use
lazy-loading.  A `LazyLoad' field was used in versions prior to 2.14.0,
but now is ignored.

   The `KeepSource' logical field controls if the package code is
sourced using `keep.source = TRUE' or `FALSE': it might be needed
exceptionally for a package designed to always be used with
`keep.source = TRUE'.

   The `ByteCompile' logical field controls if the package code is
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).

   The `ZipData' 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 ignored.

   The `Biarch' logical field is used on Windows to select the
`INSTALL' option `--force-biarch' for this package.  (Introduced in R
3.0.0.)

   The `BuildVignettes' logical field can be set to a false value to
stop `R CMD build' from attempting to rebuild the vignettes, as well as
preventing `R CMD check' 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 `VignetteBuilder' field names a package that provides an engine
other than Sweave for building vignettes.  This may be the current
package, or one listed in `Depends', `Suggests' or `Imports'.  See
*Note Non-Sweave vignettes:: for details.

   If the `DESCRIPTION' file is not entirely in ASCII it should contain
an `Encoding' field specifying an encoding.  This is used as the
encoding of the `DESCRIPTION' file itself and of the `R' and
`NAMESPACE' files, and as the default encoding of `.Rd' files.  The
examples are assumed to be in this encoding when running `R CMD check',
and it is used for the encoding of the `CITATION' file.  Only encoding
names `latin1', `latin2' and `UTF-8' 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 `R CMD build' etc in a locale using that encoding.)

   The `NeedsCompilation' field should be set to `"yes"' if the package
contains code which to be compiled, otherwise `"no"' (when the package
could be installed from source on any platform without additional
tools).  This is used by `install.packages(type = "both")' in R >=
2.15.2 on platforms where binary packages are the norm: it is normally
set by the repository assuming compilation is required if and only if
the package has a `src' directory.

   The `OS_type' field specifies the OS(es) for which the package is
intended.  If present, it should be one of `unix' or `windows', and
indicates that the package can only be installed on a platform with
`.Platform$OS.type' having that value.

   The `Type' field specifies the type of the package: *note Package
types::.

   One can add subject classifications for the content of the package
using the fields `Classification/ACM' (using the Computing
Classification System of the Association for Computing Machinery,
`http://www.acm.org/class/'), `Classification/JEL' (the Journal of
Economic Literature Classification System,
`http://www.aeaweb.org/journal/jel_class_system.html'), or
`Classification/MSC' (the Mathematics Subject Classification of the
American Mathematical Society, `http://www.ams.org/msc/').  The subject
classifications should be comma-separated lists of the respective
classification codes, e.g., `Classification/ACM: G.4, H.2.8, I.5.1'.

   A `Language' 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 (`http://tools.ietf.org/html/rfc5646',
see also `http://en.wikipedia.org/wiki/IETF_language_tag'), i.e., use
language subtags which in essence are 2-letter ISO 639-1
(`http://en.wikipedia.org/wiki/ISO_639-1') or 3-letter ISO 639-3
(`http://en.wikipedia.org/wiki/ISO_639-3') language codes.

     Note: There should be no `Built' or `Packaged' 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 `Note', `Contact' (for contacting the
authors/developers) and `MailingList' are in common use. Some
repositories (including CRAN and R-forge) add their own fields.

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

   (1) at least if this is done in a locale which matches the package
encoding.

   (2) This includes all packages directly called by `library' and
`require' calls, as well as data obtained _via_ `data(theirdata,
package = "somepkg")' calls: `R CMD check' will warn about all of
these.  But there are subtler uses which it will not detect: e.g. if
package A uses package B and makes use of functionality in package B
which uses package C which package B suggests or enhances, then package
C needs to be in the `Suggests' list for package A.  Nor will
undeclared uses in included files be reported, nor unconditional uses
of packages listed under `Enhances'.


File: R-exts.info,  Node: Licensing,  Next: The INDEX file,  Prev: The DESCRIPTION file,  Up: Package structure

1.1.2 Licensing
---------------

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., `http://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 `License' field for information on copyright holders:
if needed, use a `Copyright' field.

   The mandatory `License' field in the `DESCRIPTION' 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 _via_ `http://www.R-project.org/Licenses/' and
     contained in subdirectory `share/licenses' of the R source or home
     directory.

   * The names or abbreviations of other licenses contained in the
     license data base in file `share/licenses/license.db' in the R
     source or home directory, possibly (for versioned licenses)
     followed by a version restriction of the form `(OP V)' with `OP'
     one of the comparison operators `<', `<=', `>', `>=', `==', or
     `!=' and `V' 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 `GPL' and `LGPL' are ambiguous and usually taken to
     mean any version of the license: but it is better not to use them.

   * One of the strings `file LICENSE' or `file LICENCE' referring to a
     file named `LICENSE' or `LICENCE' in the package (source and
     installation) top-level directory.

   * The string `Unlimited', 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 `LICENSE' (or `LICENCE'), and the string
`+ file LICENSE' (or `+ file LICENCE', 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
     License: GPL-2
     License: GPL (>= 2) | BSD
     License: LGPL (>= 2.0, < 3) | Mozilla Public License
     License: GPL-2 | file LICENCE
     License: Artistic-2.0 | AGPL-3 + file LICENSE
   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 `DESCRIPTION' file.

   Fields `License_is_FOSS' and `License_restricts_use' may be added by
repositories where information cannot be computed from the name of the
license.  `License_is_FOSS: yes' is used for licenses which are known
to be FOSS, and `License_restricts_use' can have values `yes' or `no'
if the `LICENSE' file is known to restrict users or usage, or known not
to.  These are used by, e.g., the `available.packages' filters.

   The optional file `LICENSE'/`LICENCE' contains a copy of the license
to the package.  To avoid any confusion only include such a file if it
is referred to in the `License' field of the `DESCRIPTION' 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 GNU `COPYING' or `COPYING.LIB' files but refer to the
copies on `http://www.R-project.org/Licenses/' and included in the R
distribution (in directory `share/licenses').  Since files named
`LICENSE' or `LICENCE' _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
`LICENSE.note'.

   A few "standard" licenses are rather license templates which need
additional information to be completed _via_ `+ file LICENSE'.


File: R-exts.info,  Node: The INDEX file,  Next: Package subdirectories,  Prev: Licensing,  Up: Package structure

1.1.3 The `INDEX' file
----------------------

The optional file `INDEX' 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 `tools::Rdindex()') when installing from source.

   The file is part of the information given by `library(help =
PKGNAME)'.

   Rather than editing this file, it is preferable to put customized
information about the package into an overview help page (*note
Documenting packages::) and/or a vignette (*note Writing package
vignettes::).


File: R-exts.info,  Node: Package subdirectories,  Next: Data in packages,  Prev: The INDEX file,  Up: Package structure

1.1.4 Package subdirectories
----------------------------

The `R' subdirectory contains R code files, only.  The code files to be
installed must start with an ASCII (lower or upper case) letter or
digit and have one of the extensions(1) `.R', `.S', `.q', `.r', or
`.s'.  We recommend using `.R', as this extension seems to be not used
by any other software.  It should be possible to read in the files
using `source()', 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 `require' and `options'.  If computations are required
to create objects these can use code `earlier' in the package (see the
`Collate' field) plus functions in the `Depends' packages provided that
the objects created do not depend on those packages except _via_
namespace imports.

   Two exceptions are allowed: if the `R' subdirectory contains a file
`sysdata.rda' (a saved image of one or more R objects: please use
suitable compression as suggested by `tools::resaveRdaFiles') this will
be lazy-loaded into the namespace environment - this is intended for
system datasets that are not intended to be user-accessible _via_
`data'.  Also, files ending in `.in' will be allowed in the `R'
directory to allow a `configure' script to generate suitable files.

   Only ASCII characters (and the control characters tab, formfeed, LF
and CR) should be used in code files.  Other characters are accepted in
comments, but then the comments may not be readable in e.g. a UTF-8
locale.  Non-ASCII characters in object names will normally(2) fail
when the package is installed.  Any byte will be allowed in a quoted
character string but `\uxxxx' escapes should be used for non-ASCII
characters.  However, non-ASCII 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.  *Note Load hooks::.

   The `man' subdirectory should contain (only) documentation files for
the objects in the package in "R documentation" (Rd) format.  The
documentation filenames must start with an ASCII (lower or upper case)
letter or digit and have the extension `.Rd' (the default) or `.rd'.
Further, the names must be valid in `file://' URLs, which means(3) they
must be entirely ASCII and not contain `%'.  *Note Writing R
documentation files::, for more information.  Note that all user-level
objects in a package should be documented; if a package PKG contains
user-level objects which are for "internal" use only, it should provide
a file `PKG-internal.Rd' 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 (*note
Package namespaces::).

   Having a `man' directory containing no documentation files may give
an installation error.

   The `R' and `man' subdirectories may contain OS-specific
subdirectories named `unix' or `windows'.

   The sources and headers for the compiled code are in `src', plus
optionally a file `Makevars' or `Makefile'.  When a package is
installed using `R CMD INSTALL', `make' is used to control compilation
and linking into a shared object for loading into R.  There are default
`make' variables and rules for this (determined when R is configured
and recorded in `R_HOME/etcR_ARCH/Makeconf'), providing support for C,
C++, FORTRAN 77, Fortran 9x(4), Objective C and Objective C++(5) with
associated extensions `.c', `.cc' or `.cpp', `.f', `.f90' or `.f95',
`.m', and `.mm', respectively.  We recommend using `.h' for headers,
also for C++(6) or Fortran 9x include files.  (Use of extension `.C' for
C++ is no longer supported.)  Files in the `src' 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) `WIN32' will be defined: on 64-bit Windows builds also `WIN64',
and on OS X `__APPLE__' is defined.(7)

   The default rules can be tweaked by setting macros(8) in a file
`src/Makevars' (*note Using Makevars::).  Note that this mechanism
should be general enough to eliminate the need for a package-specific
`src/Makefile'.  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 `all' and a (possibly empty) target `clean' which removes all
files generated by running `make' (to be used by `R CMD INSTALL
--clean' and `R CMD INSTALL --preclean').  There are platform-specific
file names on Windows: `src/Makevars.win' takes precedence over
`src/Makevars' and `src/Makefile.win' must be used.  Some `make'
programs require makefiles to have a complete final line, including a
newline.

   A few packages use the `src' directory for purposes other than
making a shared object (e.g. to create executables).  Such packages
should have files `src/Makefile' and `src/Makefile.win' (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 `src' directory.  Such files will not be
installed in a multi-arch setting since `R CMD INSTALL --libs-only' is
used to merge multiple 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
`src/install.libs.R' which will be run as part of the installation in
the `src' build directory _instead of_ copying the shared objects/DLLs.
The script is run in a separate R environment containing the following
variables: `R_PACKAGE_NAME' (the name of the package),
`R_PACKAGE_SOURCE' (the path to the source directory of the package),
`R_PACKAGE_DIR' (the path of the target installation directory of the
package), `R_ARCH' (the arch-dependent part of the path), `SHLIB_EXT'
(the extension of shared objects) and `WINDOWS' (`TRUE' on Windows,
`FALSE' elsewhere).  Something close to the default behavior could be
replicated with the following `src/install.libs.R' file:

     files <- Sys.glob(paste("*", SHLIB_EXT, sep=''))
     libarch <- if (nzchar(R_ARCH)) paste('libs', R_ARCH, sep='') else 'libs'
     dest <- file.path(R_PACKAGE_DIR, libarch)
     dir.create(dest, recursive = TRUE, showWarnings = FALSE)
     file.copy(files, dest, overwrite = TRUE)
     if(file.exists("symbols.rds"))
         file.copy("symbols.rds", dest, overwrite = TRUE)

   The `data' subdirectory is for data files: *Note Data in packages::.

   The `demo' subdirectory is for R scripts (for running _via_
`demo()') 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 `tests' directory to achieve this.
The script files must start with a (lower or upper case) letter and
have one of the extensions `.R' or `.r'.  If present, the `demo'
subdirectory should also have a `00Index' file with one line for each
demo, giving its name and a description separated by white space. (Note
that it is not possible to generate this index file automatically.)
Note that a demo does not have a specified encoding and so should be an
ASCII file (*note Encoding issues::).  As from R 3.0.0 `demo()' will
use the package encoding if there is one, but this is mainly useful for
non-ASCII comments.

   The contents of the `inst' subdirectory will be copied recursively
to the installation directory.  Subdirectories of `inst' should not
interfere with those used by R (currently, `R', `data', `demo', `exec',
`libs', `man', `help', `html' and `Meta', and earlier versions used
`latex', `R-ex').  The copying of the `inst' happens after `src' is
built so its `Makefile' can create files to be installed.  To exclude
files from being installed, one can specify a list of exclude patterns
in file `.Rinstignore' in the top-level source directory.  These
patterns should be Perl-like regular expressions (see the help for
`regexp' in R for the precise details), one per line, to be matched(9)
against the file and directory paths, e.g. `doc/.*[.]png$' will exclude
all PNG files in `inst/doc' based on the (lower-case) extension.

   Note that with the exceptions of `INDEX', `LICENSE'/`LICENCE' and
`NEWS', information files at the top level of the package will _not_ be
installed and so not be known to users of Windows and OS X compiled
packages (and not seen by those who use `R CMD INSTALL' or
`install.packages' on the tarball).  So any information files you wish
an end user to see should be included in `inst'.  Note that if the
named exceptions also occur in `inst', the versions in `inst' will be
that seen in the installed package.

   Things you might like to add to `inst' are a `CITATION' file for use
by the `citation' function, and a `NEWS.Rd' file for use by the `news'
function.

   Another file sometimes needed in `inst' is `AUTHORS' or `COPYRIGHTS'
to specify the authors or copyright holders when this is too complex to
put in the `DESCRIPTION' file.

   Subdirectory `tests' 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 `.R' file, or _via_ a `.Rin'
file containing code which in turn creates the corresponding `.R' file
(e.g., by collecting all function objects in the package and then
calling them with the strangest arguments).  The results of running a
`.R' file are written to a `.Rout' file.  If there is a
corresponding(10) `.Rout.save' file, these two are compared, with
differences being reported but not causing an error.  The directory
`tests' is copied to the check area, and the tests are run with the
copy as the working directory and with `R_LIBS' set to ensure that the
copy of the package installed during testing will be found by
`library(PKG_NAME)'.  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 `tests' has a subdirectory `Examples' containing a file
`PKG-Ex.Rout.save', this is compared to the output file for running the
examples when the latter are checked.  Reference output should be
produced without having the `--timings' option set.

   Subdirectory `exec' could contain additional executable scripts the
package needs, typically scripts for interpreters such as the shell,
Perl, or Tcl.  This mechanism is currently used only by a very few
packages.  NB: only files (and not directories) under `exec' are
installed (and those with names starting with a dot are ignored), and
they are all marked as executable (mode `755', moderated by `umask') on
POSIX platforms.  Note too that this may not be suitable for executable
_programs_ since some platforms (including OS X and Windows) support
multiple architectures using the same installed package directory.

   Subdirectory `po' is used for files related to _localization_: *note
Internationalization::.

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

   (1) Extensions `.S' and `.s' arise from code originally written for
S(-PLUS), but are commonly used for assembler code.  Extension `.q' was
used for S, which at one time was tentatively called QPE.

   (2) This is true for OSes which implement the `C' locale: Windows'
idea of the `C' locale uses the WinAnsi charset.

   (3) More precisely, they can contain the English alphanumeric
characters and the symbols `$ - _ . + ! ' ( ) , ;  = &'.

   (4) Note that Ratfor is not supported.  If you have Ratfor source
code, you need to convert it to FORTRAN.  Only FORTRAN 77 (which we
write in upper case) is supported on all platforms, but most also
support Fortran-95 (for which we use title case).  If you want to ship
Ratfor source files, please do so in a subdirectory of `src' and not in
the main subdirectory.

   (5) either or both of which may not be supported on particular
platforms

   (6) Using `.hpp' is not guaranteed to be portable.

   (7) There is also `__APPLE_CC__', but that indicates a compiler with
Apple-specific features, not the OS.  It is used in `Rinlinedfuns.h'.

   (8) the POSIX terminology, called `make variables' by GNU make.

   (9) case-insensitively on Windows.

   (10) The best way to generate such a file is to copy the `.Rout'
from a successful run of `R CMD check'.  If you want to generate it
separately, do run R with options `--vanilla --slave' and with
environment variable `LANGUAGE=en' set to get messages in English.


File: R-exts.info,  Node: Data in packages,  Next: Non-R scripts in packages,  Prev: Package subdirectories,  Up: Package structure

1.1.5 Data in packages
----------------------

The `data' subdirectory is for data files, either to be made available
_via_ lazy-loading or for loading using `data()'.  (The choice is made
by the `LazyData' field in the `DESCRIPTION' 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
`inst/extdata' for such files.

   Data files can have one of three types as indicated by their
extension: plain R code (`.R' or `.r'), tables (`.tab', `.txt', or
`.csv', see `?data' for the file formats, and note that `.csv' is *not*
the standard(1) CSV format), or `save()' images (`.RData' or `.rda').
The files should not be hidden (have names starting with a dot).  Note
that R code should be "self-sufficient" and not make use of extra
functionality provided by the package, so that the data file can also
be used without having to load the package or its namespace.

   Images (extensions `.RData' or `.rda') can contain references to the
namespaces of packages that were used to create them.  Preferably there
should be no such references in data files, and in any case they should
only be to packages listed in the `Depends' and `Imports' fields, as
otherwise it may be impossible to install the package.  To check for
such references, load all the images into a vanilla R session, and look
at the output of `loadedNamespaces()'.

   If your data files are large and you are not using `LazyData' you
can speed up installation by providing a file `datalist' in the `data'
subdirectory.  This should have one line per topic that `data()' will
find, in the format `foo' if `data(foo)' provides `foo', or `foo: bar
bah' if `data(foo)' provides `bar' and `bah'.  `R CMD build' will
automatically add a `datalist' file to `data' directories of over 1Mb,
using the function `tools::add_datalist'.

   Tables (`.tab', `.txt', or `.csv' files) can be compressed by
`gzip', `bzip2' or `xz', optionally with additional extension `.gz',
`.bz2' or `.xz'.

   If your package is to be distributed, do consider the resource
implications of large datasets for your users: they can make packages
very slow to download and use up unwelcome amounts of storage space, as
well as taking many seconds to load.  It is normally best to distribute
large datasets as `.rda' images prepared by `save(, compress = TRUE)'
(the default).  Using `bzip2' or `xz' compression will usually reduce
the size of both the package tarball and the installed package, in some
cases by a factor of two or more.

   Package *tools* has a couple of functions to help with data images:
`checkRdaFiles' reports on the way the image was saved, and
`resaveRdaFiles' will re-save with a different type of compression,
including choosing the best type for that particular image.

   Some packages using `LazyData' will benefit from using a form of
compression other than `gzip' in the installed lazy-loading database.
This can be selected by the `--data-compress' option to `R CMD INSTALL'
or by using the `LazyDataCompression' field in the `DESCRIPTION' file.
Useful values are `bzip2', `xz' and the default, `gzip'.  The only way
to discover which is best is to try them all and look at the size of the
`PKGNAME/data/Rdata.rdb' file.

   Lazy-loading is not supported for very large datasets (those which
when serialized exceed 2GB, the limit for the format on 32-bit
platforms and all platforms prior to R 3.0.0).

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

   (1) e.g `http://tools.ietf.org/html/rfc4180'.


File: R-exts.info,  Node: Non-R scripts in packages,  Prev: Data in packages,  Up: Package structure

1.1.6 Non-R scripts in packages
-------------------------------

Code which needs to be compiled (C, C++, FORTRAN, Fortran 95 ...)  is
included in the `src' subdirectory and discussed elsewhere in this
document.

   Subdirectory `exec' could be used for scripts for interpreters such
as the shell (e.g. *arulesSequences*
(http://CRAN.R-project.org/package=arulesSequences)), BUGS, Java,
JavaScript, Matlab, Perl (*FEST*
(http://CRAN.R-project.org/package=FEST)), php (*amap*
(http://CRAN.R-project.org/package=amap)), Python or Tcl, or even R.
However, it seems more common to use the `inst' directory, for example
`AMA/inst/java', `WriteXLS/inst/Perl', `Amelia/inst/tklibs',
`NMF/inst/matlab' and `emdbook/inst/BUGS'.

   If your package requires one of these interpreters or an extension
then this should be declared in the `SystemRequirements' field of its
`DESCRIPTION' file.  Windows and Mac users should be aware that the Tcl
extensions `BWidget' and `Tktable' which are currently included with
the R for Windows and OS X installers _are_ extensions and do need to
be declared.  `Tktable' did ship as part of the X11-based Tcl/Tk
provided on CRAN for OS X prior to R 3.0.0, but you will need to tell
your users how to make use of it:

     > addTclPath('/usr/local/lib/Tktable2.9')
     > tclRequire('Tktable')
     <Tcl> 2.9

It should work with no further user action as from R 3.0.0.

   `BWidget' needs to be installed by the user for OS X with R 2.x.y
and on other OSes.  This is fairly easy to do: first find the Tcl/Tk
search path:

     library(tcltk)
     strsplit(tclvalue('auto_path'), " ")[[1]]

then download the sources from
`http://sourceforge.net/projects/tcllib/files/BWidget/' and at the
command line run

     tar xf bwidget-1.9.6.tar.gz
     sudo mv bwidget-1.9.6 /usr/local/lib

substituting a location on the Tcl/Tk search path for `/usr/local/lib'
if needed.


File: R-exts.info,  Node: Configure and cleanup,  Next: Checking and building packages,  Prev: Package structure,  Up: Creating R packages

1.2 Configure and cleanup
=========================

Note that most of this section is specific to Unix-alikes: see the
comments later on about the Windows port of R.

   If your package needs some system-dependent configuration before
installation you can include an executable (Bourne shell) script
`configure' in your package which (if present) is executed by `R CMD
INSTALL' before any other action is performed.  This can be a script
created by the Autoconf mechanism, but may also be a script written by
yourself.  Use this to detect if any nonstandard libraries are present
such that corresponding code in the package can be disabled at install
time rather than giving error messages when the package is compiled or
used.  To summarize, the full power of Autoconf is available for your
extension package (including variable substitution, searching for
libraries, etc.).

   Under a Unix-alike only, an executable (Bourne shell) script
`cleanup' is executed as the last thing by `R CMD INSTALL' if option
`--clean' was given, and by `R CMD build' when preparing the package
for building from its source.  It can be used to clean up the package
source tree: in particular, it should remove all files created by
`configure'.

   As an example consider we want to use functionality provided by a (C
or FORTRAN) library `foo'.  Using Autoconf, we can create a configure
script which checks for the library, sets variable `HAVE_FOO' to `TRUE'
if it was found and to `FALSE' otherwise, and then substitutes this
value into output files (by replacing instances of `@HAVE_FOO@' in
input files with the value of `HAVE_FOO').  For example, if a function
named `bar' is to be made available by linking against library `foo'
(i.e., using `-lfoo'), one could use

     AC_CHECK_LIB(foo, FUN, [HAVE_FOO=TRUE], [HAVE_FOO=FALSE])
     AC_SUBST(HAVE_FOO)
     ......
     AC_CONFIG_FILES([foo.R])
     AC_OUTPUT

in `configure.ac' (assuming Autoconf 2.50 or later).

   The definition of the respective R function in `foo.R.in' could be

     foo <- function(x) {
         if(!@HAVE_FOO@)
           stop("Sorry, library 'foo' is not available"))
         ...

From this file `configure' creates the actual R source file `foo.R'
looking like

     foo <- function(x) {
         if(!FALSE)
           stop("Sorry, library 'foo' is not available"))
         ...

if library `foo' was not found (with the desired functionality).  In
this case, the above R code effectively disables the function.

   One could also use different file fragments for available and missing
functionality, respectively.

   You will very likely need to ensure that the same C compiler and
compiler flags are used in the `configure' tests as when compiling R or
your package.  Under a Unix-alike, you can achieve this by including
the following fragment early in `configure.ac'

     : ${R_HOME=`R RHOME`}
     if test -z "${R_HOME}"; then
       echo "could not determine R_HOME"
       exit 1
     fi
     CC=`"${R_HOME}/bin/R" CMD config CC`
     CFLAGS=`"${R_HOME}/bin/R" CMD config CFLAGS`
     CPPFLAGS=`"${R_HOME}/bin/R" CMD config CPPFLAGS`

(Using `${R_HOME}/bin/R' rather than just `R' is necessary in order to
use the correct version of R when running the script as part of `R CMD
INSTALL', and the quotes since `${R_HOME}' might contain spaces.)

   If your code does load checks then you may also need
     LDFLAGS=`"${R_HOME}/bin/R" CMD config LDFLAGS`

and packages written with C++ need to pick up the details for the C++
compiler and switch the current language to C++ by
     AC_LANG(C++)

The latter is important, as for example C headers may not be available
to C++ programs or may not be written to avoid C++ name-mangling.

   You can use `R CMD config' for getting the value of the basic
configuration variables, or the header and library flags necessary for
linking against R, see `R CMD config --help' for details.

   To check for an external BLAS library using the `ACX_BLAS' macro
from the official Autoconf Macro Archive, one can simply do

     F77=`"${R_HOME}/bin/R" CMD config F77`
     AC_PROG_F77
     FLIBS=`"${R_HOME}/bin/R" CMD config FLIBS`
     ACX_BLAS([], AC_MSG_ERROR([could not find your BLAS library], 1))

   Note that `FLIBS' as determined by R must be used to ensure that
FORTRAN 77 code works on all R platforms.  Calls to the Autoconf macro
`AC_F77_LIBRARY_LDFLAGS', which would overwrite `FLIBS', must not be
used (and hence e.g. removed from `ACX_BLAS').  (Recent versions of
Autoconf in fact allow an already set `FLIBS' to override the test for
the FORTRAN linker flags.)

   You should bear in mind that the configure script will not be used on
Windows systems.  If your package is to be made publicly available,
please give enough information for a user on a non-Unix-alike platform
to configure it manually, or provide a `configure.win' script to be
used on that platform.  (Optionally, there can be a `cleanup.win'
script.  Both should be shell scripts to be executed by `ash', which is
a minimal version of Bourne-style `sh'.)  When `configure.win' is run
the environment variables `R_HOME' (which uses `/' as the file
separator) and `R_ARCH' will be set.  Use `R_ARCH' to decide if this is
a 64-bit build (its value there is `/x64') and to install DLLs to the
correct place (`${R_HOME}/libs${R_ARCH}').  Use `R_ARCH_BIN' to find the
correct place under the `bin' directory, e.g.
`${R_HOME}/bin${R_ARCH_BIN}/Rscript.exe'.

   In some rare circumstances, the configuration and cleanup scripts
need to know the location into which the package is being installed.  An
example of this is a package that uses C code and creates two shared
object/DLLs.  Usually, the object that is dynamically loaded by R is
linked against the second, dependent, object.  On some systems, we can
add the location of this dependent object to the object that is
dynamically loaded by R.  This means that each user does not have to
set the value of the `LD_LIBRARY_PATH' (or equivalent) environment
variable, but that the secondary object is automatically resolved.
Another example is when a package installs support files that are
required at run time, and their location is substituted into an R data
structure at installation time. (This happens with the Java Archive
files in the Omegahat *SJava* package.)  The names of the top-level
library directory (i.e., specifiable _via_ the `-l' argument) and the
directory of the package itself are made available to the installation
scripts _via_ the two shell/environment variables `R_LIBRARY_DIR' and
`R_PACKAGE_DIR'.  Additionally, the name of the package (e.g.
`survival' or `MASS') being installed is available from the environment
variable `R_PACKAGE_NAME'.  (Currently the value of `R_PACKAGE_DIR' is
always `${R_LIBRARY_DIR}/${R_PACKAGE_NAME}', but this used not to be
the case when versioned installs were allowed.  Its main use is in
`configure.win' scripts for the installation path of external
software's DLLs.)  Note that the value of `R_PACKAGE_DIR' may contain
spaces and other shell-unfriendly characters, and so should be quoted
in makefiles and configure scripts.

   One of the more tricky tasks can be to find the headers and
libraries of external software.  One tool which is increasingly
available on Unix-alikes (but not by default on OS X) to do this is
`pkg-config'.  The `configure' script will need to test for the
presence of the command itself (see for example package *Cairo*
(http://CRAN.R-project.org/package=Cairo)), and if present it can be
asked if the software is installed, of a suitable version and for
compilation/linking flags by e.g.

     $ pkg-config --exists 'QtCore >= 4.0.0'  # check the status
     $ pkg-config --modversion QtCore
     4.7.1
     $ pkg-config --cflags QtCore
     -DQT_SHARED -I/usr/include/QtCore
     $ pkg-config --libs QtCore
     -lQtCore

Note that `pkg-config --libs' gives the information required to link
against the default version of that library (usually the dynamic one),
and `pkg-config --static' is needed if the static library is to be used.

   Sometimes the name by which the software is known to `pkg-config' is
not what one might expect (e.g.  `gtk+-2.0' even for 2.22).  To get a
complete list use

     pkg-config --list-all | sort

* Menu:

* Using Makevars::
* Configure example::
* Using F95 code::


File: R-exts.info,  Node: Using Makevars,  Next: Configure example,  Prev: Configure and cleanup,  Up: Configure and cleanup

1.2.1 Using `Makevars'
----------------------

* Menu:

* OpenMP support::
* Using pthreads::
* Compiling in sub-directories::

   Sometimes writing your own `configure' script can be avoided by
supplying a file `Makevars': also one of the most common uses of a
`configure' script is to make `Makevars' from `Makevars.in'.

   A `Makevars' file is a makefile and is used as one of several
makefiles by `R CMD SHLIB' (which is called by `R CMD INSTALL' to
compile code in the `src' directory).  It should be written if at all
possible in a portable style, in particular (except for `Makevars.win')
without the use of GNU extensions.

   The most common use of a `Makevars' file is to set additional
preprocessor options (for example include paths) for C/C++ files _via_
`PKG_CPPFLAGS', and additional compiler flags by setting `PKG_CFLAGS',
`PKG_CXXFLAGS', `PKG_FFLAGS' or `PKG_FCFLAGS', for C, C++, FORTRAN or
Fortran 9x respectively (*note Creating shared objects::).

   *NB:* Include paths are preprocessor options, not compiler options,
and *must* be set in `PKG_CPPFLAGS' as otherwise platform-specific
paths (e.g. `-I/usr/local/include') will take precedence.

   `Makevars' can also be used to set flags for the linker, for example
`-L' and `-l' options, _via_ `PKG_LIBS'.

   When writing a `Makevars' file for a package you intend to
distribute, take care to ensure that it is not specific to your
compiler: flags such as `-O2 -Wall -pedantic' are all specific to GCC.

   There are some macros(1)  which are set whilst configuring the
building of R itself and are stored in `R_HOME/etcR_ARCH/Makeconf'.
That makefile is included as a `Makefile' _after_ `Makevars[.win]', and
the macros it defines can be used in macro assignments and make command
lines in the latter.  These include

`FLIBS'
     A macro containing the set of libraries need to link FORTRAN code.
     This may need to be included in `PKG_LIBS': it will normally be
     included automatically if the package contains FORTRAN source
     files.

`BLAS_LIBS'
     A macro containing the BLAS libraries used when building R.  This
     may need to be included in `PKG_LIBS'.  Beware that if it is empty
     then the R executable will contain all the double-precision and
     double-complex BLAS routines, but no single-precision or complex
     routines.  If `BLAS_LIBS' is included, then `FLIBS' also needs to
     be(2) included following it, as most BLAS libraries are written at
     least partially in FORTRAN.

`LAPACK_LIBS'
     A macro containing the LAPACK libraries (and paths where
     appropriate) used when building R.  This may need to be included in
     `PKG_LIBS'.  It may point to a dynamic library `libRlapack' which
     contains all the double-precision LAPACK routines as well as those
     double-complex LAPACK and BLAS routines needed to build R, or it
     may point to an external LAPACK library, or may be empty if an
     external BLAS library also contains LAPACK.

     [There is no guarantee that the LAPACK library will provide more
     than all the double-precision and double-complex routines, and
     some do not provide all the auxiliary routines.]

     For portability, the macros `BLAS_LIBS' and `FLIBS' should always
     be included _after_ `LAPACK_LIBS' (and in that order).

`SAFE_FFLAGS'
     A macro containing flags which are needed to circumvent
     over-optimization of FORTRAN code: it is typically `-g -O2
     -ffloat-store' on `ix86' platforms using `gfortran'.  Note that
     this is *not* an additional flag to be used as part of
     `PKG_FFLAGS', but a replacement for `FFLAGS', and that it is
     intended for the FORTRAN 77 compiler `F77' and not necessarily for
     the Fortran 90/95 compiler `FC'.  See the example later in this
     section.

   Setting certain macros in `Makevars' will prevent `R CMD SHLIB'
setting them: in particular if `Makevars' sets `OBJECTS' it will not be
set on the `make' command line.  This can be useful in conjunction with
implicit rules to allow other types of source code to be compiled and
included in the shared object.  It can also be used to control the set
of files which are compiled, either by excluding some files in `src' or
including some files in subdirectories.  For example

     OBJECTS = 4dfp/endianio.o 4dfp/Getifh.o R4dfp-object.o

   Note that `Makevars' should not normally contain targets, as it is
included before the default makefile and `make' will call the first
target, intended to be `all' in the default makefile.  If you really
need to circumvent that, use a suitable (phony) target `all' before any
actual targets in `Makevars.[win]': for example package *fastICA*
(http://CRAN.R-project.org/package=fastICA) has

     PKG_LIBS = @BLAS_LIBS@

     SLAMC_FFLAGS=$(R_XTRA_FFLAGS) $(FPICFLAGS) $(SHLIB_FFLAGS) $(SAFE_FFLAGS)

     all: $(SHLIB)

     slamc.o: slamc.f
             $(F77) $(SLAMC_FFLAGS) -c -o slamc.o slamc.f

needed to ensure that the LAPACK routines find some constants without
infinite looping.  The Windows equivalent is

     all: $(SHLIB)

     slamc.o: slamc.f
             $(F77) $(SAFE_FFLAGS) -c -o slamc.o slamc.f

(since the other macros are all empty on that platform, and R's
internal BLAS is not used).  Note that the first target in `Makevars'
will be called, but for back-compatibility it is best named `all'.

   If you want to create and then link to a library, say using code in a
subdirectory, use something like

     .PHONY: all mylibs

     all: $(SHLIB)
     $(SHLIB): mylibs

     mylibs:
             (cd subdir; make)

Be careful to create all the necessary dependencies, as there is a no
guarantee that the dependencies of `all' will be run in a particular
order (and some of the CRAN build machines use multiple CPUs and
parallel makes).

   Note that on Windows it is required that `Makevars[.win]' does
create a DLL: this is needed as it is the only reliable way to ensure
that building a DLL succeeded.  If you want to use the `src' directory
for some purpose other than building a DLL, use a `Makefile.win' file.

   It is sometimes useful to have a target `clean' in `Makevars' or
`Makevars.win': this will be used by `R CMD build' to clean up (a copy
of) the package sources.  When it is run by `build' it will have fewer
macros set, in particular not `$(SHLIB)', nor `$(OBJECTS)' unless set
in the file itself.  It would also be possible to add tasks to the
target `shlib-clean' which is run by `R CMD INSTALL' and `R CMD SHLIB'
with options `--clean' and `--preclean'.

   If you want to run R code in `Makevars', e.g. to find configuration
information, please do ensure that you use the correct copy of `R' or
`Rscript': there might not be one in the path at all, or it might be
the wrong version or architecture.  The correct way to do this is _via_

     "$(R_HOME)/bin$(R_ARCH_BIN)/Rscript" FILENAME
     "$(R_HOME)/bin$(R_ARCH_BIN)/Rscript" -e 'R EXPRESSION'

where `$(R_ARCH_BIN)' is only needed currently on Windows.

   Environment or make variables can be used to select different macros
for 32- and 64-bit code, for example (GNU `make' syntax, allowed on
Windows)

     ifeq "$(WIN)" "64"
     PKG_LIBS = VALUE FOR 64-BIT WINDOWS
     else
     PKG_LIBS = VALUE FOR 32-BIT WINDOWS
     endif

   On Windows there is normally a choice between linking to an import
library or directly to a DLL.  Where possible, the latter is much more
reliable: import libraries are tied to a specific toolchain, and in
particular on 64-bit Windows two different conventions have been
commonly used.  So for example instead of

     PKG_LIBS = -L$(XML_DIR)/lib -lxml2

one can use

     PKG_LIBS = -L$(XML_DIR)/bin -lxml2

since on Windows `-lxxx' will look in turn for

     libxxx.dll.a
     xxx.dll.a
     libxxx.a
     xxx.lib
     libxxx.dll
     xxx.dll

where the first and second are conventionally import libraries, the
third and fourth often static libraries (with `.lib' intended for
Visual C++), but might be import libraries.  See for example
`http://sourceware.org/binutils/docs-2.20/ld/WIN32.html#WIN32'.

   The fly in the ointment is that the DLL might not be named
`libxxx.dll', and in fact on 32-bit Windows there is a `libxml2.dll'
whereas on one build for 64-bit Windows the DLL is called
`libxml2-2.dll'.  Using import libraries can cover over these
differences but can cause equal difficulties.

   If static libraries are available they can save a lot of problems
with run-time finding of DLLs, especially when binary packages are to be
distributed and even more when these support both architectures.  Where
using DLLs is unavoidable we normally arrange (_via_ `configure.win')
to ship them in the same directory as the package DLL.

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

   (1) in POSIX parlance: GNU `make' calls these `make variables'.

   (2) at least on Unix-alikes: the Windows build currently resolves
such dependencies to a static FORTRAN library when `Rblas.dll' is built.


File: R-exts.info,  Node: OpenMP support,  Next: Using pthreads,  Prev: Using Makevars,  Up: Using Makevars

1.2.1.1 OpenMP support
......................

There is some support for packages which wish to use OpenMP(1).  The
`make' macros

     SHLIB_OPENMP_CFLAGS
     SHLIB_OPENMP_CXXFLAGS
     SHLIB_OPENMP_FCFLAGS
     SHLIB_OPENMP_FFLAGS

are available for use in `src/Makevars' or `src/Makevars.win'.  Include
the appropriate macro in `PKG_CFLAGS', `PKG_CPPFLAGS' and so on, and
also in `PKG_LIBS'.  C/C++ code that needs to be conditioned on the use
of OpenMP can be used inside `#ifdef SUPPORT_OPENMP', a macro defined
in the header `Rconfig.h' (*note Platform and version information::) or
`_OPENMP': note that some toolchains used for R (e.g. `clang') have no
OpenMP support at all, not even `omp.h'.

   For example, a package with C code written for OpenMP should have in
`src/Makevars' the lines

     PKG_CFLAGS = $(SHLIB_OPENMP_CFLAGS)
     PKG_LIBS = $(SHLIB_OPENMP_CFLAGS)

   There is nothing to say what version of OpenMP is supported: version
3.0 (May 2008) is supported by recent versions of the Linux, Windows and
Solaris platforms, but portable packages cannot assume that end users
have recent versions (there are some years-old versions of Linux in
use), and it may be safest to assume version 2.5.  The compilers
currently used on OS X have partial support for OpenMP 2.5, but this is
not enabled in the CRAN build. (Apple have announced the imminent
discontinuation of support for those compilers, and the preferred
alternative, `clang', has no OpenMP support.)

   The performance of OpenMP varies substantially between platforms.
Both the Windows and OS X (where available) implementations have
substantial overheads and are only beneficial if quite substantial
tasks are run in parallel.

   Calling any of the R API from threaded code is `for experts only':
they will need to read the source code to determine if it is
thread-safe.  In particular, code which makes use of the stack-checking
mechanism must not be called from threaded code.

   Packages are not standard-alone programs, and an R process could
contain more than one OpenMP-enabled package as well as other components
(for example, an optimized BLAS) making use of OpenMP.  So careful
consideration needs to be given to resource usage.  OpenMP works with
parallel regions, and for most implementations the default is to use as
many threads as `CPUs' for such regions.  Parallel regions can be
nested, although it is common to use only a single thread below the
first level.  The detected number of `CPUs' and the assumption that the
R process is entitled to use them all are both dubious assumptions.
The best way to limit resources is to limit the overall number of
threads available to OpenMP in the R process: this can be done via
environment variable `OMP_THREAD_LIMIT', where implemented.(2)
Alternatively, the number of threads per region can be limited by the
environment variable `OMP_NUM_THREADS' or API call
`omp_set_num_threads', or, better, for the regions in your code as part
of their specification. E.g. R uses
     #pragma omp parallel for num_threads(nthreads) ...
   That way you only control your own code and not that of other OpenMP
users.

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

   (1) `http://www.openmp.org/', `http://en.wikipedia.org/wiki/OpenMP',
`https://computing.llnl.gov/tutorials/openMP/'

   (2) Which it was at the time of writing with GCC, Solaris Studio and
Intel compilers.


File: R-exts.info,  Node: Using pthreads,  Next: Compiling in sub-directories,  Prev: OpenMP support,  Up: Using Makevars

1.2.1.2 Using pthreads
......................

There is no direct support for the POSIX threads (more commonly known as
`pthreads'): by the time we considered adding it several packages were
using it unconditionally so it seems that nowadays it is universally
available on POSIX operating systems (hence not Windows).

   For reasonably recent versions of `gcc' and `clang' the correct
specification is

     PKG_CPPFLAGS = -pthread
     PKG_LIBS = -pthread

(and the plural version is also accepted on some systems/versions).  For
other platforms the specification is

     PKG_CPPFLAGS = -D_REENTRANT
     PKG_LIBS = -lpthread
   (and note that the library name is singular).  This is what
`-pthread' does on all known current platforms (although earlier
versions of OpenBSD used a different library name).

   For a tutorial see `https://computing.llnl.gov/tutorials/pthreads/'.

   POSIX threads are not normally used on Windows, which has its own
native concepts of threads.  However, there are two projects
implementing `pthreads' on top of Windows, `pthreads-w32' and
`winpthreads' (a recent part of the MinGW-w64 project).

   Whether Windows toolchains implement `pthreads' is up to the
toolchain provider: the currently recommended toolchain does by default
provide it.  A `make' variable `SHLIB_PTHREAD_FLAGS' is available: this
should be included in both `PKG_CPPFLAGS' (or the Fortran or F9x
equivalents) and `PKG_LIBS'.

   The presence of a working `pthreads' implementation cannot be
unambiguously determined without testing for yourself: however, that
`_REENTRANT' is defined(1) in C/C++ code is a good indication.

   See also the comments on thread-safety and performance under OpenMP:
on all known R platforms OpenMP is implemented _via_ `pthreads' and the
known performance issues are in the latter.

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

   (1) some Windows toolchains have the typo `_REENTRANCE' instead.


File: R-exts.info,  Node: Compiling in sub-directories,  Prev: Using pthreads,  Up: Using Makevars

1.2.1.3 Compiling in sub-directories
....................................

Package authors fairly often want to organize code in sub-directories of
`src', for example if they are including a separate piece of external
software to which this is an R interface.

   One simple way is simply to set `OBJECTS' to be all the objects that
need to be compiled, including in sub-directories.  For example, CRAN
package *RSiena* (http://CRAN.R-project.org/package=RSiena) has

     SOURCES = $(wildcard data/*.cpp network/*.cpp utils/*.cpp model/*.cpp model/*/*.cpp model/*/*/*.cpp)

     OBJECTS = siena07utilities.o siena07internals.o siena07setup.o siena07models.o $(SOURCES:.cpp=.o)

One problem with that approach is that unless GNU make extensions are
used, the source files need to be listed and kept up-to-date.  As in the
following from CRAN package *lossDev*
(http://CRAN.R-project.org/package=lossDev):

     OBJECTS.samplers = samplers/ExpandableArray.o samplers/Knots.o \
       samplers/RJumpSpline.o samplers/RJumpSplineFactory.o \
       samplers/RealSlicerOV.o samplers/SliceFactoryOV.o samplers/MNorm.o
     OBJECTS.distributions = distributions/DSpline.o \
       distributions/DChisqrOV.o distributions/DTOV.o \
       distributions/DNormOV.o distributions/DUnifOV.o distributions/RScalarDist.o
     OBJECTS.root = RJump.o

     OBJECTS = $(OBJECTS.samplers) $(OBJECTS.distributions) $(OBJECTS.root)

   Where the subdirectory is self-contained code with a suitable
makefile, the best approach is something like

     PKG_LIBS = -LCsdp/lib -lsdp $(LAPACK_LIBS) $(BLAS_LIBS) $(FLIBS)

     $(SHLIB): Csdp/lib/libsdp.a

     Csdp/lib/libsdp.a
             @(cd Csdp/lib && $(MAKE) libsdp.a \
               CC="$(CC)" CFLAGS="$(CFLAGS) $(CPICFLAGS)" AR="$(AR)" RANLIB="$(RANLIB)")

Note the quotes: the macros can contain spaces, e.g. `CC = "gcc -m64
-std=gnu99"'.  Several authors have forgotten about parallel makes: the
static library in the subdirectory must be made before the shared
object (`$(SHLIB)') and so the latter must depend on the former.
Others forget the need for position-independent code.

   We really do not recommend using a `src/Makefile' instead on
`src/Makevars', and as the example above shows, it is not necessary.


File: R-exts.info,  Node: Configure example,  Next: Using F95 code,  Prev: Using Makevars,  Up: Configure and cleanup

1.2.2 Configure example
-----------------------

It may be helpful to give an extended example of using a `configure'
script to create a `src/Makevars' file: this is based on that in the
*RODBC* (http://CRAN.R-project.org/package=RODBC) package.

   The `configure.ac' file follows: `configure' is created from this by
running `autoconf' in the top-level package directory (containing
`configure.ac').

          AC_INIT([RODBC], 1.1.8) dnl package name, version

          dnl A user-specifiable option
          odbc_mgr=""
          AC_ARG_WITH([odbc-manager],
                      AC_HELP_STRING([--with-odbc-manager=MGR],
                                     [specify the ODBC manager, e.g. odbc or iodbc]),
                      [odbc_mgr=$withval])

          if test "$odbc_mgr" = "odbc" ; then
            AC_PATH_PROGS(ODBC_CONFIG, odbc_config)
          fi

          dnl Select an optional include path, from a configure option
          dnl or from an environment variable.
          AC_ARG_WITH([odbc-include],
                      AC_HELP_STRING([--with-odbc-include=INCLUDE_PATH],
                                     [the location of ODBC header files]),
                      [odbc_include_path=$withval])
          RODBC_CPPFLAGS="-I."
          if test [ -n "$odbc_include_path" ] ; then
             RODBC_CPPFLAGS="-I. -I${odbc_include_path}"
          else
            if test [ -n "${ODBC_INCLUDE}" ] ; then
               RODBC_CPPFLAGS="-I. -I${ODBC_INCLUDE}"
            fi
          fi

          dnl ditto for a library path
          AC_ARG_WITH([odbc-lib],
                      AC_HELP_STRING([--with-odbc-lib=LIB_PATH],
                                     [the location of ODBC libraries]),
                      [odbc_lib_path=$withval])
          if test [ -n "$odbc_lib_path" ] ; then
             LIBS="-L$odbc_lib_path ${LIBS}"
          else
            if test [ -n "${ODBC_LIBS}" ] ; then
               LIBS="-L${ODBC_LIBS} ${LIBS}"
            else
              if test -n "${ODBC_CONFIG}"; then
                odbc_lib_path=`odbc_config --libs | sed s/-lodbc//`
                LIBS="${odbc_lib_path} ${LIBS}"
              fi
            fi
          fi

          dnl Now find the compiler and compiler flags to use
          : ${R_HOME=`R RHOME`}
          if test -z "${R_HOME}"; then
            echo "could not determine R_HOME"
            exit 1
          fi
          CC=`"${R_HOME}/bin/R" CMD config CC`
          CPP=`"${R_HOME}/bin/R" CMD config CPP`
          CFLAGS=`"${R_HOME}/bin/R" CMD config CFLAGS`
          CPPFLAGS=`"${R_HOME}/bin/R" CMD config CPPFLAGS`
          AC_PROG_CC
          AC_PROG_CPP


          if test -n "${ODBC_CONFIG}"; then
            RODBC_CPPFLAGS=`odbc_config --cflags`
          fi
          CPPFLAGS="${CPPFLAGS} ${RODBC_CPPFLAGS}"

          dnl Check the headers can be found
          AC_CHECK_HEADERS(sql.h sqlext.h)
          if test "${ac_cv_header_sql_h}" = no ||
             test "${ac_cv_header_sqlext_h}" = no; then
             AC_MSG_ERROR("ODBC headers sql.h and sqlext.h not found")
          fi

          dnl search for a library containing an ODBC function
          if test [ -n "${odbc_mgr}" ] ; then
            AC_SEARCH_LIBS(SQLTables, ${odbc_mgr}, ,
                AC_MSG_ERROR("ODBC driver manager ${odbc_mgr} not found"))
          else
            AC_SEARCH_LIBS(SQLTables, odbc odbc32 iodbc, ,
                AC_MSG_ERROR("no ODBC driver manager found"))
          fi

          dnl for 64-bit ODBC need SQL[U]LEN, and it is unclear where they are defined.
          AC_CHECK_TYPES([SQLLEN, SQLULEN], , , [# include <sql.h>])
          dnl for unixODBC header
          AC_CHECK_SIZEOF(long, 4)

          dnl substitute RODBC_CPPFLAGS and LIBS
          AC_SUBST(RODBC_CPPFLAGS)
          AC_SUBST(LIBS)
          AC_CONFIG_HEADERS([src/config.h])
          dnl and do substitution in the src/Makevars.in and src/config.h
          AC_CONFIG_FILES([src/Makevars])
          AC_OUTPUT

where `src/Makevars.in' would be simply

          PKG_CPPFLAGS = @RODBC_CPPFLAGS@
          PKG_LIBS = @LIBS@

   A user can then be advised to specify the location of the ODBC driver
manager files by options like (lines broken for easier reading)

     R CMD INSTALL \
       --configure-args='--with-odbc-include=/opt/local/include \
       --with-odbc-lib=/opt/local/lib --with-odbc-manager=iodbc' \
       RODBC

or by setting the environment variables `ODBC_INCLUDE' and `ODBC_LIBS'.


File: R-exts.info,  Node: Using F95 code,  Prev: Configure example,  Up: Configure and cleanup

1.2.3 Using F95 code
--------------------

R assumes that source files with extension `.f' are FORTRAN 77, and
passes them to the compiler specified by `F77'.  On most but not all
platforms that compiler will accept Fortran 90/95 code: some platforms
have a separate Fortran 90/95 compiler and a few (by now quite rare(1))
platforms have no Fortran 90/95 support.

   This means that portable packages need to be written in correct
FORTRAN 77, which will also be valid Fortran 95.  See
`http://developer.R-project.org/Portability.html' for reference
resources.  In particular, _free source form_ F95 code is not portable.

   On some systems an alternative F95 compiler is available: from the
`gcc' family this might be `gfortran' or `g95'.  Configuring R will try
to find a compiler which (from its name) appears to be a Fortran 90/95
compiler, and set it in macro `FC'.  Note that it does not check that
such a compiler is fully (or even partially) compliant with Fortran
90/95.  Packages making use of Fortran 90/95 features should use file
extension `.f90' or `.f95' for the source files: the variable
`PKG_FCFLAGS' specifies any special flags to be used.  There is no
guarantee that compiled Fortran 90/95 code can be mixed with any other
type of compiled code, nor that a build of R will have support for such
packages.

   Some (but not) all compilers specified by the `FC' macro will accept
Fortran 2003 or 2008 code.  For platforms using `gfortran', you may
need to include `-std=f2003' or `-std=f2008' in `PKG_FCFLAGS': the
default is `GNU Fortran', Fortran 95 with non-standard extensions.  The
Solaris `f95' compiler `accepts some Fortran 2003 features'.  Such code
should still use file extension `.f90' or `.f95'.

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

   (1) Cygwin used `g77' up to 2011, and some pre-built versions of R
for Unix OSes still do.


File: R-exts.info,  Node: Checking and building packages,  Next: Writing package vignettes,  Prev: Configure and cleanup,  Up: Creating R packages

1.3 Checking and building packages
==================================

Before using these tools, please check that your package can be
installed (which checked it can be loaded).  `R CMD check' will _inter
alia_ do this, but you may get more detailed error messages doing the
install directly.

* Menu:

* Checking packages::
* Building package tarballs::
* Building binary packages::

   If your package specifies an encoding in its `DESCRIPTION' file, you
should run these tools in a locale which makes use of that encoding:
they may not work at all or may work incorrectly in other locales
(although UTF-8 locales will most likely work).

     Note: `R CMD check' and `R CMD build' run R processes with
     `--vanilla' in which none of the user's startup files are read.
     If you need `R_LIBS' set (to find packages in a non-standard
     library) you can set it in the environment: also you can use the
     check and build environment files (as specified by the environment
     variables `R_CHECK_ENVIRON' and `R_BUILD_ENVIRON'; if unset,
     files(1)  `~/.R/check.Renviron' and `~/.R/build.Renviron' are
     used) to set environment variables when using these utilities.

     Note to Windows users: `R CMD build' may make use of the Windows
     toolset (see the "R Installation and Administration" manual) if
     present and in your path, and it is required for packages which
     need it to install (including those with `configure.win' or
     `cleanup.win' scripts or a `src' directory) and e.g. need
     vignettes built.

     You may need to set `TMPDIR' to point to a suitable writable
     directory with a path not containing spaces - use forward slashes
     for the separators.  Also, the directory needs to be on a
     case-honouring file system (some network-mounted file systems are
     not).

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

   (1) On systems which use sub-architectures, architecture-specific
versions such as `~/.R/check.Renviron.i386' take precedence.


File: R-exts.info,  Node: Checking packages,  Next: Building package tarballs,  Prev: Checking and building packages,  Up: Checking and building packages

1.3.1 Checking packages
-----------------------

Using `R CMD check', the R package checker, one can test whether
_source_ R packages work correctly.  It can be run on one or more
directories, or compressed package `tar' archives with extension
`.tar.gz', `.tgz', `.tar.bz2' or `.tar.xz'.

   It is strongly recommended that the final checks are run on a `tar'
archive prepared by `R CMD build'.

   This runs a series of checks, including

  1. The package is installed.  This will warn about missing
     cross-references and duplicate aliases in help files.

  2. The file names are checked to be valid across file systems and
     supported operating system platforms.

  3. The files and directories are checked for sufficient permissions
     (Unix-alikes only).

  4. The files are checked for binary executables, using a suitable
     version of `file' if available(1).  (There may be rare false
     positives.)

  5. The `DESCRIPTION' file is checked for completeness, and some of its
     entries for correctness.  Unless installation tests are skipped,
     checking is aborted if the package dependencies cannot be resolved
     at run time.  (You may need to set `R_LIBS' if dependent packages
     are in a separate library tree.) One check is that the package
     name is not that of a standard package, nor one of the defunct
     standard packages (`ctest', `eda', `lqs', `mle', `modreg', `mva',
     `nls', `stepfun' and `ts').  Another check is that all packages
     mentioned in `library' or `require's or from which the `NAMESPACE'
     file imports or are called _via_ `::' or `:::' are listed (in
     `Depends', `Imports', `Suggests'): this is not an exhaustive check
     of the actual imports.

  6. Available index information (in particular, for demos and
     vignettes) is checked for completeness.

  7. The package subdirectories are checked for suitable file names and
     for not being empty.  The checks on file names are controlled by
     the option `--check-subdirs=VALUE'.  This defaults to `default',
     which runs the checks only if checking a tarball: the default can
     be overridden by specifying the value as `yes' or `no'.  Further,
     the check on the `src' directory is only run if the package does
     not contain a `configure' script (which corresponds to the value
     `yes-maybe') and there is no `src/Makefile' or `src/Makefile.in'.

     To allow a `configure' script to generate suitable files, files
     ending in `.in' will be allowed in the `R' directory.

     A warning is given for directory names that look like R package
     check directories - many packages have been submitted to CRAN
     containing these.

  8. The R files are checked for syntax errors.  Bytes which are
     non-ASCII are reported as warnings, but these should be regarded
     as errors unless it is known that the package will always be used
     in the same locale.

  9. It is checked that the package can be loaded, first with the usual
     default packages and then only with package *base* already loaded.
     It is checked that the namespace this can be loaded in an empty
     session with only the *base* namespace loaded.  (Namespaces and
     packages can be loaded very early in the session, before the
     default packages are available, so packages should work then.)

 10. The R files are checked for correct calls to `library.dynam'.
     Package startup functions are checked for correct argument lists
     and (incorrect) calls to functions which modify the search path or
     inappropriately generate messages.  The R code is checked for
     possible problems using *codetools*
     (http://CRAN.R-project.org/package=codetools).  In addition, it is
     checked whether S3 methods have all arguments of the corresponding
     generic, and whether the final argument of replacement functions
     is called `value'.  All foreign function calls (`.C', `.Fortran',
     `.Call' and `.External' calls) are tested to see if they have a
     `PACKAGE' argument, and if not, whether the appropriate DLL might
     be deduced from the namespace of the package.  Any other calls are
     reported.  (The check is generous, and users may want to
     supplement this by examining the output of
     `tools::checkFF("mypkg", verbose=TRUE)', especially if the
     intention were to always use a `PACKAGE' argument)

 11. The `Rd' files are checked for correct syntax and metadata,
     including the presence of the mandatory fields (`\name', `\alias',
     `\title' and `\description').  The `Rd' name and title are checked
     for being non-empty, and there is a check for missing
     cross-references (links).

 12. A check is made for missing documentation entries, such as
     undocumented user-level objects in the package.

 13. Documentation for functions, data sets, and S4 classes is checked
     for consistency with the corresponding code.

 14. It is checked whether all function arguments given in `\usage'
     sections of `Rd' files are documented in the corresponding
     `\arguments' section.

 15. The `data' directory is checked for non-ASCII characters and for
     the use of reasonable levels of compression.

 16. C, C++ and FORTRAN source and header files(2) are tested for
     portable (LF-only) line endings.  If there is a `Makefile' or
     `Makefile.in' or `Makevars' or `Makevars.in' file under the `src'
     directory, it is checked for portable line endings and the correct
     use of `$(BLAS_LIBS)' and `$(LAPACK_LIBS)'

     Compiled code is checked for symbols corresponding to functions
     which might terminate R or write to `stdout'/`stderr' instead of
     the console.  Note that the latter might give false positives in
     that the symbols might be pulled in with external libraries and
     could never be called.  Windows(3) users should note that the
     Fortran and C++ runtime libraries are examples of such external
     libraries.

 17. Some checks are made of the contents of the `inst/doc' directory.
     These always include checking for files that look like leftovers,
     and if suitable tools (such as `qpdf') are available, checking
     that the PDF documentation is of minimal size.

 18. The examples provided by the package's documentation are run.
     (*note Writing R documentation files::, for information on using
     `\examples' to create executable example code.)  If there is a file
     `tests/Examples/PKG-Ex.Rout.save', the output of running the
     examples is compared to that file.

     Of course, released packages should be able to run at least their
     own examples.  Each example is run in a `clean' environment (so
     earlier examples cannot be assumed to have been run), and with the
     variables `T' and `F' redefined to generate an error unless they
     are set in the example: *Note Logical vectors: (R-intro)Logical
     vectors.

 19. If the package sources contain a `tests' directory then the tests
     specified in that directory are run.  (Typically they will consist
     of a set of `.R' source files and target output files
     `.Rout.save'.)  Please note that the comparison will be done in the
     end user's locale, so the target output files should be ASCII if
     at all possible.

 20. The code in package vignettes (*note Writing package vignettes::)
     is executed, and the vignette PDFs re-made from their sources as a
     check of completeness of the sources (unless there is a
     `BuildVignettes' field in the package's `DESCRIPTION' file with a
     false value).  If there is a target output file `.Rout.save' in
     the vignette source directory, the output from running the code in
     that vignette is compared with the target output file and any
     differences are reported (but not recorded in the log file).  (If
     the vignette sources are in the deprecated location `inst/doc', do
     mark such target output files to not be installed in
     `.Rinstignore'.)

     If there is an error(4) in executing the R code in vignette
     `FOO.EXT', a log file `FOO.EXT.log' is created in the check
     directory.  The vignette PDFs are re-made in a copy of the package
     sources in the `vign_test' subdirectory of the check directory, so
     for further information on errors look in directory
     `PKGNAME/vign_test/inst/doc'.  (It is only retained if there are
     errors or if environment variable `_R_CHECK_CLEAN_VIGN_TEST_' is
     set to a false value.)

 21. The PDF version of the package's manual is created (to check that
     the `Rd' files can be converted successfully).  This needs LaTeX
     and suitable fonts and LaTeX packages to be installed.  *Note
     Making the manuals: (R-admin)Making the manuals.


   All these tests are run with collation set to the `C' locale, and
for the examples and tests with environment variable `LANGUAGE=en':
this is to minimize differences between platforms.

   Use `R CMD check --help' to obtain more information about the usage
of the R package checker.  A subset of the checking steps can be
selected by adding command-line options. It also allows customization by
setting environment variables `_R_CHECK_*_':, as described in *Note
Tools: (R-ints)Tools.: a set of these customizations similar to those
used by CRAN can be selected by the option `--as-cran' (which works
best if Internet access is available(5)).

   You do need to ensure that the package is checked in a suitable
locale if it contains non-ASCII characters.  Such packages are likely
to fail some of the checks in a `C' locale, and `R CMD check' will warn
if it spots the problem.  You should be able to check any package in a
UTF-8 locale (if one is available).  Beware that although a `C' locale
is rarely used at a console, it may be the default if logging in
remotely or for batch jobs.

     Multiple sub-architectures: On systems which support multiple
     sub-architectures (principally Windows), `R CMD check' will
     install and check a package which contains compiled code under all
     available sub-architectures. (Use option `--force-multiarch' to
     force this for packages without compiled code, which are otherwise
     only checked under the main sub-architecture.)  This will run the
     loading tests, examples and `tests' directory under each installed
     sub-architecture in turn, and give an error if any fail.  Where
     environment variables (including perhaps `PATH') need to be set
     differently for each sub-architecture, these can be set in
     architecture-specific files such as
     `R_HOME/etc/i386/Renviron.site'.

     An alternative approach is to use `R CMD check --no-multiarch' to
     check the primary sub-architecture, and then to use something like
     `R --arch=x86_64 CMD check --extra-arch' or (Windows)
     `/path/to/R/bin/x64/Rcmd check --extra-arch' to run for each
     additional sub-architecture just the checks(6) which differ by
     sub-architecture.  (This approach is required for packages which
     are installed by `R CMD INSTALL --merge-multiarch'.)

     Where packages need additional commands to install all the
     sub-architectures these can be supplied by e.g.
     `--install-args=--force-biarch'.


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

   (1) A suitable `file.exe' is part of the Windows toolset.

   (2) An exception is made for subdirectories with names starting
`win' or `Win'.

   (3) on most other platforms such runtime libraries are dynamic, but
static libraries are currently used on Windows because the toolchain is
not a standard part of the OS.

   (4) or if option `--use-valgrind' is used or environment variable
`_R_CHECK_ALWAYS_LOG_VIGNETTE_OUTPUT_' is set to a true value or if
there are differences from a target output file

   (5) Windows users behind proxies may want to set environment
variable `R_WIN_INTERNET2' to a non-empty value, e.g. in
`~/.R/check_environ'.  Some Windows users may need to set
`R_WIN_NO_JUNCTIONS' to a non-empty value.

   (6) loading, examples, tests, vignettes


File: R-exts.info,  Node: Building package tarballs,  Next: Building binary packages,  Prev: Checking packages,  Up: Checking and building packages

1.3.2 Building package tarballs
-------------------------------

Packages may be distributed in source form as "tarballs" (`.tar.gz'
files) or in binary form. The source form can be installed on all
platforms with suitable tools and is the usual form for Unix-like
systems; the binary form is platform-specific, and is the more common
distribution form for the Windows and OS X platforms.

   Using `R CMD build', the R package builder, one can build R package
tarballs from their sources (for example, for subsequent release).

   Prior to actually building the package in the standard gzipped tar
file format, a few diagnostic checks and cleanups are performed.  In
particular, it is tested whether object indices exist and can be assumed
to be up-to-date, and C, C++ and FORTRAN source files and relevant
makefiles in a `src' directory are tested and converted to LF
line-endings if necessary.

   Run-time checks whether the package works correctly should be
performed using `R CMD check' prior to invoking the final build
procedure.

   To exclude files from being put into the package, one can specify a
list of exclude patterns in file `.Rbuildignore' in the top-level source
directory.  These patterns should be Perl-like regular expressions (see
the help for `regexp' in R for the precise details), one per line, to
be matched(1) against the file and directory names relative to the
top-level package source directory.  In addition, directories from
source control systems(2) or from `eclipse'(3), directories with names
ending `.Rcheck' or `Old' or `old' and files `GNUMakefile',
`Read-and-delete-me' or with base names starting with `.#', or starting
and ending with `#', or ending in `~', `.bak' or `.swp', are excluded
by default.  In addition, those files in the `R', `demo' and `man'
directories which are flagged by `R CMD check' as having invalid names
will be excluded.

   Use `R CMD build --help' to obtain more information about the usage
of the R package builder.

   Unless `R CMD build' is invoked with the `--no-build-vignettes'
option (or the package's `DESCRIPTION' contains `BuildVignettes: no' or
similar), it will attempt to (re)build the vignettes (*note Writing
package vignettes::) in the package.  To do so it installs the current
package into a temporary library tree, but any dependent packages need
to be installed in an available library tree (see the Note: at the top
of this section).

   Similarly, if the `.Rd' documentation files contain any `\Sexpr'
macros (*note Dynamic pages::), the package will be temporarily
installed to execute them.  Post-execution binary copies of those pages
containing build-time macros will be saved in `build/partial.rdb'.  If
there are any install-time or render-time macros, a `.pdf' version of
the package manual will be built and installed in the `build/'
subdirectory.  (This allows CRAN or other repositories to display the
manual even if they are unable to install the package.)  This can be
suppressed by the option `--no-manual' or if package's `DESCRIPTION'
contains `BuildManual: no' or similar.

   One of the checks that `R CMD build' runs is for empty source
directories.  These are in most (but not all) cases unintentional, if
they are intentional use the option `--keep-empty-dirs' (or set the
environment variable `_R_BUILD_KEEP_EMPTY_DIRS_' to `TRUE', or have a
`BuildKeepEmpty' field with a true value in the `DESCRIPTION' file).

   The `--resave-data' option allows saved images (`.rda' and `.RData'
files) in the `data' directory to be optimized for size.  It will also
compress tabular files and convert `.R' files to saved images.  It can
take values `no', `gzip' (the default if this option is not supplied,
which can be changed by setting the environment variable
`_R_BUILD_RESAVE_DATA_') and `best' (equivalent to giving it without a
value), which chooses the most effective compression.  Using `best'
adds a dependence on `R (>= 2.10)' to the `DESCRIPTION' file if `bzip2'
or `xz' compression is selected for any of the files.  If this is
thought undesirable, `--resave-data=gzip' (which is the default if that
option is not supplied) will do what compression it can with `gzip'.  A
package can control how its data is resaved by supplying a
`BuildResaveData' field (with one of the values given earlier in this
paragraph) in its `DESCRIPTION' file.

   The `--compact-vignettes' option will run `tools::compactPDF' over
the PDF files in `inst/doc' (and its subdirectories) to losslessly
compress them.  This is not enabled by default (it can be selected by
environment variable `_R_BUILD_COMPACT_VIGNETTES_') and needs `qpdf'
(`http://qpdf.sourceforge.net/') to be available.

   It can be useful to run `R CMD check --check-subdirs=yes' on the
built tarball as a final check on the contents.

   Where a non-POSIX file system is in use which does not utilize
execute permissions, some care is needed with permissions.  This
applies on Windows and to e.g. FAT-formatted drives and SMB-mounted
file systems on other OSes.  The `mode' of the file recorded in the
tarball will be whatever `file.info()' returns.  On Windows this will
record only directories with execute permission and on other OSes it is
likely that all files have reported `mode' `0777'.  A particular issue
is packages being built on Windows which are intended to contain
executable scripts such as `configure' and `cleanup': it is difficult to
include these from Windows but where Cygwin has been used to set a
POSIX-like mode, using environment variable `R_BUILD_TAR=tar.exe' _may_
provide a workaround.

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

   (1) case-insensitively on Windows.

   (2) called `CVS' or `.svn' or `.arch-ids' or `.bzr' or `.git' (but
not files called `.git') or `.hg'.

   (3) called `.metadata'.


File: R-exts.info,  Node: Building binary packages,  Prev: Building package tarballs,  Up: Checking and building packages

1.3.3 Building binary packages
------------------------------

Binary packages are compressed copies of installed versions of
packages.  They contain compiled shared libraries rather than C, C++ or
Fortran source code, and the R functions are included in their installed
form.  The format and filename are platform-specific; for example, a
binary package for Windows is usually supplied as a `.zip' file, and
for the OS X platform the default binary package file extension is
`.tgz'.

   The recommended method of building binary packages is to use

   `R CMD INSTALL --build pkg' where `pkg' is either the name of a
source tarball (in the usual `.tar.gz' format) or the location of the
directory of the package source to be built.  This operates by first
installing the package and then packing the installed binaries into the
appropriate binary package file for the particular platform.

   By default, `R CMD INSTALL --build' will attempt to install the
package into the default library tree for the local installation of R.
This has two implications:

   * If the installation is successful, it will overwrite any existing
     installation of the same package.

   * The default library tree must have write permission; if not, the
     package will not install and the binary will not be created.


To prevent changes to the present working installation or to provide an
install location with write access, create a suitably located directory
with write access and use the `-l' option to build the package in the
chosen location.  The usage is then

   `R CMD INSTALL -l location --build pkg'

where `location' is the chosen directory with write access. The package
will be installed as a subdirectory of `location', and the package
binary will be created in the current directory.

   Other options for `R CMD INSTALL' can be found using `R CMD INSTALL
--help', and platform-specific details for special cases (e.g. handling
Fortran sources on OS X) are discussed in the platform-specific FAQs.

   In much earlier versions of R, `R CMD build --binary' could build a
binary version of a package, but this approach is now deprecated in
favour of `R CMD INSTALL --build'.

   Finally, at least one web-based service is available for building
binary packages from (checked) source code: WinBuilder (see
`http://win-builder.R-project.org/') is able to build Windows binaries.
Note that this is intended for developers on other platforms who do not
have access to Windows but wish to provide binaries for the Windows
platform.


File: R-exts.info,  Node: Writing package vignettes,  Next: Package namespaces,  Prev: Checking and building packages,  Up: Creating R packages

1.4 Writing package vignettes
=============================

* Menu:

* Encodings and vignettes::
* Non-Sweave vignettes::

   In addition to the help files in `Rd' format, R packages allow the
inclusion of documents in arbitrary other formats.  The standard
location for these is subdirectory `inst/doc' of a source package, the
contents will be copied to subdirectory `doc' when the package is
installed.  Pointers from package help indices to the installed
documents are automatically created.  Documents in `inst/doc' can be in
arbitrary format, however we strongly recommend providing them in PDF
format, so users on almost all platforms can easily read them.  To
ensure that they can be accessed from a browser (as an HTML index is
provided), the file names should start with an ASCII letter and be
comprised entirely of ASCII letters or digits or hyphen or underscore.

   A special case are PDF documents with sources in Sweave, which we
call _package vignettes_.  (Since R version 3.0.0, other vignette
formats besides Sweave are supported; see *Note Non-Sweave vignettes::.)
The preferred location for the sources is the subdirectory `vignettes'
of the source packages, but for compatibility with earlier versions of
R, vignette sources will be looked for in `inst/doc' if `vignettes'
does not exist.

   Vignette sources are normally given the file extension `.Rnw' or
`.Rtex', but for historical reasons extensions(1) `.Snw' and `.Stex'
are also recognized as vignettes.  Sweave allows the integration of
LaTeX documents: see the `Sweave' help page in R and the `Sweave'
vignette in package *utils* for details on the document format.
Package vignettes are tested by `R CMD check' by executing all R code
chunks they contain (except those with option `eval=FALSE').  The R
working directory for all vignette tests in `R CMD check' is a _copy_
of the vignette source directory.  Make sure all files needed to run
the R code in the vignette (data sets, ...) are accessible by either
placing them in the `inst/doc' hierarchy of the source package or by
using calls to `system.file()'.  All other files needed to re-make the
vignette PDFs (such as LaTeX style files, BiBTeX input files and files
for any figures not created by running the code in the vignette) must
be in the vignette source directory.

   `R CMD build' will automatically(2) create PDF versions of the
vignettes in `inst/doc' for distribution with the package sources.  By
including the PDF version in the package sources it is not necessary
that the vignette PDFs can be re-built at install time, i.e., the
package author can use private R packages, screen snapshots and LaTeX
extensions which are only available on his machine.(3)

   By default `R CMD build' will run `Sweave' on all files in Sweave
format in `vignettes', or if that does not exist, `inst/doc' (but not
in sub-directories).  If no `Makefile' is found in directory
`inst/doc', then `tools::texi2dvi(pdf = TRUE)' is run on all processed
vignettes.  Whenever a `Makefile' is found, then `R CMD build' will try
to run `make' after the `Sweave' runs.  The first target in the
`Makefile' should take care of both creation of PDF files and cleaning
up afterwards (including after `Sweave'), i.e., delete all files that
shall not appear in the final package archive.  Note that if the `make'
step runs R it needs to be careful to respect the environment values of
`R_LIBS' and `R_HOME'(4).  Finally, if there is a `Makefile' and it has
a `clean:' target, `make clean' is run.

   All the usual _caveats_ about including a `Makefile' apply.  It must
be portable (no GNU extensions), use LF line endings and must work
correctly with a parallel `make': too many authors have written things
like

     ## BAD EXAMPLE
     all: pdf clean

     pdf: ABC-intro.pdf ABC-details.pdf

     %.pdf:  %.tex
             texi2dvi --pdf $*

     clean:
             rm *.tex ABC-details-*.pdf

which will start removing the source files whilst `pdflatex' is working.

   Note that it is pointless (and potentially misleading since the files
might be outdated) to include in `inst/doc' R code files which would be
generated from vignettes, as these will be re-generated when the
package is installed (unless the vignette does not generate any R code,
in which case it is also pointless/misleading).

   Metadata lines can be placed in the source file, preferably in LaTeX
comments in the preamble.  One such is a `\VignetteIndexEntry' of the
form
     %\VignetteIndexEntry{Using Animal}
   Others you may see are `\VignettePackage' (currently ignored),
`\VignetteDepends' and `\VignetteKeyword' (which replaced
`\VignetteKeywords').  These are processed at package installation time
to create the saved data frame `Meta/vignette.rds', but only the
`\VignetteIndexEntry' and `\VignetteKeyword' statements are currently
used.  The `\VignetteEngine' statement is described in *Note Non-Sweave
vignettes::.

   At install time an HTML index for all vignettes in the package is
automatically created from the `\VignetteIndexEntry' statements unless
a file `index.html' exists in directory `inst/doc'. This index is
linked from the HTML help index for the package.  If you do supply a
`inst/doc/index.html' file it should contain relative links only to
files under the installed `doc' directory, or perhaps (not really an
index) to HTML help files or to the `DESCRIPTION' file.

   Sweave/Stangle allows the document to specify the `split=TRUE'
option to create a single R file for each code chunk: this will not
work for vignettes where it is assumed that each vignette source
generates a single file with the vignette extension replaced by `.R'.

   Do watch that PDFs are not too large - one in a CRAN package was
72MB!  This is usually caused by the inclusion of overly detailed
figures, which will not render well in PDF viewers.  Sometimes it is
much better to generate fairly high resolution bitmap (PNG, JPEG)
figures and include those in the PDF document.

   When `R CMD build' builds the vignette PDFs, it copies these and the
vignette sources from directory `vignettes' to `inst/doc'.  To install
any other files from the `vignettes' directory, include a file
`vignettes/.install_extras' which specifies these as Perl-like regular
expressions on one or more lines.  (See the description of the
`.Rinstignore' file for full details.)

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

   (1) and to avoid problems with case-insensitive file systems,
lower-case versions of all these extensions.

   (2) unless inhibited by using `BuildVignettes: no' in the
`DESCRIPTION' file.

   (3) provided the conditions of the package's license are met: many
would see these as incompatible with an Open Source license.

   (4) `R_HOME/bin' is prepended to the `PATH' so that references to
`R' or `Rscript' in the `Makefile' do make use of the currently running
version of R.


File: R-exts.info,  Node: Encodings and vignettes,  Next: Non-Sweave vignettes,  Prev: Writing package vignettes,  Up: Writing package vignettes

1.4.1 Encodings and vignettes
-----------------------------

Vignette PDFs will in general include descriptive text, R input, R
output and figures, LaTeX include files and bibliographic references.
As any of these may contain non-ASCII characters, the handling of
encodings can become very complicated.

   The vignette source file should be written in ASCII or contain a
declaration of the encoding (see below).  This applies even to comments
within the source file, since `Sweave()' processes comments to look for
options and metadata lines.  When `Sweave()' or `Stangle()' is called
on the vignette source, it will be converted to the encoding of the
current R session.

   `Stangle()' will produce an R code file in the current locale's
encoding: for a non-ASCII vignette what that is recorded in a comment at
the top of the file.

   `Sweave()' will produce a `.tex' file in the current locale's
encoding.  That needs to be declared to LaTeX via a line like
     \usepackage[utf8]{inputenc}
   (It is also possible to use the more recent `inputenx' LaTeX
package.)  `R CMD check' will warn about any non-ASCII vignettes it
finds which do not have such a declaration.

   `Sweave()' will also parse and evaluate the R code in each chunk.
The R output will also be in the current locale, and should be covered
by the `inputenc' declaration.  One thing people often forget is that
the R output may not be ASCII even for ASCII R sources, for many
possible reasons.  One common one is the use of `fancy' quotes: see the
R help on `sQuote': note carefully that it is not portable to declare
UTF-8 or CP1252 to cover such quotes, as their encoding will depend on
the locale used to run `Sweave()': this can be circumvented by setting
`options(useFancyQuotes="UTF-8")' in the vignette.

   The final issue is the encoding of figures - this applies only to PDF
figures and not PNG etc.  The PDF figures will contain declarations for
their encoding, but the Sweave option `pdf.encoding' may need to be set
appropriately: see the help for the `pdf()' graphics device.

   As a real example of the complexities, consider the *fortunes*
(http://CRAN.R-project.org/package=fortunes) package version `1.4-0'.
That package did not have a declared encoding, and its vignette was in
ASCII.  However, the data it displays are read from a UTF-8 CSV file
and will be assumed to be in the current encoding, so `fortunes.tex'
will be in UTF-8 in any locale.  Had `read.table' been told the data
were UTF-8, `fortunes.tex' would have been in the locale's encoding.


File: R-exts.info,  Node: Non-Sweave vignettes,  Prev: Encodings and vignettes,  Up: Writing package vignettes

1.4.2 Non-Sweave vignettes
--------------------------

New in R version 3.0.0 is the possibility of vignettes in formats other
than Sweave by means of "vignette engines". For example *knitr*
(http://CRAN.R-project.org/package=knitr) version 1.1 or higher can
create `.tex' files from a variation on Sweave format, or `.html' files
from a variation on "markdown" format. These engines replace the
`Sweave()' function with other functions to convert vignette source
files into LaTeX files for processing into `.pdf', or directly into
`.pdf' or `.html' files. The `Stangle()' function is replaced with a
function that extracts the R source from a vignette.

   R recognizes non-Sweave vignettes using filename extensions specified
by the engine.  For example, the *knitr*
(http://CRAN.R-project.org/package=knitr) package supports the
extension `.Rmd' (standing for "R markdown").  The user indicates the
vignette engine within the vignette source using the `\VignetteEngine'
line, for example
     %\VignetteEngine{knitr::knitr}
   This specifies the name of a package and an engine to use in place of
Sweave in processing the vignette.  As `Sweave' is the only engine
supplied with R, the package providing any other engine must be
specified in the `VignetteBuilder' field of the package `DESCRIPTION'
file, and also specified in the `Suggests', `Imports' or `Depends'
field (since its namespace must be available to build or check your
package).  If more than one package is specified as a builder, they
will be searched in the order given there.  The *utils* package is
always implicitly appended to the list of builder packages.

   Note that a package with non-Sweave vignettes should always have a
`VignetteBuilder' field in the `DESCRIPTION' file, since this is how `R
CMD check' recognizes that there are vignettes to be checked.

   The vignette engine can produce `.tex', `.pdf', or `.html' files as
output.  If it produces `.tex' files, R will call `pdflatex' to convert
them to `.pdf' for display to the user.

   Package writers who would like to supply vignette engines need to
register those engines in the package `.onLoad' function.  For example,
that function could make the call
     tools::vignetteEngine("knitr", weave = vweave, tangle = vtangle,
                           pattern = "[.]Rmd$", package = "knitr")
   (The actual registration in *knitr*
(http://CRAN.R-project.org/package=knitr) is more complicated, because
it supports other input formats as well as `.Rmd'.)  See the
`?tools::vignetteEngine' help topic for details on engine registration.


File: R-exts.info,  Node: Package namespaces,  Next: Writing portable packages,  Prev: Writing package vignettes,  Up: Creating R packages

1.5 Package namespaces
======================

R has a namespace management system for code in packages.  This system
allows the package writer to specify which variables in the package
should be _exported_ to make them available to package users, and which
variables should be _imported_ from other packages.

   The mechanism for specifying a namespace for a package is to place a
`NAMESPACE' file in the top level package directory.  This file
contains _namespace directives_ describing the imports and exports of
the namespace.  Additional directives register any shared objects to be
loaded and any S3-style methods that are provided.  Note that although
the file looks like R code (and often has R-style comments) it is not
processed as R code.  Only very simple conditional processing of `if'
statements is implemented.

   Packages are loaded and attached to the search path by calling
`library' or `require'.  Only the exported variables are placed in the
attached frame.  Loading a package that imports variables from other
packages will cause these other packages to be loaded as well (unless
they have already been loaded), but they will _not_ be placed on the
search path by these implicit loads.

   Namespaces are _sealed_ once they are loaded.  Sealing means that
imports and exports cannot be changed and that internal variable
bindings cannot be changed.  Sealing allows a simpler implementation
strategy for the namespace mechanism.  Sealing also allows code
analysis and compilation tools to accurately identify the definition
corresponding to a global variable reference in a function body.

   The namespace controls the search strategy for variables used by
functions in the package.  If not found locally, R searches the package
namespace first, then the imports, then the base namespace and then the
normal search path.

   Prior to R 2.14.0, namespaces were optional in packages: a default
namespace was generated on installation in 2.14.x and 2.15.x.  As from
3.0.0 a namespace is mandatory.

* Menu:

* Specifying imports and exports::
* Registering S3 methods::
* Load hooks::
* useDynLib::
* An example::
* Namespaces with S4 classes and methods::


File: R-exts.info,  Node: Specifying imports and exports,  Next: Registering S3 methods,  Prev: Package namespaces,  Up: Package namespaces

1.5.1 Specifying imports and exports
------------------------------------

Exports are specified using the `export' directive in the `NAMESPACE'
file.  A directive of the form

     export(f, g)

specifies that the variables `f' and `g' are to be exported.  (Note
that variable names may be quoted, and reserved words and non-standard
names such as `[<-.fractions' must be.)

   For packages with many variables to export it may be more convenient
to specify the names to export with a regular expression using
`exportPattern'.  The directive

     exportPattern("^[^\\.]")

exports all variables that do not start with a period.  However, such
broad patterns are not recommended for production code: it is better to
list all exports or use narrowly-defined groups.  (This pattern applies
to S4 classes.)  Beware of patterns which include names starting with a
period: some of these are internal-only variables and should never be
exported, e.g. `.__S3MethodsTable__.' (and the code nowadays excludes
known cases).

   Packages implicitly import the base namespace.  Variables exported
from other packages with namespaces need to be imported explicitly
using the directives `import' and `importFrom'.  The `import' directive
imports all exported variables from the specified package(s).  Thus the
directives

     import(foo, bar)

specifies that all exported variables in the packages *foo* and *bar*
are to be imported.  If only some of the exported variables from a
package are needed, then they can be imported using `importFrom'.  The
directive

     importFrom(foo, f, g)

specifies that the exported variables `f' and `g' of the package *foo*
are to be imported.  Using `importFrom' selectively rather than
`import' is good practice.

   It is possible to export variables from a namespace which it has
imported from other namespaces.

   If a package only needs a few objects from another package it can
use a fully qualified variable reference in the code instead of a formal
import.  A fully qualified reference to the function `f' in package
*foo* is of the form `foo::f'.  This is slightly less efficient than a
formal import and also loses the advantage of recording all
dependencies in the `NAMESPACE' file (but they still need to be
recorded in the `DESCRIPTION' file.  Evaluating `foo::f' will cause
package *foo* to be loaded, but not attached, if it was not loaded
already--this can be an advantage in delaying the loading of a rarely
used package.

   Using `foo:::f' instead of `foo::f' allows access to unexported
objects.  This is generally not recommended, as the semantics of
unexported objects may be changed by the package author in routine
maintenance.


File: R-exts.info,  Node: Registering S3 methods,  Next: Load hooks,  Prev: Specifying imports and exports,  Up: Package namespaces

1.5.2 Registering S3 methods
----------------------------

The standard method for S3-style `UseMethod' dispatching might fail to
locate methods defined in a package that is imported but not attached
to the search path.  To ensure that these methods are available the
packages defining the methods should ensure that the generics are
imported and register the methods using `S3method' directives.  If a
package defines a function `print.foo' intended to be used as a `print'
method for class `foo', then the directive

     S3method(print, foo)

ensures that the method is registered and available for `UseMethod'
dispatch, and the function `print.foo' does not need to be exported.
Since the generic `print' is defined in *base* it does not need to be
imported explicitly.

   (Note that function and class names may be quoted, and reserved words
and non-standard names such as `[<-' and `function' must be.)

   It is possible to specify a third argument to S3method, the function
to be used as the method, for example

     S3method(print, check_so_symbols, .print.via.format)

when `print.check_so_symbols' is not needed.


File: R-exts.info,  Node: Load hooks,  Next: useDynLib,  Prev: Registering S3 methods,  Up: Package namespaces

1.5.3 Load hooks
----------------

There are a number of hooks called as packages are loaded, attached,
detached, and unloaded.  See `help(".onLoad")' for more details.

   Since loading and attaching are distinct operations, separate hooks
are provided for each.  These hook functions are called `.onLoad' and
`.onAttach'.  They both take arguments(1) `libname' and `pkgname'; they
should be defined in the namespace but not exported.

   Packages can use a `.onDetach' (as from R 3.0.0) or `.Last.lib'
function (provided the latter is exported from the namespace) when
`detach' is called on the package.  It is called with a single
argument, the full path to the installed package.  There is also a hook
`.onUnload' which is called when the namespace is unloaded (_via_ a
call to `unloadNamespace', perhaps called by `detach(unload = TRUE)')
with argument the full path to the installed package's directory.
`.onUnload' and `.onDetach' should be defined in the namespace and not
exported, but `.Last.lib' does need to be exported.

   Packages are not likely to need `.onAttach' (except perhaps for a
start-up banner); code to set options and load shared objects should be
placed in a `.onLoad' function, or use made of the `useDynLib'
directive described next.

   User-level hooks are also available: see the help on function
`setHook'.

   These hooks are often used incorrectly.  People forget to export
`.Last.lib'.   Compiled code should be loaded in `.onLoad' (or _via_ a
`useDynLb' directive: see below) and unloaded in `.onUnload'.  Do
remember that a package's namespace can be loaded without the namespace
being attached (e.g. by `pkgname::fun') and that a package can be
detached and re-attached whilst its namespace remains loaded.

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

   (1) they will be called with two unnamed arguments, in that order.


File: R-exts.info,  Node: useDynLib,  Next: An example,  Prev: Load hooks,  Up: Package namespaces

1.5.4 useDynLib
---------------

A `NAMESPACE' file can contain one or more `useDynLib' directives which
allows shared objects that need to be loaded.(1)  The directive

     useDynLib(foo)

registers the shared object `foo'(2) for loading with `library.dynam'.
Loading of registered object(s) occurs after the package code has been
loaded and before running the load hook function.  Packages that would
only need a load hook function to load a shared object can use the
`useDynLib' directive instead.

   The `useDynLib' directive also accepts the names of the native
routines that are to be used in R _via_ the `.C', `.Call', `.Fortran'
and `.External' interface functions.  These are given as additional
arguments to the directive, for example,

     useDynLib(foo, myRoutine, myOtherRoutine)

   By specifying these names in the `useDynLib' directive, the native
symbols are resolved when the package is loaded and R variables
identifying these symbols are added to the package's namespace with
these names.  These can be used in the `.C', `.Call', `.Fortran' and
`.External' calls in place of the name of the routine and the `PACKAGE'
argument.  For instance, we can call the routine `myRoutine' from R
with the code

      .Call(myRoutine, x, y)

rather than

      .Call("myRoutine", x, y, PACKAGE = "foo")

   There are at least two benefits to this approach.  Firstly, the
symbol lookup is done just once for each symbol rather than each time
the routine is invoked.  Secondly, this removes any ambiguity in
resolving symbols that might be present in several compiled DLLs.

   In some circumstances, there will already be an R variable in the
package with the same name as a native symbol. For example, we may have
an R function in the package named `myRoutine'.  In this case, it is
necessary to map the native symbol to a different R variable name. This
can be done in the `useDynLib' directive by using named arguments. For
instance, to map the native symbol name `myRoutine' to the R variable
`myRoutine_sym', we would use

     useDynLib(foo, myRoutine_sym = myRoutine, myOtherRoutine)

   We could then call that routine from R using the command

      .Call(myRoutine_sym, x, y)

   Symbols without explicit names are assigned to the R variable with
that name.

   In some cases, it may be preferable not to create R variables in the
package's namespace that identify the native routines.  It may be too
costly to compute these for many routines when the package is loaded if
many of these routines are not likely to be used.  In this case, one
can still perform the symbol resolution correctly using the DLL, but do
this each time the routine is called.  Given a reference to the DLL as
an R variable, say `dll', we can call the routine `myRoutine' using the
expression

      .Call(dll$myRoutine, x, y)

   The `$' operator resolves the routine with the given name in the DLL
using a call to `getNativeSymbol'.  This is the same computation as
above where we resolve the symbol when the package is loaded. The only
difference is that this is done each time in the case of
`dll$myRoutine'.

   In order to use this dynamic approach (e.g., `dll$myRoutine'), one
needs the reference to the DLL as an R variable in the package.  The
DLL can be assigned to a variable by using the `variable = dllName'
format used above for mapping symbols to R variables.  For example, if
we wanted to assign the DLL reference for the DLL `foo' in the example
above to the variable `myDLL', we would use the following directive in
the `NAMESPACE' file:

     myDLL = useDynLib(foo, myRoutine_sym = myRoutine, myOtherRoutine)

   Then, the R variable `myDLL' is in the package's namespace and
available for calls such as `myDLL$dynRoutine' to access routines that
are not explicitly resolved at load time.

   If the package has registration information (see *Note Registering
native routines::), then we can use that directly rather than
specifying the list of symbols again in the `useDynLib' directive in the
`NAMESPACE' file.  Each routine in the registration information is
specified by giving a name by which the routine is to be specified along
with the address of the routine and any information about the number and
type of the parameters.  Using the `.registration' argument of
`useDynLib', we can instruct the namespace mechanism to create R
variables for these symbols.  For example, suppose we have the
following registration information for a DLL named `myDLL':

     R_CMethodDef cMethods[] = {
        {"foo", (DL_FUNC) &foo, 4, {REALSXP, INTSXP, STRSXP, LGLSXP}},
        {"bar_sym", (DL_FUNC) &bar, 0},
        {NULL, NULL, 0}
     };

     R_CallMethodDef callMethods[] = {
        {"R_call_sym", (DL_FUNC) &R_call, 4},
        {"R_version_sym", (DL_FUNC) &R_version, 0},
        {NULL, NULL, 0}
     };

   Then, the directive in the `NAMESPACE' file

     useDynLib(myDLL, .registration = TRUE)

causes the DLL to be loaded and also for the R variables `foo',
`bar_sym', `R_call_sym' and `R_version_sym' to be defined in the
package's namespace.

   Note that the names for the R variables are taken from the entry in
the registration information and do not need to be the same as the name
of the native routine.  This allows the creator of the registration
information to map the native symbols to non-conflicting variable names
in R, e.g. `R_version' to `R_version_sym' for use in an R function such
as

     R_version <- function()
     {
       .Call(R_version_sym)
     }

   Using argument `.fixes' allows an automatic prefix to be added to
the registered symbols, which can be useful when working with an
existing package.  For example, package *KernSmooth*
(http://CRAN.R-project.org/package=KernSmooth) has

     useDynLib(KernSmooth, .registration = TRUE, .fixes = "F_")

which makes the R variables corresponding to the FORTRAN symbols
`F_bkde' and so on, and so avoid clashes with R code in the namespace.

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

   (1) NB: this will only be read in all versions of R if the package
contains R code in a `R' directory.

   (2) Note that this is the basename of the shared object, and the
appropriate extension (`.so' or `.dll') will be added.


File: R-exts.info,  Node: An example,  Next: Namespaces with S4 classes and methods,  Prev: useDynLib,  Up: Package namespaces

1.5.5 An example
----------------

As an example consider two packages named *foo* and *bar*.  The R code
for package *foo* in file `foo.R' is

          x <- 1
          f <- function(y) c(x,y)
          foo <- function(x) .Call("foo", x, PACKAGE="foo")
          print.foo <- function(x, ...) cat("<a foo>\n")

Some C code defines a C function compiled into DLL `foo' (with an
appropriate extension).  The `NAMESPACE' file for this package is

          useDynLib(foo)
          export(f, foo)
          S3method(print, foo)

The second package *bar* has code file `bar.R'

          c <- function(...) sum(...)
          g <- function(y) f(c(y, 7))
          h <- function(y) y+9

and `NAMESPACE' file

          import(foo)
          export(g, h)

Calling `library(bar)' loads *bar* and attaches its exports to the
search path.  Package *foo* is also loaded but not attached to the
search path.  A call to `g' produces

     > g(6)
     [1]  1 13

This is consistent with the definitions of `c' in the two settings: in
*bar* the function `c' is defined to be equivalent to `sum', but in
*foo* the variable `c' refers to the standard function `c' in *base*.


File: R-exts.info,  Node: Namespaces with S4 classes and methods,  Prev: An example,  Up: Package namespaces

1.5.6 Namespaces with S4 classes and methods
--------------------------------------------

Some additional steps are needed for packages which make use of formal
(S4-style) classes and methods (unless these are purely used
internally).  The package should have `Depends: methods' in its
`DESCRIPTION' file and any classes and methods which are to be exported
need to be declared in the `NAMESPACE' file.  For example, the *stats4*
package has

     export(mle) # exporting methods implicitly exports the generic
     importFrom("graphics", plot)
     importFrom("stats", optim, qchisq)
     ## For these, we define methods or (AIC, BIC, nobs) an implicit generic:
     importFrom("stats", AIC, BIC, coef, confint, logLik, nobs, profile,
                update, vcov)
     exportClasses(mle, profile.mle, summary.mle)
     ## All methods for imported generics:
     exportMethods(coef, confint, logLik, plot, profile, summary,
                   show, update, vcov)
     ## implicit generics which do not have any methods here
     export(AIC, BIC, nobs)

All S4 classes to be used outside the package need to be listed in an
`exportClasses' directive. Alternatively, they can be specified using
`exportClassPattern'(1) in the same style as for `exportPattern'.  To
export methods for generics from other packages an `exportMethods'
directive can be used.

   Note that exporting methods on a generic in the namespace will also
export the generic, and exporting a generic in the namespace will also
export its methods.  If the generic function is not local to this
package, either because it was imported as a generic function or because
the non-generic version has been made generic solely to add S4 methods
to it (as for functions such as `plot' in the example above), it can be
declared _via_ either or both of `export' or `exportMethods', but the
latter is clearer (and is used in the *stats4* example above).  In
particular, for primitive functions there is no generic function, so
`export' would export the primitive, which makes no sense.  On the other
hand, if the generic is local to this package, it is more natural to
export the function itself using `export()', and this _must_ be done if
an implicit generic is created without setting any methods for it (as
is the case for `AIC' in *stats4*).

   A non-local generic function is only exported to ensure that calls to
the function will dispatch the methods from this package (and that is
not done or required when the methods are for primitive functions).  For
this reason, you do not need to document such implicitly created generic
functions, and `undoc' in package *tools* will not report them.

   If a package uses S4 classes and methods exported from another
package, but does not import the entire namespace of the other package,
it needs to import the classes and methods explicitly, with directives

     importClassesFrom(package, ...)
     importMethodsFrom(package, ...)

listing the classes and functions with methods respectively.  Suppose we
had two small packages *A* and *B* with *B* using *A*.  Then they could
have `NAMESPACE' files

          export(f1, ng1)
          exportMethods("[")
          exportClasses(c1)

and

          importFrom(A, ng1)
          importClassesFrom(A, c1)
          importMethodsFrom(A, f1)
          export(f4, f5)
          exportMethods(f6, "[")
          exportClasses(c1, c2)

respectively.

   Note that `importMethodsFrom' will also import any generics defined
in the namespace on those methods.

   It is important if you export S4 methods that the corresponding
generics are available.  You may for example need to import `plot' from
*graphics* to make visible a function to be converted into its implicit
generic.  But it is better practice to make use of the generics
exported by *stats4* as this enables multiple packages to unambiguously
set methods on those generics.

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

   (1) This defaults to the same pattern as `exportPattern': use
something like `exportClassPattern("^$")' to override this.


File: R-exts.info,  Node: Writing portable packages,  Next: Diagnostic messages,  Prev: Package namespaces,  Up: Creating R packages

1.6 Writing portable packages
=============================

This section contains advice on writing packages to be used on multiple
platforms or for distribution (for example to be submitted to a package
repository such as CRAN).

* Menu:

* PDF size::
* Check timing::
* Encoding issues::
* Binary distribution::

   Portable packages should have simple file names: use only
alphanumeric ASCII characters and `.', and avoid those names not
allowed under Windows which are mentioned above.

   Use `R CMD build' to make the release `.tar.gz' file.

   `R CMD check' provides a basic set of checks, but often further
problems emerge when people try to install and use packages submitted to
CRAN - many of these involve compiled code.  Here are some further
checks that you can do to make your package more portable.

   * If your package has a `configure' script, provide a
     `configure.win' script to be used on Windows (an empty file if no
     actions are needed).

   * If your package has a `Makevars' or `Makefile' file, make sure
     that you use only portable make features.  Such files should be
     LF-terminated (including the final line of the file) and not make
     use of GNU extensions.  Commonly misused GNU extensions are
     conditional inclusions (`ifeq' and the like), `${shell ...}' and
     `${wildcard ...}', and the use of `+=' and `:='.  Also, the use of
     `$<' other than in implicit rules is a GNU extension.
     Unfortunately makefiles which use GNU extensions often run on other
     platforms but do not have the intended results.

     The use of `${shell ...}' can be avoided by using backticks, e.g.

          PKG_CPPFLAGS = `gsl-config --cflags`

     which works in all versions of `make' known(1) to be used with R.

     If you really must assume GNU make, declare it in the `DESCRIPTON'
     file by

          SystemRequirements: GNU make

     Since the only viable make for Windows is GNU make, it is
     permissible to use GNU extensions in files `Makevars.win' or
     `Makefile.win'.

   * Make use of the abilities of your compilers to check the
     standards-conformance of your code.  For example, `gcc' can be
     used with options `-Wall -pedantic' to alert you to potential
     problems.  This is particularly important for C++, where `g++ -Wall
     -pedantic' will alert you to the use of GNU extensions which fail
     to compile on most other C++ compilers. If R was not configured
     accordingly, one can achieve this _via_ personal `Makevars' files.
     *Note Customizing package compilation: (R-admin)Customizing
     package compilation,

     Although there is a 2011 version of the C++ standard, it is not yet
     fully implemented (nor is it likely to be widely available for some
     years) and portable C++ code needs to follow the 1998 standard
     (and not use features from C99).

     Similarly, the 2011 C standard is unlikely to be widely
     implemented for several years.

     If you use FORTRAN 77, `ftnchek'
     (`http://www.dsm.fordham.edu/~ftnchek/') provides thorough testing
     of conformance to the standard.

   * Do be very careful with passing arguments between R, C and FORTRAN
     code.  In particular, `long' in C will be 32-bit on some R
     platforms (including 64-bit Windows), but 64-bit on most modern
     Unix and Linux platforms.  It is rather unlikely that the use of
     `long' in C code has been thought through: if you need a longer
     type than `int' you should use a configure test for a C99 type such
     as `int_fast64_t' (and failing that, `long long' (2)) and typedef
     your own type to be `long' or `long long', or use another suitable
     type (such as `size_t').

     It is not safe to assume that `long' and pointer types are the same
     size, and they are not on 64-bit Windows.  If you need to convert
     pointers to and from integers use the C99 integer types `intptr_t'
     and `uintptr_t' (which are defined in the header `<stdint.h>' and
     are not required to be implemented by the C99 standard).

     Note that `integer' in FORTRAN corresponds to `int' in C on all R
     platforms.

   * Under no circumstances should your compiled code ever call `abort'
     or `exit': these terminate the user's R process, quite possibly
     including all his unsaved work.  One usage that could call `abort'
     is the `assert' macro in C or C++ functions, which should never be
     active in production code.  The normal way to ensure that is to
     define the macro `NDEBUG', and `R CMD INSTALL' does so as part of
     the compilation flags.  If you wish to use `assert' during
     development. you can include `-UNDEBUG' in `PKG_CPPFLAGS'.  Note
     that your own `src/Makefile' or makefiles in sub-directories may
     also need to define `NDEBUG'.

     This applies not only to your own code but to any external
     software you compile in or link to.

   * Compiled code should not write to `stdout' or `stderr' and C++ and
     Fortran I/O should not be used.  As with the previous item such
     calls may come from external software and may never be called, but
     package authors are often mistaken about that.

   * Errors in memory allocation and reading/writing outside arrays are
     very common causes of crashes (e.g., segfaults) on some machines.
     See *Note Using valgrind:: for a tool which can be used to look
     for this.

   * Many platforms will allow unsatisfied entry points in compiled
     code, but will crash the application (here R) if they are ever
     used.  Some (notably Windows) will not.  Looking at the output of

          nm -pg mypkg.so  # or other extension such as `.sl'

     and checking if any of the symbols marked `U' is unexpected is a
     good way to avoid this.

   * Conflicts between symbols in DLLs are handled in very
     platform-specific ways.  Good ways to avoid trouble are to make as
     many symbols as possible static (check with `nm -pg'), and to use
     names which are clearly tied to your package (which also helps
     users if anything does go wrong).

   * It is not portable to call compiled code in R or other packages
     _via_ `.Internal', `.C', `.Fortran', `.Call' or `.External', since
     such interfaces are subject to change without notice and will
     probably result in your code terminating the R process.

   * Do not use (hard or symbolic) file links in your package sources.
     Where possible `R CMD build' will replace them by copies.

   * If you do not yourself have a Windows system, consider submitting
     your source package to WinBuilder
     (`http://win-builder.r-project.org/') before distribution.


   Do be careful in what your tests actually test.  Bad practice seen in
distributed packages include:

   * It is not reasonable to test the time taken by a command: you
     cannot know how fast or how heavily loaded an R platform might be.
     At best you can test a ratio of times, and even that is fraught
     with difficulties.

   * Do not test the exact format of R error messages: they change, and
     they can be translated.

   * Only test the accuracy of results if you have done a formal error
     analysis.  Things such as checking that probabilities numerically
     sum to one are silly: numerical tests should always have a
     tolerance.  That the tests on your platform achieve a particular
     tolerance says little about other platforms.  Most R platforms use
     `ix86' or `x86_64' CPUs: these use extended precision registers on
     some but not all of their FPU instructions.  Thus the achieved
     precision can depend on the compiler version and optimization
     flags--our experience is that 32-bit builds tend to be less
     precise than 64-bit ones.  But not all platforms use those CPUs,
     and not all(3)  which use them configure them allow the use of
     extended precision.

     If you must try to establish a tolerance empirically, configure and
     build R with `--disable-long-doubles' and use appropriate compiler
     flags (such as `-ffloat-store' for `gcc') to mitigate the effects
     of extended-precision calculations.


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

   (1) GNU make, BSD make as in FreeBSD, AT&T make as implemented on
Solaris.

   (2) but note that `long long' is not a standard C++ type, and C++
compilers set up for strict checking will reject it.

   (3) Not doing so is the default on Windows, overridden for the R
executables.  It is also the default on some Solaris compilers.


File: R-exts.info,  Node: PDF size,  Next: Check timing,  Prev: Writing portable packages,  Up: Writing portable packages

1.6.1 PDF size
--------------

There are a several tools available to reduce the size of PDF files:
often the size can be reduced substantially with no or minimal loss in
quality. Not only do large files take up space: they can stress the PDF
viewer and take many minutes to print (if they can be printed at all).

   `qpdf' (`http://qpdf.sourceforge.net/') can compress losslessly.  It
is fairly readily available (e.g. it has binaries for Windows and
packages in Debian/Ubuntu/Fedora 17, and is installed as part of the
CRAN OS X distribution of R).  `R CMD build' has an option to run
`qpdf' over PDF files under `inst/doc' and replace them if at least
10Kb and 10% is saved.  The full path to the `qpdf' command can be
supplied as environment variable `R_QPDF' (and is on the CRAN binary of
R for OS X).  It seems MiKTeX does not use PDF object compression and
so `qpdf' can reduce considerably the files it outputs: MiKTeX can be
overridden by code in the preamble of an Sweave or LaTeX file -- see
how this is done for the R reference manual at
`https://svn.r-project.org/R/trunk/doc/manual/refman.top'.

   Other tools can reduce the size of PDFs containing bitmap images at
excessively high resolution.  These are often best re-generated (for
example `Sweave' defaults to 300 ppi, and 100-150 is more appropriate
for a package manual).  These tools include Adobe Acrobat (not Reader),
Apple's Preview(1)  and Ghostscript (which converts PDF to PDF by

     ps2pdf OPTIONS -dAutoRotatePages=/None IN.pdf OUT.pdf

and suitable options might be

     -dPDFSETTINGS=/ebook
     -dPDFSETTINGS=/screen

; see `http://www.ghostscript.com/doc/9.07/Ps2pdf.htm' for more such
and consider all the options for image downsampling).   We come across
occasionally large PDF files containing excessively complicated figures
using PDF vector graphics: such figures are often best redesigned or
failing that, output as PNG files.

   Option `--compact-vignettes' to `R CMD build' defaults to value
`qpdf': use `both' to try harder to reduce the size, provided you have
Ghostscript available (see the help for `tools::compactPDF').

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

   (1) Select `Save as', and select `Reduce file size' from the `Quartz
filter' menu': this can be accessed in other ways, for example by
Automator.


File: R-exts.info,  Node: Check timing,  Next: Encoding issues,  Prev: PDF size,  Up: Writing portable packages

1.6.2 Check timing
------------------

There are several ways to find out where time is being spent in the
check process.  Start by setting the environment variable
`_R_CHECK_TIMINGS_' to `0'.  This will report the total CPU times (not
Windows) and elapsed times for installation and running examples, tests
and vignettes, under each sub-architecture if appropriate.  For tests
and vignettes, it reports the time for each as well as the total.

   Setting `_R_CHECK_TIMINGS_' to a positive value sets a threshold (in
seconds elapsed time) for reporting timings.

   If you need to look in more detail at the timings for examples, use
option `--timings' to `R CMD check'.  This adds a summary to the check
output for all the examples with CPU or elapsed time of more than 5
seconds. It produces a file `MYPKG.Rcheck/MYPKG-Ex.timings' containing
timings for each help file: it is a tab-delimited file which can be
read into R for further analysis.

   Timings for the tests and vignette runs are given at the bottom of
the corresponding log file: note that log files for successful vignette
runs are only retained if `_R_CHECK_ALWAYS_LOG_VIGNETTE_OUTPUT_' is set
to a true value.


File: R-exts.info,  Node: Encoding issues,  Next: Binary distribution,  Prev: Check timing,  Up: Writing portable packages

1.6.3 Encoding issues
---------------------

Care is needed if your package contains non-ASCII text, and in
particular if it is intended to be used in more than one locale.  It is
possible to mark the encoding used in the `DESCRIPTION' file and in
`.Rd' files, as discussed elsewhere in this manual.

   First, consider carefully if you really need non-ASCII text.  Many
users of R will only be able to view correctly text in their native
language group (e.g. Western European, Eastern European, Simplified
Chinese) and ASCII.(1).  Other characters may not be rendered at all,
rendered incorrectly, or cause your R code to give an error.  For `.Rd'
documentation, marking the encoding and including ASCII
transliterations is likely to do a reasonable job.  The set of
characters which is commonly supported is wider than it used to be
around 2000, but non-Latin alphabets (Greek, Russian, Georgian, ...)
are still often problematic and those with double-width characters
(Chinese, Japanese, Korean) often need specialist fonts to render
correctly.

   Several CRAN packages have messages in their R code in French (and a
few in German).  A better way to tackle this is to use the
internationalization facilities discussed elsewhere in this manual.

   Function `showNonASCIIfile' in package *tools* can help in finding
non-ASCII bytes in files.

   There is a portable way to have arbitrary text in character strings
(only) in your R code, which is to supply them in Unicode as `\uxxxx'
escapes.  If there are any characters not in the current encoding the
parser will encode the character string as UTF-8 and mark it as such.
This applies also to character strings in datasets: they can be
prepared using `\uxxxx' escapes or encoded in UTF-8 in a UTF-8 locale,
or even converted to UTF-8 via `iconv()'.  If you do this, make sure
you have `R (>= 2.10)' (or later) in the `Depends' field of the
`DESCRIPTION' file.

   R sessions running in non-UTF-8 locales will if possible re-encode
such strings for display (and this is done by `RGui' on Windows, for
example).  Suitable fonts will need to be selected or made available(2)
both for the console/terminal and graphics devices such as `X11()' and
`windows()'.  Using `postscript' or `pdf' will choose a default 8-bit
encoding depending on the language of the UTF-8 locale, and your users
would need to be told how to select the `encoding' argument.

   If you want to run `R CMD check' on a Unix-alike over a package that
sets a package encoding in its `DESCRIPTION' file you may need to
specify a suitable locale _via_ environment variable
`R_ENCODING_LOCALES'.  The default is equivalent to the value

     "latin1=en_US:latin2=pl_PL:UTF-8=en_US.UTF-8:latin9=fr_FR.iso885915@euro"

(which is appropriate for a system based on `glibc') except that if the
current locale is UTF-8 then the package code is translated to UTF-8
for syntax checking.

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

   (1) except perhaps some special characters such as backslash and
hash which may be taken over for currency symbols.

   (2) Typically on a Unix-alike this is done by telling `fontconfig'
where to find suitable fonts to select glyphs from.


File: R-exts.info,  Node: Binary distribution,  Prev: Encoding issues,  Up: Writing portable packages

1.6.4 Binary distribution
-------------------------

If you want to distribute a binary version of a package on Windows or OS
X, there are further checks you need to do to check it is portable: it
is all too easy to depend on external software on your own machine that
other users will not have.

   For Windows, check what other DLLs your package's DLL depends on
(`imports' from in the DLL tools' parlance).  A convenient GUI-based
tool to do so is `Dependency Walker'
(`http://www.dependencywalker.com/') for both 32-bit and 64-bit DLLs -
note that this will report as missing links to R's own DLLs such as
`R.dll' and `Rblas.dll'.  For 32-bit DLLs only, the command-line tool
`pedump.exe -i' (in `Rtools*.exe') can be used, and for the brave, the
`objdump' tool in the appropriate toolchain will also reveal what DLLs
are imported from.  If you use a toolchain other than one provided by
the R developers or use your own makefiles, watch out in particular for
dependencies on the toolchain's runtime DLLs such as `libgfortran',
`libstdc++' and `libgcc_s'.

   For OS X, using `R CMD otool -L' on the package's shared objects in
the `libs' directory will show what they depend on: watch for any
dependencies in `/usr/local/lib', notably `libgfortran.2.dylib'.

   Many people (including the CRAN package repository) will not accept
source packages containing binary files as the latter are a security
risk.  If you want to distribute a source package which needs external
software on Windows or OS X, options include
   * To arrange for installation of the package to download the
     additional software from a URL, as e.g. package *Cairo*
     (http://CRAN.R-project.org/package=Cairo) does.

   * (For CRAN.)  To negotiate with Uwe Ligges to host the additional
     components on WinBuilder, and write a `configure.win' file to
     install them.  There used to be many examples, e.g. package
     *rgdal* (http://CRAN.R-project.org/package=rgdal) (however
     nowadays CRAN prefers to use a uniform cross-compilation approach
     for software such as GDAL).


Be aware that license requirements will need to be met so you may need
to supply the sources for the additional components (and will if your
package has a GPL-like license).


File: R-exts.info,  Node: Diagnostic messages,  Next: Internationalization,  Prev: Writing portable packages,  Up: Creating R packages

1.7 Diagnostic messages
=======================

Diagnostic messages can be made available for translation, so it is
important to write them in a consistent style.  Using the tools
described in the next section to extract all the messages can give a
useful overview of your consistency (or lack of it).  Some guidelines
follow.

   * Messages are sentence fragments, and not viewed in isolation.  So
     it is conventional not to capitalize the first word and not to end
     with a period (or other punctuation).

   * Try not to split up messages into small pieces.  In C error
     messages use a single format string containing all English words
     in the messages.

     In R error messages do not construct a message with `paste' (such
     messages will not be translated) but _via_ multiple arguments to
     `stop' or `warning', or _via_ `gettextf'.

   * Do not use colloquialisms such as "can't" and "don't".

   * Conventionally single quotation marks are used for quotations such
     as

          'ord' must be a positive integer, at most the number of knots

     and double quotation marks when referring to an R character string
     or a class, such as

          'format' must be "normal" or "short" - using "normal"

     Since ASCII does not contain directional quotation marks, it is
     best to use `'' and let the translator (including automatic
     translation) use directional quotations where available.  The
     range of quotation styles is immense: unfortunately we cannot
     reproduce them in a portable `texinfo' document.  But as a taster,
     some languages use `up' and `down' (comma) quotes rather than left
     or right quotes, and some use guillemets (and some use what Adobe
     calls `guillemotleft' to start and others use it to end).

     In R messages it is also possible to use `sQuote' or `dQuote' as in

                  stop(gettextf("object must be of class %s or %s",
                                dQuote("manova"), dQuote("maov")),
                       domain = NA)

   * Occasionally messages need to be singular or plural (and in other
     languages there may be no such concept or several plural forms -
     Slovenian has four).  So avoid constructions such as was once used
     in `library'

          if((length(nopkgs) > 0) && !missing(lib.loc)) {
              if(length(nopkgs) > 1)
                  warning("libraries ",
                          paste(sQuote(nopkgs), collapse = ", "),
                          " contain no packages")
              else
                  warning("library ", paste(sQuote(nopkgs)),
                          " contains no package")
          }

     and was replaced by

          if((length(nopkgs) > 0) && !missing(lib.loc)) {
              pkglist <- paste(sQuote(nopkgs), collapse = ", ")
              msg <- sprintf(ngettext(length(nopkgs),
                                      "library %s contains no packages",
                                      "libraries %s contain no packages",
                                      domain = "R-base"),
                             pkglist)
              warning(msg, domain=NA)
          }

     Note that it is much better to have complete clauses as here, since
     in another language one might need to say `There is no package in
     library %s' or `There are no packages in libraries %s'.



File: R-exts.info,  Node: Internationalization,  Next: CITATION files,  Prev: Diagnostic messages,  Up: Creating R packages

1.8 Internationalization
========================

There are mechanisms to translate the R- and C-level error and warning
messages.  There are only available if R is compiled with NLS support
(which is requested by `configure' option `--enable-nls', the default).

   The procedures make use of `msgfmt' and `xgettext' which are part of
GNU `gettext' and this will need to be installed: Windows users can
find pre-compiled binaries at
`http://www.stats.ox.ac.uk/pub/Rtools/goodies/gettext-tools.zip'.

* Menu:

* C-level messages::
* R messages::
* Preparing translations::


File: R-exts.info,  Node: C-level messages,  Next: R messages,  Prev: Internationalization,  Up: Internationalization

1.8.1 C-level messages
----------------------

The process of enabling translations is

   * In a header file that will be included in all the C (or C++ or
     Objective C/C++) files containing messages that should be
     translated, declare

          #include <R.h>  /* to include Rconfig.h */

          #ifdef ENABLE_NLS
          #include <libintl.h>
          #define _(String) dgettext ("PKG", String)
          /* replace PKG as appropriate */
          #else
          #define _(String) (String)
          #endif

   * For each message that should be translated, wrap it in `_(...)',
     for example

          error(_("'ord' must be a positive integer"));

     If you want to use different messages for singular and plural
     forms, you need to add

          #ifndef ENABLE_NLS
          #define dngettext(pkg, String, StringP, N) (N > 1 ? StringP : String)
          #endif

     and mark strings by

          dngettext(("PKG", <SINGULAR STRING>, <PLURAL STRING>, n)

   * In the package's `src' directory run

          xgettext --keyword=_ -o PKG.pot *.c


   The file `src/PKG.pot' is the template file, and conventionally this
is shipped as `po/PKG.pot'.


File: R-exts.info,  Node: R messages,  Next: Preparing translations,  Prev: C-level messages,  Up: Internationalization

1.8.2 R messages
----------------

Mechanisms are also available to support the automatic translation of R
`stop', `warning' and `message' messages.  They make use of message
catalogs in the same way as C-level messages, but using domain `R-PKG'
rather than `PKG'.  Translation of character strings inside `stop',
`warning' and `message' calls is automatically enabled, as well as
other messages enclosed in calls to `gettext' or `gettextf'.  (To
suppress this, use argument `domain=NA'.)

   Tools to prepare the `R-PKG.pot' file are provided in package
*tools*: `xgettext2pot' will prepare a file from all strings occurring
inside `gettext'/`gettextf', `stop', `warning' and `message' calls.
Some of these are likely to be spurious and so the file is likely to
need manual editing.  `xgettext' extracts the actual calls and so is
more useful when tidying up error messages.

   The R function `ngettext' provides an interface to the C function of
the same name: see example in the previous section.  It is safest to
use `domain="R-PKG"' explicitly in calls to `ngettext', and necessary
for earlier versions of R unless they are calls directly from a
function in the package.


File: R-exts.info,  Node: Preparing translations,  Prev: R messages,  Up: Internationalization

1.8.3 Preparing translations
----------------------------

Once the template files have been created, translations can be made.
Conventional translations have file extension `.po' and are placed in
the `po' subdirectory of the package with a name that is either `LL.po'
or `R-LL.po' for translations of the C and R messages respectively to
language with code `LL'.

   *Note Localization of messages: (R-admin)Localization of messages,
for details of language codes.

   There is an R function, `update_pkg_po' in package *tools*, to
automate much of the maintenance of message translations.  See its help
for what it does in detail.

   If this is called on a package with no existing translations, it
creates the directory `PKGDIR/po', creates a template file of R
messages, `PKGDIR/po/R-PKG.pot', within it, creates the `en@quot'
translation and installs that.  (The `en@quot' pseudo-language
interprets quotes in their directional forms in suitable (e.g. UTF-8)
locales.)

   If the package has C source files in its `src' directory that are
marked for translation, use

     touch PKGDIR/po/PKG.pot

to create a dummy template file, then call `update_pkg_po' again (this
can also be done before it is called for the first time).

   When translations to new languages are added in the `PKGDIR/po'
directory, running the same command will check and then install the
translations.

   If the package sources are updated, the same command will update the
template files, merge the changes into the translation `.po' files and
then installed the updated translations.  You will often see that
merging marks translations as `fuzzy' and this is reported in the
coverage statistics.  As fuzzy translations are _not_ used, this is an
indication that the translation files need human attention.

   The merged translations are run through `tools::checkPofile' to
check that C-style formats are used correctly: if not the mismatches are
reported and the broken translations are not installed.

   This function needs the GNU `gettext-tools' installed and on the
path: see its help page.


File: R-exts.info,  Node: CITATION files,  Next: Package types,  Prev: Internationalization,  Up: Creating R packages

1.9 CITATION files
==================

An installed file named `CITATION' will be used by the `citation()'
function.  (To be installed, it needed to be in the `inst' subdirectory
of the package sources.)

   The `CITATION' file is parsed as R code (in the package's declared
encoding, or in ASCII if none is declared).  If no such file is
present, `citation' auto-generates citation information from the
package `DESCRIPTION' metadata, and an example of what that would look
like as a `CITATION' file can be seen in recommended package *nlme*
(http://CRAN.R-project.org/package=nlme) (see below): recommended
packages *boot* (http://CRAN.R-project.org/package=boot), *cluster*
(http://CRAN.R-project.org/package=cluster) and *mgcv*
(http://CRAN.R-project.org/package=mgcv) have further examples.

   A `CITATION' file will contain calls to function `bibentry'.

   Here is that for *nlme* (http://CRAN.R-project.org/package=nlme),
re-formatted:

     citHeader("To cite package 'nlme' in publications use:")

     year <- sub(".*(2[[:digit:]]{3})-.*", "\\1", meta$Date, perl = TRUE)
     vers <- paste("R package version", meta$Version)

     citEntry(entry = "Manual",
              title = "nlme: Linear and Nonlinear Mixed Effects Models",
              author = personList(as.person("Jose Pinheiro"),
                                  as.person("Douglas Bates"),
                                  as.person("Saikat DebRoy"),
                                  as.person("Deepayan Sarkar"),
                                  person("R Core Team")),
              year = year,
              note = vers,

              textVersion =
              paste0("Jose Pinheiro, Douglas Bates, Saikat DebRoy,",
                     "Deepayan Sarkar and the R Core Team (",
                     year,
                     "). nlme: Linear and Nonlinear Mixed Effects Models. ",
                     vers, "."))

   Note the way that information that may need to be updated is picked
up from the `DESCRIPTION' file - it is tempting to hardcode such
information, but it normally then gets outdated.  See `?bibentry' for
further details of the information which can be provided.

   The `CITATION' file should itself produce no output when `source'-d.


File: R-exts.info,  Node: Package types,  Next: Services,  Prev: CITATION files,  Up: Creating R packages

1.10 Package types
==================

The `DESCRIPTION' file has an optional field `Type' which if missing is
assumed to be `Package', the sort of extension discussed so far in this
chapter.  Currently one other type is recognized; there used also to be
a `Translation' type.

* Menu:

* Frontend::


File: R-exts.info,  Node: Frontend,  Prev: Package types,  Up: Package types

1.10.1 Frontend
---------------

This is a rather general mechanism, designed for adding new front-ends
such as the former *gnomeGUI* package (see the `Archive' area on CRAN).
If a `configure' file is found in the top-level directory of the
package it is executed, and then if a `Makefile' is found (often
generated by `configure'), `make' is called.  If `R CMD INSTALL
--clean' is used `make clean' is called.  No other action is taken.

   `R CMD build' can package up this type of extension, but `R CMD
check' will check the type and skip it.

   Many packages of this type need write permission for the R
installation directory.


File: R-exts.info,  Node: Services,  Prev: Package types,  Up: Creating R packages

1.11 Services
=============

Several members of the R project have set up services to assist those
writing R packages, particularly those intended for public distribution.

   win-builder.r-project.org (http://win-builder.r-project.org) offers
the automated preparation of (32/64-bit) Windows binaries from
well-tested source packages.

   R-Forge (R-Forge.r-project.org (http://R-Forge.r-project.org)) and
RForge (www.rforge.net (http://www.rforge.net)) are similar services
with similar names.  Both provide source-code management through SVN,
daily building and checking, mailing lists and a repository that can be
accessed _via_ `install.packages' (they can be selected by
`setRepositories' and the GUI menus that use it).  Package developers
have the opportunity to present their work on the basis of project
websites or news announcements.  Mailing lists, forums or wikis provide
useRs with convenient instruments for discussions and for exchanging
information between developers and/or interested useRs.


File: R-exts.info,  Node: Writing R documentation files,  Next: Tidying and profiling R code,  Prev: Creating R packages,  Up: Top

2 Writing R documentation files
*******************************

* Menu:

* Rd format::
* Sectioning::
* Marking text::
* Lists and tables::
* Cross-references::
* Mathematics::
* Figures::
* Insertions::
* Indices::
* Platform-specific sections::
* Conditional text::
* Dynamic pages::
* User-defined macros::
* Encoding::
* Processing documentation files::
* Editing Rd files::


File: R-exts.info,  Node: Rd format,  Next: Sectioning,  Prev: Writing R documentation files,  Up: Writing R documentation files

2.1 Rd format
=============

R objects are documented in files written in "R documentation" (Rd)
format, a simple markup language much of which closely resembles
(La)TeX, which can be processed into a variety of formats, including
LaTeX, HTML and plain text.  The translation is carried out by
functions in the *tools* package called by the script `Rdconv' in
`R_HOME/bin' and by the installation scripts for packages.

   The R distribution contains more than 1300 such files which can be
found in the `src/library/PKG/man' directories of the R source tree,
where PKG stands for one of the standard packages which are included in
the R distribution.

   As an example, let us look at a simplified version of
`src/library/base/man/load.Rd' which documents the R function `load'.

          % File src/library/base/man/load.Rd
          \name{load}
          \alias{load}
          \title{Reload Saved Datasets}
          \description{
            Reload the datasets written to a file with the function
            \code{save}.
          }
          \usage{
          load(file, envir = parent.frame())
          }
          \arguments{
            \item{file}{a connection or a character string giving the
              name of the file to load.}
            \item{envir}{the environment where the data should be
              loaded.}
          }
          \seealso{
            \code{\link{save}}.
          }
          \examples{
          ## save all data
          save(list = ls(), file= "all.RData")

          ## restore the saved values to the current environment
          load("all.RData")

          ## restore the saved values to the workspace
          load("all.RData", .GlobalEnv)
          }
          \keyword{file}

   An `Rd' file consists of three parts.  The header gives basic
information about the name of the file, the topics documented, a title,
a short textual description and R usage information for the objects
documented.  The body gives further information (for example, on the
function's arguments and return value, as in the above example).
Finally, there is an optional footer with keyword information.  The
header is mandatory.

   Information is given within a series of _sections_ with standard
names (and user-defined sections are also allowed).  Unless otherwise
specified(1) these should occur only once in an `Rd' file (in any
order), and the processing software will retain only the first
occurrence of a standard section in the file, with a warning.

   See "Guidelines for Rd files"
(http://developer.r-project.org/Rds.html) for guidelines for writing
documentation in `Rd' format which should be useful for package writers.  The
R generic function `prompt' is used to construct a bare-bones `Rd' file
ready for manual editing.  Methods are defined for documenting
functions (which fill in the proper function and argument names) and
data frames.  There are also functions `promptData', `promptPackage',
`promptClass', and `promptMethods' for other types of `Rd' file.

   The general syntax of `Rd' files is summarized below.  For a detailed
technical discussion of current `Rd' syntax, see "Parsing Rd files"
(http://developer.r-project.org/parseRd.pdf).

   `Rd' files consists of three types of text input.  The most common
is LaTeX-like, with the backslash used as a prefix on markup (e.g.
`\alias'), and braces used to indicate arguments (e.g. `{load}').  The
least common type of text is verbatim text, where no markup is
processed. The third type is R-like, intended for R code, but allowing
some embedded macros.  Quoted strings within R-like text are handled
specially: regular character escapes such as `\n' may be entered as-is.
Only markup starting with `\l' (e.g.  `\link') or `\v' (e.g. `\var')
will be recognized within quoted strings.  The rarely used vertical tab
`\v' must be entered as `\\v'.

   Each macro defines the input type for its argument.  For example, the
file initially uses LaTeX-like syntax, and this is also used in the
`\description' section, but the `\usage' section uses R-like syntax,
and the `\alias' macro uses verbatim syntax.  Comments run from a
percent symbol `%' to the end of the line in all types of text (as on
the first line of the `load' example).

   Because backslashes, braces and percent symbols have special
meaning, to enter them into text sometimes requires escapes using a
backslash.  In general balanced braces do not need to be escaped, but
percent symbols always do.  For the complete list of macros and rules
for escapes, see "Parsing Rd files"
(http://developer.r-project.org/parseRd.pdf).

* Menu:

* Documenting functions::
* Documenting data sets::
* Documenting S4 classes and methods::
* Documenting packages::

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

   (1) e.g. `\alias', `\keyword' and `\note' sections.


File: R-exts.info,  Node: Documenting functions,  Next: Documenting data sets,  Prev: Rd format,  Up: Rd format

2.1.1 Documenting functions
---------------------------

The basic markup commands used for documenting R objects (in
particular, functions) are given in this subsection.

`\name{NAME}'
     NAME typically(1) is the basename of the `Rd' file containing the
     documentation.  It is the "name" of the `Rd' object represented by
     the file and has to be unique in a package.  To avoid problems
     with indexing the package manual, it may not contain `!'  `|' nor
     `@', and to avoid possible problems with the HTML help system it
     should not contain `/' nor a space.  (LaTeX special characters are
     allowed, but may not be collated correctly in the index.)  There
     can only be one `\name' entry in a file, and it must not contain
     any markup.  Entries in the package manual will be in
     alphabetic(2) order of the `\name' entries.

`\alias{TOPIC}'
     The `\alias' sections specify all "topics" the file documents.
     This information is collected into index data bases for lookup by
     the on-line (plain text and HTML) help systems.  The TOPIC can
     contain spaces, but (for historical reasons) leading and trailing
     spaces will be stripped.  Percent and left brace need to be
     escaped by a backslash.

     There may be several `\alias' entries.  Quite often it is
     convenient to document several R objects in one file.  For example,
     file `Normal.Rd' documents the density, distribution function,
     quantile function and generation of random variates for the normal
     distribution, and hence starts with

          \name{Normal}
          \alias{Normal}
          \alias{dnorm}
          \alias{pnorm}
          \alias{qnorm}
          \alias{rnorm}

     Also, it is often convenient to have several different ways to
     refer to an R object, and an `\alias' does not need to be the name
     of an object.

     Note that the `\name' is not necessarily a topic documented, and if
     so desired it needs to have an explicit `\alias' entry (as in this
     example).

`\title{TITLE}'
     Title information for the `Rd' file.  This should be capitalized
     and not end in a period; try to limit its length to at most 65
     characters for widest compatibility.

     Markup is supported in the text, but use of characters other than
     English text and punctuation (e.g., `<') may limit portability.

     There must be one (and only one) `\title' section in a help file.

`\description{...}'
     A short description of what the function(s) do(es) (one paragraph,
     a few lines only).  (If a description is too long and cannot
     easily be shortened, the file probably tries to document too much
     at once.)  This is mandatory except for package-overview files.

`\usage{FUN(ARG1, ARG2, ...)}'
     One or more lines showing the synopsis of the function(s) and
     variables documented in the file.  These are set in typewriter
     font.  This is an R-like command.

     The usage information specified should match the function
     definition _exactly_ (such that automatic checking for consistency
     between code and documentation is possible).

     It is no longer advisable to use `\synopsis' for the actual
     synopsis and show modified synopses in the `\usage'.  Support for
     `\synopsis' will be removed in \R 3.1.0.  To indicate that a
     function can be used in several different ways, depending on the
     named arguments specified, use section `\details'.  E.g.,
     `abline.Rd' contains

          \details{
            Typical usages are
          \preformatted{abline(a, b, untf = FALSE, \dots)
          ......
          }

     Use `\method{GENERIC}{CLASS}' to indicate the name of an S3 method
     for the generic function GENERIC for objects inheriting from class
     `"CLASS"'.  In the printed versions, this will come out as GENERIC
     (reflecting the understanding that methods should not be invoked
     directly but _via_ method dispatch), but `codoc()' and other QC
     tools always have access to the full name.

     For example, `print.ts.Rd' contains

          \usage{
          \method{print}{ts}(x, calendar, \dots)
          }

     which will print as

          Usage:

               ## S3 method for class 'ts':
               print(x, calendar, ...)

     Usage for replacement functions should be given in the style of
     `dim(x) <- value' rather than explicitly indicating the name of the
     replacement function (`"dim<-"' in the above).  Similarly, one can
     use `\method{GENERIC}{CLASS}(ARGLIST) <- value' to indicate the
     usage of an S3 replacement method for the generic replacement
     function `"GENERIC<-"' for objects inheriting from class `"CLASS"'.

     Usage for S3 methods for extracting or replacing parts of an
     object, S3 methods for members of the Ops group, and S3 methods
     for user-defined (binary) infix operators (`%XXX%') follows the
     above rules, using the appropriate function names.  E.g.,
     `Extract.factor.Rd' contains

          \usage{
          \method{[}{factor}(x, \dots, drop = FALSE)
          \method{[[}{factor}(x, \dots)
          \method{[}{factor}(x, \dots) <- value
          }

     which will print as

          Usage:

               ## S3 method for class 'factor':
               x[..., drop = FALSE]
               ## S3 method for class 'factor':
               x[[...]]
               ## S3 replacement method for class 'factor':
               x[...] <- value

     `\S3method' is accepted as an alternative to `\method'.

`\arguments{...}'
     Description of the function's arguments, using an entry of the form

          \item{ARG_I}{DESCRIPTION OF ARG_I.}

     for each element of the argument list.  (Note that there is no
     whitespace between the three parts of the entry.) There may be
     optional text outside the `\item' entries, for example to give
     general information about groups of parameters.

`\details{...}'
     A detailed if possible precise description of the functionality
     provided, extending the basic information in the `\description'
     slot.

`\value{...}'
     Description of the function's return value.

     If a list with multiple values is returned, you can use entries of
     the form

          \item{COMP_I}{DESCRIPTION OF COMP_I.}

     for each component of the list returned.  Optional text may
     precede(3) this list (see for example the help for `rle').  Note
     that `\value' is implicitly a `\describe' environment, so that
     environment should not be used for listing components, just
     individual `\item{}{}' entries.

`\references{...}'
     A section with references to the literature.  Use `\url{}' or
     `\href{}{}' for web pointers.

`\note{...}'
     Use this for a special note you want to have pointed out.  Multiple
     `\note' sections are allowed, but might be confusing to the end
     users.

     For example, `pie.Rd' contains

          \note{
            Pie charts are a very bad way of displaying information.
            The eye is good at judging linear measures and bad at
            judging relative areas.
            ......
          }

`\author{...}'
     Information about the author(s) of the `Rd' file.  Use `\email{}'
     without extra delimiters (such as `( )' or `< >') to specify email
     addresses, or `\url{}' or `\href{}{}' for web pointers.

`\seealso{...}'
     Pointers to related R objects, using `\code{\link{...}}' to refer
     to them (`\code' is the correct markup for R object names, and
     `\link' produces hyperlinks in output formats which support this.
     *Note Marking text::, and *Note Cross-references::).

`\examples{...}'
     Examples of how to use the function.  Code in this section is set
     in typewriter font without reformatting and is run by `example()'
     unless marked otherwise (see below).

     Examples are not only useful for documentation purposes, but also
     provide test code used for diagnostic checking of R code.  By
     default, text inside `\examples{}' will be displayed in the output
     of the help page and run by `example()' and by `R CMD check'.  You
     can use `\dontrun{}' for text that should only be shown, but not
     run, and `\dontshow{}' for extra commands for testing that should
     not be shown to users, but will be run by `example()'.
     (Previously this was called `\testonly', and that is still
     accepted.)

     Text inside `\dontrun{}' is verbatim, but the other parts of the
     `\examples' section are R-like text.

     For example,

          x <- runif(10)       # Shown and run.
          \dontrun{plot(x)}    # Only shown.
          \dontshow{log(x)}    # Only run.

     Thus, example code not included in `\dontrun' must be executable!
     In addition, it should not use any system-specific features or
     require special facilities (such as Internet access or write
     permission to specific directories).  Text included in `\dontrun'
     is indicated by comments in the processed help files: it need not
     be valid R code but the escapes must still be used for `%', `\'
     and unpaired braces as in other verbatim text.

     Example code must be capable of being run by `example', which uses
     `source'.  This means that it should not access `stdin', e.g. to
     `scan()' data from the example file.

     Data needed for making the examples executable can be obtained by
     random number generation (for example, `x <- rnorm(100)'), or by
     using standard data sets listed by `data()' (see `?data' for more
     info).

     Finally, there is `\donttest', used (at the beginning of a separate
     line) to mark code that should be run by `examples()' but not by
     `R CMD check'.  This should be needed only occasionally but can be
     used for code which might fail in circumstances that are hard to
     test for, for example in some locales.  (Use e.g. `capabilities()'
     to test for features needed in the examples wherever possible, and
     you can also use `try()' or `tryCatch()'.)

`\keyword{KEY}'
     There can be zero or more `\keyword' sections per file.  Each
     `\keyword' section should specify a single keyword, preferably one
     of the standard keywords as listed in file `KEYWORDS' in the R
     documentation directory (default `R_HOME/doc').  Use e.g.
     `RShowDoc("KEYWORDS")' to inspect the standard keywords from
     within R.  There can be more than one `\keyword' entry if the R
     object being documented falls into more than one category, or none.

     The special keyword `internal' marks a page of internal objects
     that are not part of the package's API.  If the help page for
     object `foo' has keyword `internal', then `help(foo)' gives this
     help page, but `foo' is excluded from several object indices,
     including the alphabetical list of objects in the HTML help system.

     `help.search()' can search by keyword, including user-defined
     values: however the `Search Engine & Keywords' HTML page accessed
     _via_ `help.start()' provides single-click access only to a
     pre-defined list of keywords.

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

   (1) There can be exceptions: for example `Rd' files are not allowed
to start with a dot, and have to be uniquely named on a
case-insensitive file system.

   (2) in the current locale, and with special treatment for LaTeX
special characters and with any `PKGNAME-package' topic moved to the
top of the list.

   (3) Text between or after list items is discouraged.


File: R-exts.info,  Node: Documenting data sets,  Next: Documenting S4 classes and methods,  Prev: Documenting functions,  Up: Rd format

2.1.2 Documenting data sets
---------------------------

The structure of `Rd' files which document R data sets is slightly
different.  Sections such as `\arguments' and `\value' are not needed
but the format and source of the data should be explained.

   As an example, let us look at `src/library/datasets/man/rivers.Rd'
which documents the standard R data set `rivers'.

          \name{rivers}
          \docType{data}
          \alias{rivers}
          \title{Lengths of Major North American Rivers}
          \description{
            This data set gives the lengths (in miles) of 141 \dQuote{major}
            rivers in North America, as compiled by the US Geological
            Survey.
          }
          \usage{rivers}
          \format{A vector containing 141 observations.}
          \source{World Almanac and Book of Facts, 1975, page 406.}
          \references{
            McNeil, D. R. (1977) \emph{Interactive Data Analysis}.
            New York: Wiley.
          }
          \keyword{datasets}

   This uses the following additional markup commands.

`\docType{...}'
     Indicates the "type" of the documentation object.  Always `data'
     for data sets, and `package' for `PKG-package.Rd' overview files.
     Documentation for S4 methods and classes uses `methods' (from
     `promptMethods()') and `class' (from `promptClass()').

`\format{...}'
     A description of the format of the data set (as a vector, matrix,
     data frame, time series, ...).  For matrices and data frames this
     should give a description of each column, preferably as a list or
     table.  *Note Lists and tables::, for more information.

`\source{...}'
     Details of the original source (a reference or URL).  In addition,
     section `\references' could give secondary sources and usages.

   Note also that when documenting data set BAR,

   * The `\usage' entry is always `BAR' or (for packages which do not
     use lazy-loading of data) `data(BAR)'.  (In particular, only
     document a _single_ data object per `Rd' file.)

   * The `\keyword' entry should always be `datasets'.

   If `BAR' is a data frame, documenting it as a data set can be
initiated _via_ `prompt(BAR)'.  Otherwise, the `promptData' function
may be used.


File: R-exts.info,  Node: Documenting S4 classes and methods,  Next: Documenting packages,  Prev: Documenting data sets,  Up: Rd format

2.1.3 Documenting S4 classes and methods
----------------------------------------

There are special ways to use the `?'  operator, namely `class?TOPIC'
and `methods?TOPIC', to access documentation for S4 classes and
methods, respectively.  This mechanism depends on conventions for the
topic names used in `\alias' entries.  The topic names for S4 classes
and methods respectively are of the form

     CLASS-class
     GENERIC,SIGNATURE_LIST-method

where SIGNATURE_LIST contains the names of the classes in the signature
of the method (without quotes) separated by `,' (without whitespace),
with `ANY' used for arguments without an explicit specification.  E.g.,
`genericFunction-class' is the topic name for documentation for the S4
class `"genericFunction"', and `coerce,ANY,NULL-method' is the topic
name for documentation for the S4 method for `coerce' for signature
`c("ANY", "NULL")'.

   Skeletons of documentation for S4 classes and methods can be
generated by using the functions `promptClass()' and `promptMethods()'
from package *methods*.  If it is necessary or desired to provide an
explicit function declaration (in a `\usage' section) for an S4 method
(e.g., if it has "surprising arguments" to be mentioned explicitly),
one can use the special markup

     \S4method{GENERIC}{SIGNATURE_LIST}(ARGUMENT_LIST)

(e.g., `\S4method{coerce}{ANY,NULL}(from, to)').

   To make full use of the potential of the on-line documentation
system, all user-visible S4 classes and methods in a package should at
least have a suitable `\alias' entry in one of the package's `Rd' files.
If a package has methods for a function defined originally somewhere
else, and does not change the underlying default method for the
function, the package is responsible for documenting the methods it
creates, but not for the function itself or the default method.

   An S4 replacement method is documented in the same way as an S3 one:
see the description of  `\method' in *Note Documenting functions::.

   See `help("Documentation", package = "methods")' for more
information on using and creating on-line documentation for S4 classes
and methods.


File: R-exts.info,  Node: Documenting packages,  Prev: Documenting S4 classes and methods,  Up: Rd format

2.1.4 Documenting packages
--------------------------

Packages may have an overview help page with an `\alias'
`PKGNAME-package', e.g. `utils-package' for the *utils* package, when
`package?PKGNAME' will open that help page.  If a topic named `PKGNAME'
does not exist in another `Rd' file, it is helpful to use this as an
additional `\alias'.

   Skeletons of documentation for a package can be generated using the
function `promptPackage()'.  If the `final = TRUE' argument is used,
then the `Rd' file will be generated in final form, containing the
information that would be produced up to `library(help = PKGNAME)'.
Otherwise (the default) comments will be inserted giving suggestions
for content.

   Apart from the mandatory `\name' and `\title' and the
`PKGNAME-package' alias, the only requirement for the package overview
page is that it include a `\docType{package}' statement.  All other
content is optional.  We suggest that it should be a short overview, to
give a reader unfamiliar with the package enough information to get
started.  More extensive documentation is better placed into a package
vignette (*note Writing package vignettes::) and referenced from this
page, or into individual man pages for the functions, datasets, or
classes.


File: R-exts.info,  Node: Sectioning,  Next: Marking text,  Prev: Rd format,  Up: Writing R documentation files

2.2 Sectioning
==============

To begin a new paragraph or leave a blank line in an example, just
insert an empty line (as in (La)TeX).  To break a line, use `\cr'.  

   In addition to the predefined sections (such as `\description{}',
`\value{}', etc.), you can "define" arbitrary ones by
`\section{SECTION_TITLE}{...}'.  For example

     \section{Warning}{
       You must not call this function unless ...
     }

For consistency with the pre-assigned sections, the section name (the
first argument to `\section') should be capitalized (but not all upper
case).  Whitespace between the first and second braced expressions is
not allowed.  Markup (e.g. `\code') within the section title may cause
problems with the latex conversion (depending on the version of macro
packages such as `hyperref') and so should be avoided.

   The `\subsection' macro takes arguments in the same format as
`\section', but is used within a section, so it may be used to nest
subsections within sections or other subsections.  There is no
predefined limit on the nesting level, but formatting is not designed
for more than 3 levels (i.e. subsections within subsections within
sections).

   Note that additional named sections are always inserted at a fixed
position in the output (before `\note', `\seealso' and the examples),
no matter where they appear in the input (but in the same order amongst
themselves as in the input).


File: R-exts.info,  Node: Marking text,  Next: Lists and tables,  Prev: Sectioning,  Up: Writing R documentation files

2.3 Marking text
================

The following logical markup commands are available for emphasizing or
quoting text.

`\emph{TEXT}'
`\strong{TEXT}'
     Emphasize TEXT using _italic_ and *bold* font if possible;
     `\strong' is regarded as stronger (more emphatic).

`\bold{TEXT}'
     Set TEXT in bold font if possible.

`\sQuote{TEXT}'
`\dQuote{TEXT}'
     Portably single or double quote TEXT (without hard-wiring the
     characters used for quotation marks).

   Each of the above commands takes LaTeX-like input, so other macros
may be used within TEXT.

   The following logical markup commands are available for indicating
specific kinds of text.  Except as noted, these take verbatim text
input, and so other macros may not be used within them.  Some characters
will need to be escaped (*note Insertions::).

`\code{TEXT}'
     Indicate text that is a literal example of a piece of an R program,
     e.g., a fragment of R code or the name of an R object.  Text is
     entered in R-like syntax, and displayed using `typewriter' font if
     possible.  Macros `\var' and `\link' are interpreted within TEXT.

`\preformatted{TEXT}'
     Indicate text that is a literal example of a piece of a program.
     Text is displayed using `typewriter' font if possible.  Formatting,
     e.g. line breaks, is preserved.  (Note that this includes a line
     break after the initial {, so typically text should start on the
     same line as the command.)

     Due to limitations in LaTeX as of this writing, this macro may not
     be nested within other markup macros other than `\dQuote' and
     `\sQuote', as errors or bad formatting may result.

`\kbd{KEYBOARD-CHARACTERS}'
     Indicate keyboard input, using `slanted typewriter' font if
     possible, so users can distinguish the characters they are
     supposed to type from computer output.  Text is entered verbatim.

`\samp{TEXT}'
     Indicate text that is a literal example of a sequence of
     characters, entered verbatim.  No wrapping or reformatting will
     occur.  Displayed using `typewriter' font if possible.

`\verb{TEXT}'
     Indicate text that is a literal example of a sequence of
     characters, with no interpretation of e.g. `\var', but which will
     be included within word-wrapped text.  Displayed using
     `typewriter' font if possible.

`\pkg{PACKAGE_NAME}'
     Indicate the name of an R package.  LaTeX-like.

`\file{FILE_NAME}'
     Indicate the name of a file.  Text is LaTeX-like, so backslash
     needs to be escaped.  Displayed using a distinct font if possible.

`\email{EMAIL_ADDRESS}'
     Indicate an electronic mail address.  LaTeX-like, will be rendered
     as a hyperlink in HTML and PDF conversion.  Displayed using
     `typewriter' font if possible.

`\url{UNIFORM_RESOURCE_LOCATOR}'
     Indicate a uniform resource locator (URL) for the World Wide Web.
     The argument is handled verbatim, and rendered as a hyperlink in
     HTML and PDF conversion.  Displayed using `typewriter' font if
     possible.

`\href{UNIFORM_RESOURCE_LOCATOR}{TEXT}'
     Indicate a hyperlink to the World Wide Web. The first argument is
     handled verbatim, and is used as the URL in the hyperlink, with the
     second argument of LaTeX-like text displayed to the user.

`\var{METASYNTACTIC_VARIABLE}'
     Indicate a metasyntactic variable.  In some cases this will be
     rendered distinctly, e.g. in italic, but not in all(1). LaTeX-like.

`\env{ENVIRONMENT_VARIABLE}'
     Indicate an environment variable. Verbatim.  Displayed using
     `typewriter' font if possible

`\option{OPTION}'
     Indicate a command-line option.  Verbatim.  Displayed using
     `typewriter' font if possible.

`\command{COMMAND_NAME}'
     Indicate the name of a command. LaTeX-like, so `\var' is
     interpreted.  Displayed using `typewriter' font if possible.

`\dfn{TERM}'
     Indicate the introductory or defining use of a term. LaTeX-like.

`\cite{REFERENCE}'
     Indicate a reference without a direct cross-reference _via_ `\link'
     (*note Cross-references::), such as the name of a book. LaTeX-like.

`\acronym{ACRONYM}'
     Indicate an acronym (an abbreviation written in all capital
     letters), such as GNU. LaTeX-like.

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

   (1) Currently it is rendered differently only in HTML conversions,
and LaTeX conversion outside `\usage' and `\examples' environments.


File: R-exts.info,  Node: Lists and tables,  Next: Cross-references,  Prev: Marking text,  Up: Writing R documentation files

2.4 Lists and tables
====================

The `\itemize' and `\enumerate' commands take a single argument, within
which there may be one or more `\item' commands.  The text following
each `\item' is formatted as one or more paragraphs, suitably indented
and with the first paragraph marked with a bullet point (`\itemize') or
a number (`\enumerate').

   Note that unlike argument lists, `\item' in these formats is
followed by a space and the text (not enclosed in braces).  For example

       \enumerate{
         \item A database consists of one or more records, each with one or
         more named fields.
         \item Regular lines start with a non-whitespace character.
         \item Records are separated by one or more empty lines.
       }

   `\itemize' and `\enumerate' commands may be nested.

   The `\describe' command is similar to `\itemize' but allows initial
labels to be specified.  Each `\item' takes two arguments, the label
and the body of the item, in exactly the same way as an argument or
value `\item'.  `\describe' commands are mapped to `<DL>' lists in HTML
and `\description' lists in LaTeX.

   The `\tabular' command takes two arguments.  The first gives for
each of the columns the required alignment (`l' for left-justification,
`r' for right-justification or `c' for centring.)  The second argument
consists of an arbitrary number of lines separated by `\cr', and with
fields separated by `\tab'.  For example:

       \tabular{rlll}{
         [,1] \tab Ozone   \tab numeric \tab Ozone (ppb)\cr
         [,2] \tab Solar.R \tab numeric \tab Solar R (lang)\cr
         [,3] \tab Wind    \tab numeric \tab Wind (mph)\cr
         [,4] \tab Temp    \tab numeric \tab Temperature (degrees F)\cr
         [,5] \tab Month   \tab numeric \tab Month (1--12)\cr
         [,6] \tab Day     \tab numeric \tab Day of month (1--31)
       }

There must be the same number of fields on each line as there are
alignments in the first argument, and they must be non-empty (but can
contain only spaces).  (There is no whitespace between `\tabular' and
the first argument, nor between the two arguments.)


File: R-exts.info,  Node: Cross-references,  Next: Mathematics,  Prev: Lists and tables,  Up: Writing R documentation files

2.5 Cross-references
====================

The markup `\link{FOO}' (usually in the combination
`\code{\link{FOO}}') produces a hyperlink to the help for FOO.  Here
FOO is a _topic_, that is the argument of `\alias' markup in another
`Rd' file (possibly in another package).  Hyperlinks are supported in
some of the formats to which `Rd' files are converted, for example HTML
and PDF, but ignored in others, e.g.  the text format.

   One main usage of `\link' is in the `\seealso' section of the help
page, *note Rd format::.

   Note that whereas leading and trailing spaces are stripped when
extracting a topic from a `\alias', they are not stripped when looking
up the topic of a `\link'.

   You can specify a link to a different topic than its name by
`\link[=DEST]{NAME}' which links to topic DEST with name NAME.  This
can be used to refer to the documentation for S3/4 classes, for example
`\code{"\link[=abc-class]{abc}"}' would be a way to refer to the
documentation of an S4 class `"abc"' defined in your package, and
`\code{"\link[=terms.object]{terms}"}' to the S3 `"terms"' class (in
package *stats*).  To make these easy to read in the source file,
`\code{"\linkS4class{abc}"}' expands to the form given above.

   There are two other forms of optional argument specified as
`\link[PKG]{FOO}' and `\link[PKG:BAR]{FOO}' to link to the package
*PKG*, to _files_ `FOO.html' and `BAR.html' respectively.  These are
rarely needed, perhaps to refer to not-yet-installed packages (but
there the HTML help system will resolve the link at run time) or in the
normally undesirable event that more than one package offers help on a
topic(1) (in which case the present package has precedence so this is
only needed to refer to other packages).  They are currently only used
in HTML help (and ignored for hyperlinks in LaTeX conversions of help
pages), and link to the file rather than the topic (since there is no
way to know which topics are in which files in an uninstalled package).
The *only* reason to use these forms for base and recommended packages
is to force a reference to a package that might be further down the
search path.  Because they have been frequently misused, the HTML help
system looks for topic `FOO' in package *PKG* if it does not find file
`FOO.html'.

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

   (1) a common example in CRAN packages is `\link[mgcv]{gam}'.


File: R-exts.info,  Node: Mathematics,  Next: Figures,  Prev: Cross-references,  Up: Writing R documentation files

2.6 Mathematics
===============

Mathematical formulae should be set beautifully for printed
documentation yet we still want something useful for text and HTML
online help.  To this end, the two commands `\eqn{LATEX}{ASCII}' and
`\deqn{LATEX}{ASCII}' are used.  Whereas `\eqn' is used for "inline"
formulae (corresponding to TeX's `$...$'), `\deqn' gives "displayed
equations" (as in LaTeX's `displaymath' environment, or TeX's
`$$...$$').  Both arguments are treated as verbatim text.

   Both commands can also be used as `\eqn{LATEXASCII}' (only _one_
argument) which then is used for both LATEX and ASCII.  No whitespace
is allowed between command and the first argument, nor between the
first and second arguments.

   The following example is from `Poisson.Rd':

       \deqn{p(x) = \frac{\lambda^x e^{-\lambda}}{x!}}{%
             p(x) = \lambda^x exp(-\lambda)/x!}
       for \eqn{x = 0, 1, 2, \ldots}.

   For text on-line help we get

              p(x) = lambda^x exp(-lambda)/x!

          for x = 0, 1, 2, ....

   Greek letters (both cases) will be rendered in HTML if preceded by a
backslash, `\dots' and `\ldots' will be rendered as ellipses and
`\sqrt', `\ge' and `\le' as mathematical symbols.

   Note that only basic LaTeX can be used, there being no provision to
specify LaTeX style files such as the AMS extensions.


File: R-exts.info,  Node: Figures,  Next: Insertions,  Prev: Mathematics,  Up: Writing R documentation files

2.7 Figures
===========

To include figures in help pages, use the `\figure' markup.  There are
three forms.

   The two commonly used simple forms are `\figure{FILENAME}' and
`\figure{FILENAME}{ALTERNATE TEXT}'.  This will include a copy of the
figure in either HTML or LaTeX output.  In text output, the alternate
text will be displayed instead.  (When the second argument is omitted,
the filename will be used.)  Both the filename and the alternate text
will be parsed verbatim, and should not include special characters that
are significant in HTML or LaTeX.

   The expert form is `\figure{FILENAME}{options: STRING}'.  (The word
`options:' must be typed exactly as shown and followed by at least one
space.)  In this form, the STRING is copied into the HTML `img' tag as
attributes following the `src' attribute, or into the second argument
of the `\Figure' macro in LaTeX, which by default is used as options to
an `\includegraphics' call.  As it is unlikely that any single string
would suffice for both display modes, the expert form would normally be
wrapped in conditionals.  It is up to the author to make sure that legal
HTML/LaTeX is used.  For example, to include a logo in both HTML (using
the simple form) and LaTeX (using the expert form), the following could
be used:

     \if{html}{\figure{logo.jpg}{Our logo}}
     \if{latex}{\figure{logo.jpg}{options: width=0.5in}}

   The files containing the figures should be stored in the directory
`man/figures'.  Files with extensions `.jpg', `.pdf', `.png' and `.svg'
from that directory will be copied to the `help/figures' directory at
install time. (Figures in PDF format will not display in most HTML
browsers, but might be the best choice in reference manuals.)  Specify
the filename relative to `man/figures' in the `\figure' directive.


File: R-exts.info,  Node: Insertions,  Next: Indices,  Prev: Figures,  Up: Writing R documentation files

2.8 Insertions
==============

Use `\R' for the R system itself.  Use `\dots' for the dots in function
argument lists `...', and `\ldots' for ellipsis dots in ordinary
text.(1)  These can be followed by `{}', and should be unless followed
by whitespace.

   After an unescaped `%', you can put your own comments regarding the
help text.  The rest of the line (but not the newline at the end) will
be completely disregarded.  Therefore, you can also use it to make part
of the "help" invisible.

   You can produce a backslash (`\') by escaping it by another
backslash.  (Note that `\cr' is used for generating line breaks.)

   The "comment" character `%' and unpaired braces(2) _almost always_
need to be escaped by `\', and `\\' can be used for backslash and needs
to be when there two or more adjacent backslashes).  In R-like code
quoted strings are handled slightly differently; see "Parsing Rd files"
(http://developer.r-project.org/parseRd.pdf) for details - in
particular braces should not be escaped in quoted strings.

   All of `% { } \' should be escaped in LaTeX-like text.

   Text which might need to be represented differently in different
encodings should be marked by `\enc', e.g.  `\enc{Jöreskog}{Joreskog}'
(with no whitespace between the braces) where the first argument will
be used where encodings are allowed and the second should be ASCII (and
is used for e.g.  the text conversion in locales that cannot represent
the encoded form).  (This is intended to be used for individual words,
not whole sentences or paragraphs.)

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

   (1) There is only a fine distinction between `\dots' and `\ldots'.
It is technically incorrect to use `\ldots' in code blocks and
`tools::checkRd' will warn about this--on the other hand the current
converters treat them the same way in code blocks, and elsewhere apart
from the small distinction between the two in LaTeX.

   (2) See the examples section in the file `Paren.Rd' for an example.


File: R-exts.info,  Node: Indices,  Next: Platform-specific sections,  Prev: Insertions,  Up: Writing R documentation files

2.9 Indices
===========

The `\alias' command (*note Documenting functions::) is used to specify
the "topics" documented, which should include _all_ R objects in a
package such as functions and variables, data sets, and S4 classes and
methods (*note Documenting S4 classes and methods::).  The on-line help
system searches the index data base consisting of all alias topics.

   In addition, it is possible to provide "concept index entries" using
`\concept', which can be used for `help.search()' lookups.  E.g., file
`cor.test.Rd' in the standard package *stats* contains

     \concept{Kendall correlation coefficient}
     \concept{Pearson correlation coefficient}
     \concept{Spearman correlation coefficient}

so that e.g. `??Spearman' will succeed in finding the help page for the
test for association between paired samples using Spearman's rho.

   (Note that `help.search()' only uses "sections" of documentation
objects with no additional markup.)

   If you want to cross reference such items from other help files _via_
`\link', you need to use `\alias' and not `\concept'.


File: R-exts.info,  Node: Platform-specific sections,  Next: Conditional text,  Prev: Indices,  Up: Writing R documentation files

2.10 Platform-specific documentation
====================================

Sometimes the documentation needs to differ by platform.  Currently two
OS-specific options are available, `unix' and `windows', and lines in
the help source file can be enclosed in

     #ifdef OS
        ...
     #endif

or

     #ifndef OS
        ...
     #endif

for OS-specific inclusion or exclusion.  Such blocks should not be
nested, and should be entirely within a block (that, is between the
opening and closing brace of a section or item), or at top-level contain
one or more complete sections.

   If the differences between platforms are extensive or the R objects
documented are only relevant to one platform, platform-specific `Rd'
files can be put in a `unix' or `windows' subdirectory.


File: R-exts.info,  Node: Conditional text,  Next: Dynamic pages,  Prev: Platform-specific sections,  Up: Writing R documentation files

2.11 Conditional text
=====================

Occasionally the best content for one output format is different from
the best content for another.  For this situation, the
`\if{FORMAT}{TEXT}' or `\ifelse{FORMAT}{TEXT}{ALTERNATE}' markup is
used.  Here FORMAT is a comma separated list of formats in which the
TEXT should be rendered.  The ALTERNATE will be rendered if the format
does not match.  Both TEXT and ALTERNATE may be any sequence of text
and markup.

   Currently the following formats are recognized:  `example', `html',
`latex' and `text'.  These select output for the corresponding targets.
(Note that `example' refers to extracted example code rather than the
displayed example in some other format.)  Also accepted are `TRUE'
(matching all formats) and `FALSE' (matching no formats).  These could
be the output of the `\Sexpr' macro (*note Dynamic pages::).

   The `\out{LITERAL}' macro would usually be used within the TEXT part
of `\if{FORMAT}{TEXT}'.  It causes the renderer to output the literal
text exactly, with no attempt to escape special characters.  For
example, use the following to output the markup necessary to display
the Greek letter in LaTeX or HTML, and the text string `alpha' in other
formats:
     \if{latex}{\out{\alpha}}\ifelse{html}{\out{&alpha;}}{alpha}


File: R-exts.info,  Node: Dynamic pages,  Next: User-defined macros,  Prev: Conditional text,  Up: Writing R documentation files

2.12 Dynamic pages
==================

Two macros supporting dynamically generated man pages are `\Sexpr' and
`\RdOpts'.  These are modelled after Sweave, and are intended to
contain executable R expressions in the `Rd' file.

   The main argument to `\Sexpr' must be valid R code that can be
executed. It may also take options in square brackets before the main
argument. Depending on the options, the code may be executed at package
build time, package install time, or man page rendering time.

   The options follow the same format as in Sweave, but different
options are supported.  Currently the allowed options and their
defaults are:

   * `eval=TRUE' Whether the R code should be evaluated.

   * `echo=FALSE' Whether the R code should be echoed.  If `TRUE', a
     display will be given in a preformatted block.  For example,
     `\Sexpr[echo=TRUE]{ x <- 1 }' will be displayed as
          > x <- 1

   * `keep.source=TRUE' Whether to keep the author's formatting when
     displaying the code, or throw it away and use a deparsed version.

   * `results=text' How should the results be displayed?  The
     possibilities are:

        - `results=text' Apply `as.character()' to the result of the
          code, and insert it as a text element.

        - `results=verbatim' Print the results of the code just as if
          it was executed at the console, and include the printed
          results verbatim.  (Invisible results will not print.)

        - `results=rd' The result is assumed to be a character vector
          containing markup to be passed to `parse_Rd()', with the
          result inserted in place.  This could be used to insert
          computed aliases, for instance.  `parse_Rd()' is called first
          with `fragment = FALSE' to allow a single Rd section macro to
          be inserted.  If that fails, it is called again with
          `fragment = TRUE', the older behavior.

        - `results=hide' Insert no output.

   * `strip.white=TRUE' Remove leading and trailing white space from
     each line of output if `strip.white=TRUE'.  With
     `strip.white=all', also remove blank lines.

   * `stage=install' Control when this macro is run.  Possible values
     are
        - `stage=build' The macro is run when building a source tarball.

        - `stage=install' The macro is run when installing from source.

        - `stage=render' The macro is run when displaying the help page.

     Conditionals such as `#ifdef' (*note Platform-specific sections::)
     are applied after the `build' macros but before the `install'
     macros.  In some situations (e.g. installing directly from a
     source directory without a tarball, or building a binary package)
     the above description is not literally accurate, but authors can
     rely on the sequence being `build', `#ifdef', `install', `render',
     with all stages executed.

     Code is only run once in each stage, so a `\Sexpr[results=rd]'
     macro can output an `\Sexpr' macro designed for a later stage, but
     not for the current one or any earlier stage.

   * `width, height, fig' These options are currently allowed but
     ignored.

   The `\RdOpts' macro is used to set new defaults for options to apply
to following uses of `\Sexpr'.

   For more details, see the online document "Parsing Rd files"
(http://developer.r-project.org/parseRd.pdf).


File: R-exts.info,  Node: User-defined macros,  Next: Encoding,  Prev: Dynamic pages,  Up: Writing R documentation files

2.13 User-defined macros
========================

The `\newcommand' and `\renewcommand' macros allow new macros to be
defined within an Rd file.  These are similar but not identical to the
same-named LaTeX macros.

   They each take two arguments which are parsed verbatim.  The first is
the name of the new macro including the initial backslash, and the
second is the macro definition.  As in LaTeX, `\newcommand' requires
that the new macro not have been previously defined, whereas
`\renewcommand' allows existing macros (including all built-in ones) to
be replaced.

   Also as in LaTeX, the new macro may be defined to take arguments,
and numeric placeholders such as `#1' are used in the macro definition.
However, unlike LaTeX, the number of arguments is determined
automatically from the highest placeholder number seen in the macro
definition.  For example, a macro definition containing `#1' and `#3'
(but no other placeholders) will define a three argument macro (whose
second argument will be ignored). As in LaTeX, at most 9 arguments may
be defined. If the `#' character is followed by a non-digit it will
have no special significance.  All arguments to user-defined macros
will be parsed as verbatim text, and simple text-substitution will be
used to replace the place-holders, after which the replacement text
will be parsed.

   For example, the `NEWS.Rd' file currently uses the definition
     \newcommand{\PR}{\Sexpr[results=rd]{tools:::Rd_expr_PR(#1)}}
   which defines `\PR' to be a single argument macro; then code like
     \PR{1234}
   will expand to
     \Sexpr[results=rd]{tools:::Rd_expr_PR(1234)}
   when parsed.


File: R-exts.info,  Node: Encoding,  Next: Processing documentation files,  Prev: User-defined macros,  Up: Writing R documentation files

2.14 Encoding
=============

Rd files are text files and so it is impossible to deduce the encoding
they are written in unless ASCII: files with 8-bit characters could be
UTF-8, Latin-1, Latin-9, KOI8-R, EUC-JP, _etc_.  So an `\encoding{}'
section must be used to specify the encoding if it is not ASCII.  (The
`\encoding{}' section must be on a line by itself, and in particular
one containing no non-ASCII characters.  The encoding declared in the
`DESCRIPTION' file will be used if none is declared in the file.)  The
`Rd' files are converted to UTF-8 before parsing and so the preferred
encoding for the files themselves is now UTF-8.

   Wherever possible, avoid non-ASCII chars in `Rd' files, and even
symbols such as `<', `>', `$', `^', `&', `|', `@', `~', and `*' outside
verbatim environments (since they may disappear in fonts designed to
render text).  (Function `showNonASCIIfile' in package *tools* can help
in finding non-ASCII bytes in the files.)

   For convenience, encoding names `latin1' and `latin2' are always
recognized: these and `UTF-8' are likely to work fairly widely.
However, this does not mean that all characters in UTF-8 will be
recognized, and the coverage of non-Latin characters(1) is fairly low.
Using LaTeX `inputenx' (see `?Rd2pdf' in R) will give greater coverage
of UTF-8.

   The `\enc' command (*note Insertions::) can be used to provide
transliterations which will be used in conversions that do not support
the declared encoding.

   The LaTeX conversion converts the file to UTF-8 from the declared
encoding, and includes a

     \inputencoding{utf8}

command, and this needs to be matched by a suitable invocation of the
`\usepackage{inputenc}' command.  The R utility `R CMD Rd2pdf' looks at
the converted code and includes the encodings used: it might for
example use

     \usepackage[utf8]{inputenc}

(Use of `utf8' as an encoding requires LaTeX dated 2003/12/01 or later.
Also, the use of Cyrillic characters in `UTF-8' appears to also need
`\usepackage[T2A]{fontenc}', and `R CMD Rd2pdf' includes this
conditionally on the file `t2aenc.def' being present and environment
variable `_R_CYRILLIC_TEX_' being set.)

   Note that this mechanism works best with Latin letters: the coverage
of UTF-8 in LaTeX is quite low.

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

   (1) R 2.9.0 added support for UTF-8 Cyrillic characters in LaTeX,
but on some OSes this will need Cyrillic support added to LaTeX, so
environment variable `_R_CYRILLIC_TEX_' may need to be set to a
non-empty value to enable this.


File: R-exts.info,  Node: Processing documentation files,  Next: Editing Rd files,  Prev: Encoding,  Up: Writing R documentation files

2.15 Processing documentation files
===================================

There are several commands to process Rd files from the system command
line.

   Using `R CMD Rdconv' one can convert R documentation format to other
formats, or extract the executable examples for run-time testing.  The
currently supported conversions are to plain text, HTML and LaTeX as
well as extraction of the examples.

   `R CMD Rd2pdf' generates PDF output from documentation in `Rd'
files, which can be specified either explicitly or by the path to a
directory with the sources of a package.  In the latter case, a
reference manual for all documented objects in the package is created,
including the information in the `DESCRIPTION' files.

   `R CMD Sweave' and `R CMD Stangle' process `Sweave' documentation
files (usually with extension `.Snw' or `.Rnw'): `R CMD Stangle' is use
to extract the R code fragments.

   The exact usage and a detailed list of available options for all of
these commands can be obtained by running `R CMD COMMAND --help', e.g.,
`R CMD Rdconv --help'.  All available commands can be listed using `R
--help' (or `Rcmd --help' under Windows).

   All of these work under Windows.  You may need to have installed the
the tools to build packages from source as described in the "R
Installation and Administration" manual, although typically all that is
needed is a LaTeX installation.


File: R-exts.info,  Node: Editing Rd files,  Prev: Processing documentation files,  Up: Writing R documentation files

2.16 Editing Rd files
=====================

It can be very helpful to prepare `.Rd' files using a editor which
knows about their syntax and will highlight commands, indent to show the
structure and detect mis-matched braces, and so on.

   The system most commonly used for this is some version of `Emacs'
(including `XEmacs') with the ESS package (`http://ess.r-project.org/':
it is often is installed with `Emacs' but may need to be loaded, or
even installed, separately).

   Another is the Eclipse IDE with the Stat-ET plugin
(`http://www.walware.de/goto/statet'), and (on Windows only) Tinn-R
(`http://sourceforge.net/projects/tinn-r/').

   People have also used LaTeX mode in a editor, as `.Rd' files are
rather similar to LaTeX files.

   Some R front-ends provide editing support for  `.Rd' files, for
example RStudio (`http://rstudio.org/').


File: R-exts.info,  Node: Tidying and profiling R code,  Next: Debugging,  Prev: Writing R documentation files,  Up: Top

3 Tidying and profiling R code
******************************

* Menu:

* Tidying R code::
* Profiling R code for speed::
* Profiling R code for memory use::
* Profiling compiled code::

   R code which is worth preserving in a package and perhaps making
available for others to use is worth documenting, tidying up and perhaps
optimizing. The last two of these activities are the subject of this
chapter.


File: R-exts.info,  Node: Tidying R code,  Next: Profiling R code for speed,  Prev: Tidying and profiling R code,  Up: Tidying and profiling R code

3.1 Tidying R code
==================

R treats function code loaded from packages and code entered by users
differently.  By default code entered by users has the source code
stored internally, and when the function is listed, the original source
is reproduced.  Loading code from a package (by default) discards the
source code, and the function listing is re-created from the parse tree
of the function.

   Normally keeping the source code is a good idea, and in particular it
avoids comments being removed from the source.  However, we can make
use of the ability to re-create a function listing from its parse tree
to produce a tidy version of the function, for example with consistent
indentation and spaces around operators.  If the original source does
not follow the standard format this tidied version can be much easier
to read.

   We can subvert the keeping of source in two ways.

  1. The option `keep.source' can be set to `FALSE' before the code is
     loaded into R.

  2. The stored source code can be removed by calling the
     `removeSource()' function, for example by

          myfun <- removeSource(myfun)


In each case if we then list the function we will get the standard
layout.

   Suppose we have a file of functions `myfuns.R' that we want to tidy
up.  Create a file `tidy.R' containing

     source("myfuns.R", keep.source = FALSE)
     dump(ls(all = TRUE), file = "new.myfuns.R")

and run R with this as the source file, for example by `R --vanilla <
tidy.R' or by pasting into an R session.  Then the file `new.myfuns.R'
will contain the functions in alphabetical order in the standard
layout.  Warning:  comments in your functions will be lost.

   The standard format provides a good starting point for further
tidying.  Although the deparsing cannot do so, we recommend the
consistent use of the preferred assignment operator `<-' (rather than
`=') for assignment.  Many package authors use a version of Emacs (on a
Unix-alike or Windows) to edit R code, using the ESS[S] mode of the ESS
Emacs package.  See *Note R coding standards: (R-ints)R coding
standards. for style options within the ESS[S] mode recommended for the
source code of R itself.


File: R-exts.info,  Node: Profiling R code for speed,  Next: Profiling R code for memory use,  Prev: Tidying R code,  Up: Tidying and profiling R code

3.2 Profiling R code for speed
==============================

It is possible to profile R code on Windows and most(1) Unix-alike
versions of R.

   The command `Rprof' is used to control profiling, and its help page
can be consulted for full details.  Profiling works by recording at
fixed intervals(2) (by default every 20 msecs) which line in which R
function is being used, and recording the results in a file (default
`Rprof.out' in the working directory).  Then the function
`summaryRprof' or the command-line utility `R CMD Rprof RPROF.OUT' can
be used to summarize the activity.

   As an example, consider the following code (from Venables & Ripley,
2002, pp. 225-6).

     library(MASS); library(boot)
     storm.fm <- nls(Time ~ b*Viscosity/(Wt - c), stormer,
                     start = c(b=30.401, c=2.2183))
     st <- cbind(stormer, fit=fitted(storm.fm))
     storm.bf <- function(rs, i) {
         st$Time <-  st$fit + rs[i]
         tmp <- nls(Time ~ (b * Viscosity)/(Wt - c), st,
                    start = coef(storm.fm))
         tmp$m$getAllPars()
     }
     rs <- scale(resid(storm.fm), scale = FALSE) # remove the mean
     Rprof("boot.out")
     storm.boot <- boot(rs, storm.bf, R = 4999) # slow enough to profile
     Rprof(NULL)

Having run this we can summarize the results by

     R CMD Rprof boot.out

     Each sample represents 0.02 seconds.
     Total run time: 22.52 seconds.

     Total seconds: time spent in function and callees.
     Self seconds: time spent in function alone.

        %       total       %        self
      total    seconds     self    seconds    name
      100.0     25.22       0.2      0.04     "boot"
       99.8     25.18       0.6      0.16     "statistic"
       96.3     24.30       4.0      1.02     "nls"
       33.9      8.56       2.2      0.56     "<Anonymous>"
       32.4      8.18       1.4      0.36     "eval"
       31.8      8.02       1.4      0.34     ".Call"
       28.6      7.22       0.0      0.00     "eval.parent"
       28.5      7.18       0.3      0.08     "model.frame"
       28.1      7.10       3.5      0.88     "model.frame.default"
       17.4      4.38       0.7      0.18     "sapply"
       15.0      3.78       3.2      0.80     "nlsModel"
       12.5      3.16       1.8      0.46     "lapply"
       12.3      3.10       2.7      0.68     "assign"
      ...

        %        self        %      total
       self    seconds     total   seconds    name
        5.7      1.44       7.5      1.88     "inherits"
        4.0      1.02      96.3     24.30     "nls"
        3.6      0.92       3.6      0.92     "$"
        3.5      0.88      28.1      7.10     "model.frame.default"
        3.2      0.80      15.0      3.78     "nlsModel"
        2.8      0.70       9.8      2.46     "qr.coef"
        2.7      0.68      12.3      3.10     "assign"
        2.5      0.64       2.5      0.64     ".Fortran"
        2.5      0.62       7.1      1.80     "qr.default"
        2.2      0.56      33.9      8.56     "<Anonymous>"
        2.1      0.54       5.9      1.48     "unlist"
        2.1      0.52       7.9      2.00     "FUN"
       ...

This often produces surprising results and can be used to identify
bottlenecks or pieces of R code that could benefit from being replaced
by compiled code.

   Two warnings: profiling does impose a small performance penalty, and
the output files can be very large if long runs are profiled at the
default sampling interval.

   Profiling short runs can sometimes give misleading results.  R from
time to time performs _garbage collection_ to reclaim unused memory,
and this takes an appreciable amount of time which profiling will
charge to whichever function happens to provoke it.  It may be useful
to compare profiling code immediately after a call to `gc()' with a
profiling run without a preceding call to `gc'.

   More detailed analysis of the output can be achieved by the tools in
the CRAN packages *proftools*
(http://CRAN.R-project.org/package=proftools) and *profr*
(http://CRAN.R-project.org/package=profr): in particular these allow
call graphs to be studied.

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

   (1) R has to be built to enable this, but the option
`--enable-R-profiling' is the default.

   (2) For Unix-alikes these are intervals of CPU time, and for Windows
of elapsed time.


File: R-exts.info,  Node: Profiling R code for memory use,  Next: Profiling compiled code,  Prev: Profiling R code for speed,  Up: Tidying and profiling R code

3.3 Profiling R code for memory use
===================================

Measuring memory use in R code is useful either when the code takes
more memory than is conveniently available or when memory allocation and
copying of objects is responsible for slow code. There are three ways to
profile memory use over time in R code. All three require R to have
been compiled with `--enable-memory-profiling', which is not the
default, but is currently used for the OS X and Windows binary
distributions. All can be misleading, for different reasons.

   In understanding the memory profiles it is useful to know a little
more about R's memory allocation. Looking at the results of `gc()'
shows a division of memory into `Vcells' used to store the contents of
vectors and `Ncells' used to store everything else, including all the
administrative overhead for vectors such as type and length
information.  In fact the vector contents are divided into two pools.
Memory for small vectors (by default 128 bytes or less) is obtained in
large chunks and then parcelled out by R; memory for larger vectors is
obtained directly from the operating system.

   Some memory allocation is obvious in interpreted code, for example,

     y <- x + 1

allocates memory for a new vector `y'. Other memory allocation is less
obvious and occurs because `R' is forced to make good on its promise of
`call-by-value' argument passing.  When an argument is passed to a
function it is not immediately copied. Copying occurs (if necessary)
only when the argument is modified.  This can lead to surprising memory
use. For example, in the `survey' package we have

     print.svycoxph <- function (x, ...)
     {
         print(x$survey.design, varnames = FALSE, design.summaries = FALSE,
             ...)
         x$call <- x$printcall
         NextMethod()
     }

It may not be obvious that the assignment to `x$call' will cause the
entire object `x' to be copied.  This copying to preserve the
call-by-value illusion is usually done by the internal C function
`duplicate'.

   The main reason that memory-use profiling is difficult is garbage
collection. Memory is allocated at well-defined times in an R program,
but is freed whenever the garbage collector happens to run.

* Menu:

* Memory statistics from Rprof::
* Tracking memory allocations::
* Tracing copies of an object::


File: R-exts.info,  Node: Memory statistics from Rprof,  Next: Tracking memory allocations,  Prev: Profiling R code for memory use,  Up: Profiling R code for memory use

3.3.1 Memory statistics from `Rprof'
------------------------------------

The sampling profiler `Rprof' described in the previous section can be
given the option `memory.profiling=TRUE'. It then writes out the total
R memory allocation in small vectors, large vectors, and cons cells or
nodes at each sampling interval. It also writes out the number of calls
to the internal function `duplicate', which is called to copy R
objects. `summaryRprof' provides summaries of this information.  The
main reason that this can be misleading is that the memory use is
attributed to the function running at the end of the sampling interval.
A second reason is that garbage collection can make the amount of
memory in use decrease, so a function appears to use little memory.
Running under `gctorture' helps with both problems: it slows down the
code to effectively increase the sampling frequency and it makes each
garbage collection release a smaller amount of memory.  Changing the
memory limits with `mem.limits()' may also be useful, to see how the
code would run under different memory conditions.


File: R-exts.info,  Node: Tracking memory allocations,  Next: Tracing copies of an object,  Prev: Memory statistics from Rprof,  Up: Profiling R code for memory use

3.3.2 Tracking memory allocations
---------------------------------

The second method of memory profiling uses a memory-allocation
profiler, `Rprofmem()', which writes out a stack trace to an output
file every time a large vector is allocated (with a user-specified
threshold for `large') or a new page of memory is allocated for the R
heap. Summary functions for this output are still being designed.

   Running the example from the previous section with

     > Rprofmem("boot.memprof",threshold=1000)
     > storm.boot <- boot(rs, storm.bf, R = 4999)
     > Rprofmem(NULL)

shows that apart from some initial and final work in `boot' there are
no vector allocations over 1000 bytes.


File: R-exts.info,  Node: Tracing copies of an object,  Prev: Tracking memory allocations,  Up: Profiling R code for memory use

3.3.3 Tracing copies of an object
---------------------------------

The third method of memory profiling involves tracing copies made of a
specific (presumably large) R object. Calling `tracemem' on an object
marks it so that a message is printed to standard output when the
object is copied _via_ `duplicate' or coercion to another type, or when
a new object of the same size is created in arithmetic operations. The
main reason that this can be misleading is that copying of subsets or
components of an object is not tracked. It may be helpful to use
`tracemem' on these components.

   In the example above we can run `tracemem' on the data frame `st'

     > tracemem(st)
     [1] "<0x9abd5e0>"
     > storm.boot <- boot(rs, storm.bf, R = 4)
     memtrace[0x9abd5e0->0x92a6d08]: statistic boot
     memtrace[0x92a6d08->0x92a6d80]: $<-.data.frame $<- statistic boot
     memtrace[0x92a6d80->0x92a6df8]: $<-.data.frame $<- statistic boot
     memtrace[0x9abd5e0->0x9271318]: statistic boot
     memtrace[0x9271318->0x9271390]: $<-.data.frame $<- statistic boot
     memtrace[0x9271390->0x9271408]: $<-.data.frame $<- statistic boot
     memtrace[0x9abd5e0->0x914f558]: statistic boot
     memtrace[0x914f558->0x914f5f8]: $<-.data.frame $<- statistic boot
     memtrace[0x914f5f8->0x914f670]: $<-.data.frame $<- statistic boot
     memtrace[0x9abd5e0->0x972cbf0]: statistic boot
     memtrace[0x972cbf0->0x972cc68]: $<-.data.frame $<- statistic boot
     memtrace[0x972cc68->0x972cd08]: $<-.data.frame $<- statistic boot
     memtrace[0x9abd5e0->0x98ead98]: statistic boot
     memtrace[0x98ead98->0x98eae10]: $<-.data.frame $<- statistic boot
     memtrace[0x98eae10->0x98eae88]: $<-.data.frame $<- statistic boot

The object is duplicated fifteen times, three times for each of the
`R+1' calls to `storm.bf'.  This is surprising, since none of the
duplications happen inside `nls'. Stepping through `storm.bf' in the
debugger shows that all three happen in the line

     st$Time <- st$fit + rs[i]

   Data frames are slower than matrices and this is an example of why.
Using `tracemem(st$Viscosity)' does not reveal any additional copying.


File: R-exts.info,  Node: Profiling compiled code,  Prev: Profiling R code for memory use,  Up: Tidying and profiling R code

3.4 Profiling compiled code
===========================

Profiling compiled code is highly system-specific, but this section
contains some hints gleaned from various R users.  Some methods need to
be different for a compiled executable and for dynamic/shared
libraries/objects as used by R packages.  We know of no good way to
profile DLLs on Windows.

* Menu:

* Linux::
* Solaris::
* OS X::


File: R-exts.info,  Node: Linux,  Next: Solaris,  Prev: Profiling compiled code,  Up: Profiling compiled code

3.4.1 Linux
-----------

Options include using `sprof' for a shared object, and `oprofile' (see
`http://oprofile.sourceforge.net/') and `perf' (see
`https://perf.wiki.kernel.org/index.php/Tutorial') for any executable
or shared object.

3.4.1.1 sprof
.............

You can select shared objects to be profiled with `sprof' by setting
the environment variable `LD_PROFILE'.  For example

     % setenv LD_PROFILE /path/to/R_HOME/library/stats/libs/stats.so
     R
     ... run the boot example
     % sprof /path/to/R_HOME/library/stats/libs/stats.so \
       /var/tmp/path/to/R_HOME/library/stats/libs/stats.so.profile

     Flat profile:

     Each sample counts as 0.01 seconds.
       %   cumulative   self              self     total
      time   seconds   seconds    calls  us/call  us/call  name
      76.19      0.32     0.32        0     0.00           numeric_deriv
      16.67      0.39     0.07        0     0.00           nls_iter
       7.14      0.42     0.03        0     0.00           getListElement

     rm /path/to/R_HOME/library/stats/libs/stats.so.profile
     ... to clean up ...

   It is possible that root access is needed to create the directories
used for the profile data.

3.4.1.2 oprofile
................

`oprofile' works by running a daemon which collects information.  The
daemon must be started as root, e.g.

     % su
     % opcontrol --no-vmlinux
     % (optional, some platforms) opcontrol --callgraph=5
     % opcontrol --start
     % exit

   Then as a user

     % R
     ... run the boot example
     % opcontrol --dump
     % opreport -l /path/to/R_HOME/library/stats/libs/stats.so
     ...
     samples  %        symbol name
     1623     75.5939  anonymous symbol from section .plt
     349      16.2552  numeric_deriv
     113       5.2632  nls_iter
     62        2.8878  getListElement
     % opreport -l /path/to/R_HOME/bin/exec/R
     ...
     samples  %        symbol name
     76052    11.9912  Rf_eval
     54670     8.6198  Rf_findVarInFrame3
     37814     5.9622  Rf_allocVector
     31489     4.9649  Rf_duplicate
     28221     4.4496  Rf_protect
     26485     4.1759  Rf_cons
     23650     3.7289  Rf_matchArgs
     21088     3.3250  Rf_findFun
     19995     3.1526  findVarLocInFrame
     14871     2.3447  Rf_evalList
     13794     2.1749  R_Newhashpjw
     13522     2.1320  R_gc_internal
     ...

   Shutting down the profiler and clearing the records needs to be done
as root.  You can use `opannotate' to annotate the source code with the
times spent in each section, if the appropriate source code was
compiled with debugging support, and `opreport -c' to generate a
callgraph (if collection was enabled and the platform supports this).


File: R-exts.info,  Node: Solaris,  Next: OS X,  Prev: Linux,  Up: Profiling compiled code

3.4.2 Solaris
-------------

On 64-bit (only) Solaris, the standard profiling tool `gprof' collects
information from shared objects compiled with `-pg'.


File: R-exts.info,  Node: OS X,  Prev: Solaris,  Up: Profiling compiled code

3.4.3 OS X
----------

Developers have recommended `sample' (or `Sampler.app', which is a GUI
version), `Shark' (in version of `Xcode' up to those for Snow Leopard),
and `Instruments' (part of `Xcode', see
`https://developer.apple.com/library/mac/#documentation/DeveloperTools/Conceptual/InstrumentsUserGuide/Introduction/Introduction.html').


File: R-exts.info,  Node: Debugging,  Next: System and foreign language interfaces,  Prev: Tidying and profiling R code,  Up: Top

4 Debugging
***********

This chapter covers the debugging of R extensions, starting with the
ways to get useful error information and moving on to how to deal with
errors that crash R.  For those who prefer other styles there are
contributed packages such as *debug*
(http://CRAN.R-project.org/package=debug) on CRAN (described in an
article in R-News 3/3
(http://CRAN.R-project.org/doc/Rnews/Rnews_2003-3.pdf)).  (There are
notes from 2002 provided by Roger Peng at
`http://www.biostat.jhsph.edu/~rpeng/docs/R-debug-tools.pdf' which
provide complementary examples to those given here.)

* Menu:

* Browsing::
* Debugging R code::
* Using gctorture and memory access::
* Debugging compiled code::


File: R-exts.info,  Node: Browsing,  Next: Debugging R code,  Prev: Debugging,  Up: Debugging

4.1 Browsing
============

Most of the R-level debugging facilities are based around the built-in
browser.  This can be used directly by inserting a call to `browser()'
into the code of a function (for example, using `fix(my_function)' ).
When code execution reaches that point in the function, control returns
to the R console with a special prompt.  For example

     > fix(summary.data.frame) ## insert browser() call after for() loop
     > summary(women)
     Called from: summary.data.frame(women)
     Browse[1]> ls()
      [1] "digits" "i"      "lbs"    "lw"     "maxsum" "nm"     "nr"     "nv"
      [9] "object" "sms"    "z"
     Browse[1]> maxsum
     [1] 7
     Browse[1]>
          height         weight
      Min.   :58.0   Min.   :115.0
      1st Qu.:61.5   1st Qu.:124.5
      Median :65.0   Median :135.0
      Mean   :65.0   Mean   :136.7
      3rd Qu.:68.5   3rd Qu.:148.0
      Max.   :72.0   Max.   :164.0
     > rm(summary.data.frame)

At the browser prompt one can enter any R expression, so for example
`ls()' lists the objects in the current frame, and entering the name of
an object will(1) print it.  The following commands are also accepted

   * `n'

     Enter `step-through' mode.  In this mode, hitting return executes
     the next line of code (more precisely one line and any
     continuation lines).  Typing `c' will continue to the end of the
     current context, e.g.  to the end of the current loop or function.

   * `c'

     In normal mode, this quits the browser and continues execution,
     and just return works in the same way.  `cont' is a synonym.

   * `where'

     This prints the call stack.  For example

          > summary(women)
          Called from: summary.data.frame(women)
          Browse[1]> where
          where 1: summary.data.frame(women)
          where 2: summary(women)

          Browse[1]>

   * `Q'

     Quit both the browser and the current expression, and return to the
     top-level prompt.

   Errors in code executed at the browser prompt will normally return
control to the browser prompt.  Objects can be altered by assignment,
and will keep their changed values when the browser is exited.  If
really necessary, objects can be assigned to the workspace from the
browser prompt (by using `<<-' if the name is not already in scope).

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

   (1) With the exceptions of the commands listed below: an object of
such a name can be printed _via_ an explicit call to `print'.


File: R-exts.info,  Node: Debugging R code,  Next: Using gctorture and memory access,  Prev: Browsing,  Up: Debugging

4.2 Debugging R code
====================

Suppose your R program gives an error message.  The first thing to find
out is what R was doing at the time of the error, and the most useful
tool is `traceback()'.  We suggest that this is run whenever the cause
of the error is not immediately obvious.  Daily, errors are reported to
the R mailing lists as being in some package when `traceback()' would
show that the error was being reported by some other package or base R.
Here is an example from the regression suite.

     > success <- c(13,12,11,14,14,11,13,11,12)
     > failure <- c(0,0,0,0,0,0,0,2,2)
     > resp <- cbind(success, failure)
     > predictor <- c(0, 5^(0:7))
     > glm(resp ~ 0+predictor, family = binomial(link="log"))
     Error: no valid set of coefficients has been found: please supply starting values
     > traceback()
     3: stop("no valid set of coefficients has been found: please supply
              starting values", call. = FALSE)
     2: glm.fit(x = X, y = Y, weights = weights, start = start, etastart = etastart,
            mustart = mustart, offset = offset, family = family, control = control,
            intercept = attr(mt, "intercept") > 0)
     1: glm(resp ~ 0 + predictor, family = binomial(link ="log"))

The calls to the active frames are given in reverse order (starting with
the innermost).  So we see the error message comes from an explicit
check in `glm.fit'.  (`traceback()' shows you all the lines of the
function calls, which can be limited by setting `option'
`"deparse.max.lines"'.)

   Sometimes the traceback will indicate that the error was detected
inside compiled code, for example (from `?nls')

     Error in nls(y ~ a + b * x, start = list(a = 0.12345, b = 0.54321), trace = TRUE) :
             step factor 0.000488281 reduced below 'minFactor' of 0.000976563
     >  traceback()
     2: .Call(R_nls_iter, m, ctrl, trace)
     1: nls(y ~ a + b * x, start = list(a = 0.12345, b = 0.54321), trace = TRUE)

This will be the case if the innermost call is to `.C', `.Fortran',
`.Call', `.External' or `.Internal', but as it is also possible for
such code to evaluate R expressions, this need not be the innermost
call, as in

     > traceback()
     9: gm(a, b, x)
     8: .Call(R_numeric_deriv, expr, theta, rho, dir)
     7: numericDeriv(form[[3]], names(ind), env)
     6: getRHS()
     5: assign("rhs", getRHS(), envir = thisEnv)
     4: assign("resid", .swts * (lhs - assign("rhs", getRHS(), envir = thisEnv)),
            envir = thisEnv)
     3: function (newPars)
        {
            setPars(newPars)
            assign("resid", .swts * (lhs - assign("rhs", getRHS(), envir = thisEnv)),
                envir = thisEnv)
            assign("dev", sum(resid^2), envir = thisEnv)
            assign("QR", qr(.swts * attr(rhs, "gradient")), envir = thisEnv)
            return(QR$rank < min(dim(QR$qr)))
        }(c(-0.00760232418963883, 1.00119632515036))
     2: .Call(R_nls_iter, m, ctrl, trace)
     1: nls(yeps ~ gm(a, b, x), start = list(a = 0.12345, b = 0.54321))

   Occasionally `traceback()' does not help, and this can be the case
if S4 method dispatch is involved.  Consider the following example

     > xyd <- new("xyloc", x=runif(20), y=runif(20))
     Error in as.environment(pkg) : no item called "package:S4nswv"
     on the search list
     Error in initialize(value, ...) : S language method selection got
     an error when called from internal dispatch for function 'initialize'
     > traceback()
     2: initialize(value, ...)
     1: new("xyloc", x = runif(20), y = runif(20))

which does not help much, as there is no call to `as.environment' in
`initialize' (and the note "called from internal dispatch" tells us
so).  In this case we searched the R sources for the quoted call, which
occurred in only one place, `methods:::.asEnvironmentPackage'.  So now
we knew where the error was occurring.  (This was an unusually opaque
example.)

   The error message

     evaluation nested too deeply: infinite recursion / options(expressions=)?

can be hard to handle with the default value (5000).  Unless you know
that there actually is deep recursion going on, it can help to set
something like

     options(expressions=500)

and re-run the example showing the error.

   Sometimes there is warning that clearly is the precursor to some
later error, but it is not obvious where it is coming from.  Setting
`options(warn = 2)' (which turns warnings into errors) can help here.

   Once we have located the error, we have some choices.  One way to
proceed is to find out more about what was happening at the time of the
crash by looking a _post-mortem_ dump.  To do so, set `options(error=dump.frames)'
and run the code again.  Then invoke `debugger()' and explore the dump.
Continuing our example:

     > options(error = dump.frames)
     > glm(resp ~ 0 + predictor, family = binomial(link ="log"))
     Error: no valid set of coefficients has been found: please supply starting values

which is the same as before, but an object called `last.dump' has
appeared in the workspace.  (Such objects can be large, so remove it
when it is no longer needed.)  We can examine this at a later time by
calling the function `debugger'.  

     > debugger()
     Message:  Error: no valid set of coefficients has been found: please supply starting values
     Available environments had calls:
     1: glm(resp ~ 0 + predictor, family = binomial(link = "log"))
     2: glm.fit(x = X, y = Y, weights = weights, start = start, etastart = etastart, mus
     3: stop("no valid set of coefficients has been found: please supply starting values
     Enter an environment number, or 0 to exit  Selection:

which gives the same sequence of calls as `traceback', but in
outer-first order and with only the first line of the call, truncated to
the current width.  However, we can now examine in more detail what was
happening at the time of the error.  Selecting an environment opens the
browser in that frame.  So we select the function call which spawned the
error message, and explore some of the variables (and execute two
function calls).

     Enter an environment number, or 0 to exit  Selection: 2
     Browsing in the environment with call:
        glm.fit(x = X, y = Y, weights = weights, start = start, etas
     Called from: debugger.look(ind)
     Browse[1]> ls()
      [1] "aic"        "boundary"   "coefold"    "control"    "conv"
      [6] "dev"        "dev.resids" "devold"     "EMPTY"      "eta"
     [11] "etastart"   "family"     "fit"        "good"       "intercept"
     [16] "iter"       "linkinv"    "mu"         "mu.eta"     "mu.eta.val"
     [21] "mustart"    "n"          "ngoodobs"   "nobs"       "nvars"
     [26] "offset"     "start"      "valideta"   "validmu"    "variance"
     [31] "varmu"      "w"          "weights"    "x"          "xnames"
     [36] "y"          "ynames"     "z"
     Browse[1]> eta
                 1             2             3             4             5
      0.000000e+00 -2.235357e-06 -1.117679e-05 -5.588393e-05 -2.794197e-04
                 6             7             8             9
     -1.397098e-03 -6.985492e-03 -3.492746e-02 -1.746373e-01
     Browse[1]> valideta(eta)
     [1] TRUE
     Browse[1]> mu
             1         2         3         4         5         6         7         8
     1.0000000 0.9999978 0.9999888 0.9999441 0.9997206 0.9986039 0.9930389 0.9656755
             9
     0.8397616
     Browse[1]> validmu(mu)
     [1] FALSE
     Browse[1]> c
     Available environments had calls:
     1: glm(resp ~ 0 + predictor, family = binomial(link = "log"))
     2: glm.fit(x = X, y = Y, weights = weights, start = start, etastart = etastart
     3: stop("no valid set of coefficients has been found: please supply starting v

     Enter an environment number, or 0 to exit  Selection: 0
     > rm(last.dump)

   Because `last.dump' can be looked at later or even in another R
session, post-mortem debugging is possible even for batch usage of R.
We do need to arrange for the dump to be saved: this can be done either
using the command-line flag `--save' to save the workspace at the end
of the run, or _via_ a setting such as

     > options(error = quote({dump.frames(to.file=TRUE); q()}))

See the help on `dump.frames' for further options and a worked example.

   An alternative error action is to use the function `recover()':

     > options(error = recover)
     > glm(resp ~ 0 + predictor, family = binomial(link = "log"))
     Error: no valid set of coefficients has been found: please supply starting values

     Enter a frame number, or 0 to exit

     1: glm(resp ~ 0 + predictor, family = binomial(link = "log"))
     2: glm.fit(x = X, y = Y, weights = weights, start = start, etastart = etastart

     Selection:

which is very similar to `dump.frames'.  However, we can examine the
state of the program directly, without dumping and re-loading the dump.
As its help page says, `recover' can be routinely used as the error
action in place of `dump.calls' and `dump.frames', since it behaves
like `dump.frames' in non-interactive use.

   Post-mortem debugging is good for finding out exactly what went
wrong, but not necessarily why.  An alternative approach is to take a
closer look at what was happening just before the error, and a good way
to do that is to use `debug'.  This inserts a call to the browser at
the beginning of the function, starting in step-through mode.  So in
our example we could use

     > debug(glm.fit)
     > glm(resp ~ 0 + predictor, family = binomial(link ="log"))
     debugging in: glm.fit(x = X, y = Y, weights = weights, start = start, etastart = etastart,
         mustart = mustart, offset = offset, family = family, control = control,
         intercept = attr(mt, "intercept") > 0)
     debug: {
     ## lists the whole function
     Browse[1]>
     debug: x <- as.matrix(x)
     ...
     Browse[1]> start
     [1] -2.235357e-06
     debug: eta <- drop(x %*% start)
     Browse[1]> eta
                 1             2             3             4             5
      0.000000e+00 -2.235357e-06 -1.117679e-05 -5.588393e-05 -2.794197e-04
                 6             7             8             9
     -1.397098e-03 -6.985492e-03 -3.492746e-02 -1.746373e-01
     Browse[1]>
     debug: mu <- linkinv(eta <- eta + offset)
     Browse[1]> mu
             1         2         3         4         5         6         7         8
     1.0000000 0.9999978 0.9999888 0.9999441 0.9997206 0.9986039 0.9930389 0.9656755
             9
     0.8397616

(The prompt `Browse[1]>' indicates that this is the first level of
browsing: it is possible to step into another function that is itself
being debugged or contains a call to `browser()'.)

   `debug' can be used for hidden functions and S3 methods by e.g.
`debug(stats:::predict.Arima)'.  (It cannot be used for S4 methods, but
an alternative is given on the help page for `debug'.)  Sometimes you
want to debug a function defined inside another function, e.g. the
function `arimafn' defined inside `arima'.  To do so, set `debug' on
the outer function (here `arima') and step through it until the inner
function has been defined.  Then call `debug' on the inner function
(and use `c' to get out of step-through mode in the outer function).

   To remove debugging of a function, call `undebug' with the argument
previously given to `debug'; debugging otherwise lasts for the rest of
the R session (or until the function is edited or otherwise replaced).

   `trace' can be used to temporarily insert debugging code into a
function, for example to insert a call to `browser()' just before the
point of the error.  To return to our running example

     ## first get a numbered listing of the expressions of the function
     > page(as.list(body(glm.fit)), method="print")
     > trace(glm.fit, browser, at=22)
     Tracing function "glm.fit" in package "stats"
     [1] "glm.fit"
     > glm(resp ~ 0 + predictor, family = binomial(link ="log"))
     Tracing glm.fit(x = X, y = Y, weights = weights, start = start,
        etastart = etastart,  .... step 22
     Called from: eval(expr, envir, enclos)
     Browse[1]> n
     ## and single-step from here.
     > untrace(glm.fit)
   For your own functions, it may be as easy to use `fix' to insert
temporary code, but `trace' can help with functions in a namespace (as
can `fixInNamespace').  Alternatively, use `trace(,edit=TRUE)' to
insert code visually.


File: R-exts.info,  Node: Using gctorture and memory access,  Next: Debugging compiled code,  Prev: Debugging R code,  Up: Debugging

4.3 Using gctorture and memory access
=====================================

Errors in memory allocation and reading/writing outside arrays are very
common causes of crashes (e.g., segfaults) on some machines.  Often the
crash appears long after the invalid memory access: in particular
damage to the structures which R itself has allocated may only become
apparent at the next garbage collection (or even at later garbage
collections after objects have been deleted).

   Note that memory access errors may be seen with LAPACK, BLAS and
Java-using packages: some at least of these seem to be intentional.

* Menu:

* Using gctorture::
* Using valgrind::
* Using AddressSanitizer::
* Fortran array bounds checking::


File: R-exts.info,  Node: Using gctorture,  Next: Using valgrind,  Prev: Using gctorture and memory access,  Up: Using gctorture and memory access

4.3.1 Using gctorture
---------------------

We can help to detect memory problems earlier by running garbage
collection as often as possible.  This is achieved by
`gctorture(TRUE)', which as described on its help page

     Provokes garbage collection on (nearly) every memory allocation.
     Intended to ferret out memory protection bugs.  Also makes R run
     _very_ slowly, unfortunately.

The reference to `memory protection' is to missing C-level calls to
`PROTECT'/`UNPROTECT' (*note Garbage Collection::) which if missing
allow R objects to be garbage-collected when they are still in use.
But it can also help with other memory-related errors.

   Normally running under `gctorture(TRUE)' will just produce a crash
earlier in the R program, hopefully close to the actual cause. See the
next section for how to decipher such crashes.

   It is possible to run all the examples, tests and vignettes covered
by `R CMD check' under `gctorture(TRUE)' by using the option
`--use-gct'.

   The function `gctorture2' provides more refined control over the GC
torture process.  Its arguments `step', `wait' and `inhibit_release'
are documented on its help page.  Environment variables can also be
used to turn on GC torture: `R_GCTORTURE' corresponds to the `step'
argument to `gctorture', `R_GCTORTURE_WAIT' to `wait', and
`R_GCTORTURE_INHIBIT_RELEASE' to `inhibit_release'.

   If R is configured with `--enable-strict-barrier' then a variety of
tests for the integrity of the write barrier are enabled.  In addition
tests to help detect protect issues are enabled as well:

   * All GCs are full GCs.

   * New nodes in small node pages are marked as `NEWSXP' on creation.

   * After a GC all free nodes that are not of type `NEWSXP' are marked
     as type `FREESXP' and their previous type is recorded.

   * Most calls to accessor functions check their `SEXP' inputs and
     `SEXP' outputs and signal an error if a `FREESXP' is found.  The
     address of the node and the old type are included in the error
     message.


   Used with a debugger and with `gctorture' or `gctorture2' this
mechanism can be helpful in isolating memory protect problems.


File: R-exts.info,  Node: Using valgrind,  Next: Using AddressSanitizer,  Prev: Using gctorture,  Up: Using gctorture and memory access

4.3.2 Using valgrind
--------------------

If you have access to Linux on an `ix86', `x86_64', `ppc32', `ppc64' or
`s390x' platform, or (some versions of) OS X you can use `valgrind'
(`http://www.valgrind.org/', pronounced to rhyme with `tinned') to
check for possible problems.  To run some examples under `valgrind' use
something like

     R -d valgrind --vanilla < mypkg-Ex.R
     R -d "valgrind --tool=memcheck --leak-check=full" --vanilla < mypkg-Ex.R

where `mypkg-Ex.R' is a set of examples, e.g. the file created in
`mypkg.Rcheck' by `R CMD check'.  Occasionally this reports memory
reads of `uninitialised values' that are the result of compiler
optimization, so can be worth checking under an unoptimized compile: for
maximal information use a build with debugging symbols.  We know there
will be some small memory leaks from `readline' and R itself -- these
are memory areas that are in use right up to the end of the R session.
Expect this to run around 20x slower than without `valgrind', and in
some cases even slower than that.  Several versions of `valgrind' were
not happy with some optimized BLASes that use CPU-specific instructions
so you may need to build a version of R specifically to use with
`valgrind'.

   On Mac OS 10.6 and later the valgrind session is liable to hang when
R terminates with `valgrind' prior to 3.8.1.

   On platforms supported by `valgrind' you can build a version of R
with extra instrumentation to help `valgrind' detect errors in the use
of memory allocated from the R heap.  The configure option is
`--with-valgrind-instrumentation=LEVEL', where LEVEL is 0, 1, or 2.
Level 0 is the default and does not add any anything.  Level 1 will
detect use of uninitialised memory and has little impact on speed.
Level 2 will detect many other memory-use bugs but makes R much slower
when running under `valgrind'.  Using this in conjunction with
`gctorture' can be even more effective (and even slower).

   An example of `valgrind' output is
     ==12539== Invalid read of size 4
     ==12539==    at 0x1CDF6CBE: csc_compTr (Mutils.c:273)
     ==12539==    by 0x1CE07E1E: tsc_transpose (dtCMatrix.c:25)
     ==12539==    by 0x80A67A7: do_dotcall (dotcode.c:858)
     ==12539==    by 0x80CACE2: Rf_eval (eval.c:400)
     ==12539==    by 0x80CB5AF: R_execClosure (eval.c:658)
     ==12539==    by 0x80CB98E: R_execMethod (eval.c:760)
     ==12539==    by 0x1B93DEFA: R_standardGeneric (methods_list_dispatch.c:624)
     ==12539==    by 0x810262E: do_standardGeneric (objects.c:1012)
     ==12539==    by 0x80CAD23: Rf_eval (eval.c:403)
     ==12539==    by 0x80CB2F0: Rf_applyClosure (eval.c:573)
     ==12539==    by 0x80CADCC: Rf_eval (eval.c:414)
     ==12539==    by 0x80CAA03: Rf_eval (eval.c:362)
     ==12539==  Address 0x1C0D2EA8 is 280 bytes inside a block of size 1996 alloc'd
     ==12539==    at 0x1B9008D1: malloc (vg_replace_malloc.c:149)
     ==12539==    by 0x80F1B34: GetNewPage (memory.c:610)
     ==12539==    by 0x80F7515: Rf_allocVector (memory.c:1915)
     ...
   This example is from an instrumented version of R, while tracking
down a bug in the *Matrix* (http://CRAN.R-project.org/package=Matrix)
package in January, 2006.  The first line indicates that R has tried to
read 4 bytes from a memory address that it does not have access to.
This is followed by a C stack trace showing where the error occurred.
Next is a description of the memory that was accessed. It is inside a
block allocated by `malloc', called from `GetNewPage', that is, in the
internal R heap.  Since this memory all belongs to R, `valgrind' would
not (and did not) detect the problem in an uninstrumented build of R.
In this example the stack trace was enough to isolate and fix the bug,
which was in `tsc_transpose', and in this example running under
`gctorture()' did not provide any additional information.  When the
stack trace is not sufficiently informative the option
`--db-attach=yes' to `valgrind' may be helpful.  This starts a
post-mortem debugger (by default `gdb') so that variables in the C code
can be inspected (*note Inspecting R objects::).

   `valgrind' is good at spotting the use of uninitialized values: use
option `--track-origins=yes' to show where these originated from.  What
it cannot detect is the misuse of arrays allocated on the stack: this
includes C automatic variables and most Fortran arrays.

   It is possible to run all the examples, tests and vignettes covered
by `R CMD check' under `valgrind' by using the option `--use-valgrind'.
If you do this you will need to select the `valgrind' options some
other way, for example by having a `~/.valgrindrc' file containing

     --leak-check=full
     --track-origins=yes

or setting the environment variable `VALGRIND_OPTS'.

   On OS X you may need to ensure that debugging symbols are made
available (so `valgrind' reports line numbers in files).  This can
usually be done with the `valgrind' option `--dysmutil=yes' to ask for
the symbols to be dumped when the `.so' file is loaded.  This will not
work where packages are installed into a system area (such as the
`R.framework') and can be slow.  Installing packages with `R CMD
INSTALL --dsym' installs the dumped symbols.  (This can also be done by
setting environment variable `PKG_MAKE_DSYM' to a non-empty value
before the `INSTALL'.)


File: R-exts.info,  Node: Using AddressSanitizer,  Next: Fortran array bounds checking,  Prev: Using valgrind,  Up: Using gctorture and memory access

4.3.3 Using AddressSanitizer
----------------------------

`AddressSanitizer' (`ASan') is a tool with similar aims to the memory
checker in `valgrind'.  It is available with suitable builds of `gcc'
4.8.x and `clang' 3.1 and later(1), on common Linux platforms and
64-bit Mac OS X.  See `https://code.google.com/p/address-sanitizer/'.

   It requires code to have been compiled _and linked_ with
`-fsanitize=address' (`gcc' and recent versions of `clang') or
`-faddress-sanitizer' (`clang' 3.1), and using
`-fno-omit-frame-pointer' will give more legible reports.  It has a
runtime penalty of 2-3x, extended compilation times and uses
substantially more memory, often 1-2GB, at run time.  In contrast to
`valgrind', it can detect misuse of stack variables but not the use of
uninitialized memory (although that may come with `-fsanitize=memory'
in future versions of `clang').

   Current versions do not return symbolic addresses for the location of
the error without some help.  One possibility is to use an external
symbolizer such as `asan_symbolize.py' from `http://llvm.org': it makes
use of `llvm-symbolizer' if available.  For example, the check output
can be piped through `asan_symbolize.py' and then (for compiled C++
code) `c++filt'.

   The simplest way to make use of this is to build a version of R with
something like

     CC="gcc-4.8.0 -std=gnu99 -fsanitize=address"
     CFLAGS="-fno-omit-frame-pointer -O2 -Wall -pedantic -mtune=native"

which will ensure that the `libasan' run-time library is compiled into
the R executable.  However, building R with e.g.

     MAIN_LD="gcc-4.8.0 -std=gnu99 -fsanitize=address"

allows this check to be enabled on a per-package basis by using a
`~/.R/Makevars' file like
     CC = gcc-4.8.0 -std=gnu99 -fsanitize=address -fno-omit-frame-pointer
     CXX = g++-4.8.0 -fsanitize=address -fno-omit-frame-pointer
     F77 = gfortran-4.8.0 -fsanitize=address
     FC = gfortran-4.8.0 -fsanitize=address

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

   (1) not including the version distributed by Apple in `Xcode' 4.6.


File: R-exts.info,  Node: Fortran array bounds checking,  Prev: Using AddressSanitizer,  Up: Using gctorture and memory access

4.3.4 Fortran array bounds checking
-----------------------------------

Most of the Fortran compilers used with R allow code to be compiled
with checking of array bounds: for example `gfortran' has option
`-fbounds-check' and Solaris Studio has `-C'.  This gives an error when
the upper or lower bound is exceeded, e.g.
     At line 97 of file .../src/appl/dqrdc2.f
     Fortran runtime error: Index '1' of dimension 1 of array 'x' above upper bound of 0

   One does need to be aware that lazy programmers often specify Fortran
dimensions as `1' rather than `*' or a real bound:
`stats/src/portsrc.f' was a prolific example.

   It is easy to arrange to use this check on just the code in your
package: add to `~/.R/Makevars' something like (for `gfortran')
     FCFLAGS = -g -O2 -mtune=native -fbounds-check
     FFLAGS = -g -O2 -mtune=native -fbounds-check

when you run `R CMD check'.


File: R-exts.info,  Node: Debugging compiled code,  Prev: Using gctorture and memory access,  Up: Debugging

4.4 Debugging compiled code
===========================

Sooner or later programmers will be faced with the need to debug
compiled code loaded into R.  This section is geared to platforms using
`gdb' with code compiled by `gcc', but similar things are possible with
front-ends to `gdb' such as `ddd' and `insight', and other debuggers
such as `lldb' (used on OS X) and Sun's `dbx'.

   Consider first `crashes', that is when R terminated unexpectedly with
an illegal memory access (a `segfault' or `bus error'), illegal
instruction or similar.  Unix-alike versions of R use a signal handler
which aims to give some basic information.  For example

      *** caught segfault ***
     address 0x20000028, cause 'memory not mapped'

     Traceback:
      1: .identC(class1[[1]], class2)
      2: possibleExtends(class(sloti), classi, ClassDef2 = getClassDef(classi,
     where = where))
      3: validObject(t(cu))
      4: stopifnot(validObject(cu <- as(tu, "dtCMatrix")), validObject(t(cu)),
     validObject(t(tu)))

     Possible actions:
     1: abort (with core dump)
     2: normal R exit
     3: exit R without saving workspace
     4: exit R saving workspace
     Selection: 3

Since the R process may be damaged, the only really safe option is the
first.  (Note that a core dump is only produced where enabled: a common
default in a shell is to limit its size to 0, thereby disabling it.)

   A fairly common cause of such crashes is a package which uses `.C'
or `.Fortran' and writes beyond (at either end) one of the arguments it
is passed.  As from R 3.0.0 there is a good way to detect this: using
`options(CBoundsCheck = TRUE)' (which can be selected _via_ the
environment variable `R_C_BOUNDS_CHECK=yes)' changes the way `.C' and
`.Fortran' work to check if the compiled code writes in the 64 bytes at
either end of an argument.

   Another cause of a `crash' is to overrun the C stack.  R tries to
track that in its own code, but it may happen in third-party compiled
code.  For modern POSIX-compliant OSes R can safely catch that and
return to the top-level prompt, so one gets something like

     > .C("aaa")
     Error: segfault from C stack overflow
     >

However, C stack overflows are fatal under Windows and normally defeat
attempts at debugging on that platform.  Further, the size of the stack
is set when R is compiled, whereas on POSIX OSes it can be set in the
shell from which R is launched.

   If you have a crash which gives a core dump you can use something
like

     gdb /path/to/R/bin/exec/R core.12345

to examine the core dump.  If core dumps are disabled or to catch errors
that do not generate a dump one can run R directly under a debugger by
for example

     $ R -d gdb --vanilla
     ...
     gdb> run

at which point R will run normally, and hopefully the debugger will
catch the error and return to its prompt.  This can also be used to
catch infinite loops or interrupt very long-running code.  For a simple
example

     > for(i in 1:1e7) x <- rnorm(100)
     [hit Ctrl-C]
     Program received signal SIGINT, Interrupt.
     0x00397682 in _int_free () from /lib/tls/libc.so.6
     (gdb) where
     #0  0x00397682 in _int_free () from /lib/tls/libc.so.6
     #1  0x00397eba in free () from /lib/tls/libc.so.6
     #2  0xb7cf2551 in R_gc_internal (size_needed=313)
         at /users/ripley/R/svn/R-devel/src/main/memory.c:743
     #3  0xb7cf3617 in Rf_allocVector (type=13, length=626)
         at /users/ripley/R/svn/R-devel/src/main/memory.c:1906
     #4  0xb7c3f6d3 in PutRNGstate ()
         at /users/ripley/R/svn/R-devel/src/main/RNG.c:351
     #5  0xb7d6c0a5 in do_random2 (call=0x94bf7d4, op=0x92580e8, args=0x9698f98,
         rho=0x9698f28) at /users/ripley/R/svn/R-devel/src/main/random.c:183
     ...

   Some "tricks" worth knowing follow:

* Menu:

* Finding entry points::
* Inspecting R objects::


File: R-exts.info,  Node: Finding entry points,  Next: Inspecting R objects,  Prev: Debugging compiled code,  Up: Debugging compiled code

4.4.1 Finding entry points in dynamically loaded code
-----------------------------------------------------

Under most compilation environments, compiled code dynamically loaded
into R cannot have breakpoints set within it until it is loaded.  To
use a symbolic debugger on such dynamically loaded code under
Unix-alikes use

   * Call the debugger on the R executable, for example by `R -d gdb'.

   * Start R.

   * At the R prompt, use `dyn.load' or `library' to load your shared
     object.

   * Send an interrupt signal.  This will put you back to the debugger
     prompt.

   * Set the breakpoints in your code.

   * Continue execution of R by typing `signal 0<RET>'.

   Under Windows signals may not be able to be used, and if so the
procedure is more complicated.  See the rw-FAQ and
`www.stats.uwo.ca/faculty/murdoch/software/debuggingR/gdb.shtml'
(http://www.stats.uwo.ca/faculty/murdoch/software/debuggingR/gdb.shtml).


File: R-exts.info,  Node: Inspecting R objects,  Prev: Finding entry points,  Up: Debugging compiled code

4.4.2 Inspecting R objects when debugging
-----------------------------------------

The key to inspecting R objects from compiled code is the function
`PrintValue(SEXP S)' which uses the normal R printing mechanisms to
print the R object pointed to by S, or the safer version `R_PV(SEXP S)'
which will only print `objects'.

   One way to make use of `PrintValue' is to insert suitable calls into
the code to be debugged.

   Another way is to call `R_PV' from the symbolic debugger.
(`PrintValue' is hidden as `Rf_PrintValue'.)  For example, from `gdb'
we can use

     (gdb) p R_PV(ab)

using the object `ab' from the convolution example, if we have placed a
suitable breakpoint in the convolution C code.

   To examine an arbitrary R object we need to work a little harder.
For example, let

     R> DF <- data.frame(a = 1:3, b = 4:6)

By setting a breakpoint at `do_get' and typing `get("DF")' at the R
prompt, one can find out the address in memory of `DF', for example

     Value returned is $1 = (SEXPREC *) 0x40583e1c
     (gdb) p *$1
     $2 = {
       sxpinfo = {type = 19, obj = 1, named = 1, gp = 0,
         mark = 0, debug = 0, trace = 0, = 0},
       attrib = 0x40583e80,
       u = {
         vecsxp = {
           length = 2,
           type = {c = 0x40634700 "0>X@D>X@0>X@", i = 0x40634700,
             f = 0x40634700, z = 0x40634700, s = 0x40634700},
           truelength = 1075851272,
         },
         primsxp = {offset = 2},
         symsxp = {pname = 0x2, value = 0x40634700, internal = 0x40203008},
         listsxp = {carval = 0x2, cdrval = 0x40634700, tagval = 0x40203008},
         envsxp = {frame = 0x2, enclos = 0x40634700},
         closxp = {formals = 0x2, body = 0x40634700, env = 0x40203008},
         promsxp = {value = 0x2, expr = 0x40634700, env = 0x40203008}
       }
     }

(Debugger output reformatted for better legibility).

   Using `R_PV()' one can "inspect" the values of the various elements
of the SEXP, for example,

     (gdb) p R_PV($1->attrib)
     $names
     [1] "a" "b"

     $row.names
     [1] "1" "2" "3"

     $class
     [1] "data.frame"

     $3 = void

   To find out where exactly the corresponding information is stored,
one needs to go "deeper":

     (gdb) set $a = $1->attrib
     (gdb) p $a->u.listsxp.tagval->u.symsxp.pname->u.vecsxp.type.c
     $4 = 0x405d40e8 "names"
     (gdb) p $a->u.listsxp.carval->u.vecsxp.type.s[1]->u.vecsxp.type.c
     $5 = 0x40634378 "b"
     (gdb) p $1->u.vecsxp.type.s[0]->u.vecsxp.type.i[0]
     $6 = 1
     (gdb) p $1->u.vecsxp.type.s[1]->u.vecsxp.type.i[1]
     $7 = 5

   Another alternative is the `R_inspect' function which shows the
low-level structure of the objects recursively (addresses differ from
the above as this example is created on another machine):

     (gdb) p R_inspect($1)
     @100954d18 19 VECSXP g0c2 [OBJ,NAM(2),ATT] (len=2, tl=0)
       @100954d50 13 INTSXP g0c2 [NAM(2)] (len=3, tl=0) 1,2,3
       @100954d88 13 INTSXP g0c2 [NAM(2)] (len=3, tl=0) 4,5,6
     ATTRIB:
       @102a70140 02 LISTSXP g0c0 []
         TAG: @10083c478 01 SYMSXP g0c0 [MARK,NAM(2),gp=0x4000] "names"
         @100954dc0 16 STRSXP g0c2 [NAM(2)] (len=2, tl=0)
           @10099df28 09 CHARSXP g0c1 [MARK,gp=0x21] "a"
           @10095e518 09 CHARSXP g0c1 [MARK,gp=0x21] "b"
         TAG: @100859e60 01 SYMSXP g0c0 [MARK,NAM(2),gp=0x4000] "row.names"
         @102a6f868 13 INTSXP g0c1 [NAM(2)] (len=2, tl=1) -2147483648,-3
         TAG: @10083c948 01 SYMSXP g0c0 [MARK,gp=0x4000] "class"
         @102a6f838 16 STRSXP g0c1 [NAM(2)] (len=1, tl=1)
           @1008c6d48 09 CHARSXP g0c2 [MARK,gp=0x21,ATT] "data.frame"

   In general the representation of each object follows the format:

     @<address> <type-nr> <type-name> <gc-info> [<flags>] ...

   For a more fine-grained control over the the depth of the recursion
and the output of vectors `R_inspect3' takes additional two integer
parameters: maximum depth and the maximal number of elements that will
be printed for scalar vectors. The defaults in `R_inspect' are
currently -1 (no limit) and 5 respectively.


File: R-exts.info,  Node: System and foreign language interfaces,  Next: The R API,  Prev: Debugging,  Up: Top

5 System and foreign language interfaces
****************************************

* Menu:

* Operating system access::
* Interface functions .C and .Fortran::
* dyn.load and dyn.unload::
* Registering native routines::
* Creating shared objects::
* Interfacing C++ code::
* Fortran I/O::
* Linking to other packages::
* Handling R objects in C::
* Interface functions .Call and .External::
* Evaluating R expressions from C::
* Parsing R code from C::
* External pointers and weak references::
* Vector accessor functions::
* Character encoding issues::


File: R-exts.info,  Node: Operating system access,  Next: Interface functions .C and .Fortran,  Prev: System and foreign language interfaces,  Up: System and foreign language interfaces

5.1 Operating system access
===========================

Access to operating system functions is _via_ the R functions `system'
and `system2'.  The details will differ by platform (see the on-line
help), and about all that can safely be assumed is that the first
argument will be a string `command' that will be passed for execution
(not necessarily by a shell) and the second argument to `system' will be
`internal' which if true will collect the output of the command into an
R character vector.

   The function `system.time' is available for timing.  Timing on child
processes is only available on Unix-alikes, and may not be reliable
there.


File: R-exts.info,  Node: Interface functions .C and .Fortran,  Next: dyn.load and dyn.unload,  Prev: Operating system access,  Up: System and foreign language interfaces

5.2 Interface functions `.C' and `.Fortran'
===========================================

These two functions provide an interface to compiled code that has been
linked into R, either at build time or _via_ `dyn.load' (*note dyn.load
and dyn.unload::).  They are primarily intended for compiled C and
FORTRAN 77 code respectively, but the `.C' function can be used with
other languages which can generate C interfaces, for example C++ (*note
Interfacing C++ code::).

   The first argument to each function is a character string specifying
the symbol name as known(1) to C or FORTRAN, that is the function or
subroutine name.  (That the symbol is loaded can be tested by, for
example, `is.loaded("cg")'.  Use the name you pass to `.C' or
`.Fortran' rather than the translated symbol name.)

   There can be up to 65 further arguments giving R objects to be passed
to compiled code.  Normally these are copied before being passed in, and
copied again to an R list object when the compiled code returns.  If
the arguments are given names, these are used as names for the
components in the returned list object (but not passed to the compiled
code).

   The following table gives the mapping between the modes of R atomic
vectors and the types of arguments to a C function or FORTRAN
subroutine.

     R storage mode     C type                   FORTRAN type
     --------------------------------------------------------------- 
     `logical'          `int *'                  `INTEGER'
     `integer'          `int *'                  `INTEGER'
     `double'           `double *'               `DOUBLE PRECISION'
     `complex'          `Rcomplex *'             `DOUBLE COMPLEX'
     `character'        `char **'                `CHARACTER*255'
     `raw'              `unsigned char *'        none

   Do please note the first two.  On the 64-bit Unix/Linux/OS X
platforms, `long' is 64-bit whereas `int' and `INTEGER' are 32-bit.
Code ported from S-PLUS (which uses `long *' for `logical' and
`integer') will not work on all 64-bit platforms (although it may
appear to work on some, including Windows).  Note also that if your
compiled code is a mixture of C functions and FORTRAN subprograms the
argument types must match as given in the table above.

   C type `Rcomplex' is a structure with `double' members `r' and `i'
defined in the header file `R_ext/Complex.h' included by `R.h'.  (On
most platforms this is stored in a way compatible with the C99 `double
complex' type: however, it may not be possible to pass `Rcomplex' to a
C99 function expecting a `double complex' argument.  Nor need it be
compatible with a C++ `complex' type.  Moreover, the compatibility can
depends on the optimization level set for the compiler.)

   Only a single character string can be passed to or from FORTRAN, and
the success of this is compiler-dependent.  Other R objects can be
passed to `.C', but it is much better to use one of the other
interfaces.

   It is possible to pass numeric vectors of storage mode `double' to C
as `float *' or to FORTRAN as `REAL' by setting the attribute
`Csingle', most conveniently by using the R functions `as.single',
`single' or `mode'.  This is intended only to be used to aid
interfacing existing C or FORTRAN code.

   Logical values are sent as `0' (`FALSE'), `1' (`TRUE') or `INT_MIN =
-2147483648' (`NA', but only if `NAOK' is true), and the compiled code
should return one of these three values.  (Non-zero values other than
`INT_MIN' are mapped to `TRUE'.)

   Unless formal argument `NAOK' is true, all the other arguments are
checked for missing values `NA' and for the IEEE special values `NaN',
`Inf' and `-Inf', and the presence of any of these generates an error.
If it is true, these values are passed unchecked.

   Argument `DUP' can be used to suppress copying.  It is dangerous:
see the on-line help for arguments against its use.  It is not possible
to pass numeric vectors as `float *' or `REAL' if `DUP = FALSE', and
character vectors cannot be used.

   Argument `PACKAGE' confines the search for the symbol name to a
specific shared object (or use `"base"' for code compiled into R).  Its
use is highly desirable, as there is no way to avoid two package
writers using the same symbol name, and such name clashes are normally
sufficient to cause R to crash.  (If it is not present and the call is
from the body of a function defined in a package namespace, the shared
object loaded by the first (if any) `useDynLib' directive will be used.
However, prior to R 2.15.2 the detection of the correct namespace is
unreliable and you are strongly recommended to use the `PACKAGE'
argument for packages to be used with earlier versions of R.

   Note that the compiled code should not return anything except through
its arguments: C functions should be of type `void' and FORTRAN
subprograms should be subroutines.

   To fix ideas, let us consider a very simple example which convolves
two finite sequences. (This is hard to do fast in interpreted R code,
but easy in C code.)  We could do this using `.C' by

     void convolve(double *a, int *na, double *b, int *nb, double *ab)
     {
         int nab = *na + *nb - 1;

         for(int i = 0; i < nab; i++)
             ab[i] = 0.0;
         for(int i = 0; i < *na; i++)
             for(int j = 0; j < *nb; j++)
                 ab[i + j] += a[i] * b[j];
     }

called from R by

     conv <- function(a, b)
         .C("convolve",
            as.double(a),
            as.integer(length(a)),
            as.double(b),
            as.integer(length(b)),
            ab = double(length(a) + length(b) - 1))$ab

   Note that we take care to coerce all the arguments to the correct R
storage mode before calling `.C'; mistakes in matching the types can
lead to wrong results or hard-to-catch errors.

   Special care is needed in handling `character' vector arguments in C
(or C++).  Since only `DUP = TRUE' is allowed, on entry the contents of
the elements are duplicated and assigned to the elements of a `char **'
array, and on exit the elements of the C array are copied to create new
elements of a character vector.  This means that the contents of the
character strings of the `char **' array can be changed, including to
`\0' to shorten the string, but the strings cannot be lengthened.  It
is possible(2) to allocate a new string _via_ `R_alloc' and replace an
entry in the `char **' array by the new string.  However, when character
vectors are used other than in a read-only way, the `.Call' interface
is much to be preferred.

   Passing character strings to FORTRAN code needs even more care, and
should be avoided where possible.  Only the first element of the
character vector is passed in, as a fixed-length (255) character array.
Up to 255 characters are passed back to a length-one character vector.
How well this works (or even if it works at all) depends on the C and
FORTRAN compilers on each platform.

   It is possible to pass R objects other than atomic vectors via `.C',
but this is only supported for historical compatibility: use the
`.Call' or `.External' interfaces for such objects.  Any C/C++ code
that includes `Rinternals.h' should be called via `.Call' or
`.External'.

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

   (1) possibly after some platform-specific translation, e.g. adding
leading or trailing underscores.

   (2) Note that this is then not checked for over-runs by option
`CBoundsCheck = TRUE'.


File: R-exts.info,  Node: dyn.load and dyn.unload,  Next: Registering native routines,  Prev: Interface functions .C and .Fortran,  Up: System and foreign language interfaces

5.3 `dyn.load' and `dyn.unload'
===============================

Compiled code to be used with R is loaded as a shared object
(Unix-alikes including OS X, *note Creating shared objects:: for more
information) or DLL (Windows).

   The shared object/DLL is loaded by `dyn.load' and unloaded by
`dyn.unload'.  Unloading is not normally necessary, but it is needed to
allow the DLL to be re-built on some platforms, including Windows.

   The first argument to both functions is a character string giving the
path to the object.  Programmers should not assume a specific file
extension for the object/DLL (such as `.so') but use a construction like

     file.path(path1, path2, paste0("mylib", .Platform$dynlib.ext))

for platform independence.  On Unix-alike systems the path supplied to
`dyn.load' can be an absolute path, one relative to the current
directory or, if it starts with `~', relative to the user's home
directory.

   Loading is most often done automatically based on the `useDynLib()'
declaration in the `NAMESPACE' file, but may be done explicitly _via_ a
call to `library.dynam'.  This has the form

     library.dynam("libname", package, lib.loc)

where `libname' is the object/DLL name _with the extension omitted_.
Note that the first argument, `chname', should *not* be `package' since
this will not work if the package is installed under another name.

   Under some Unix-alike systems there is a choice of how the symbols
are resolved when the object is loaded, governed by the arguments
`local' and `now'.  Only use these if really necessary: in particular
using `now=FALSE' and then calling an unresolved symbol will terminate
R unceremoniously.

   R provides a way of executing some code automatically when a
object/DLL is either loaded or unloaded.  This can be used, for
example, to register native routines with R's dynamic symbol mechanism,
initialize some data in the native code, or initialize a third party
library.  On loading a DLL, R will look for a routine within that DLL
named `R_init_LIB' where LIB is the name of the DLL file with the
extension removed.  For example, in the command

     library.dynam("mylib", package, lib.loc)

R looks for the symbol named `R_init_mylib'.  Similarly, when unloading
the object, R looks for a routine named `R_unload_LIB', e.g.,
`R_unload_mylib'.  In either case, if the routine is present, R will
invoke it and pass it a single argument describing the DLL.  This is a
value of type `DllInfo' which is defined in the `Rdynload.h' file in
the `R_ext' directory.

   Note that there are some implicit restrictions on this mechanism as
the basename of the DLL needs to be both a valid file name and valid as
part of a C entry point (e.g. it cannot contain `.'): for portable code
it is best to confine DLL names to be ASCII alphanumeric plus
underscore.  If entry point `R_init_LIB' is not found it is also looked
for with `.' replaced by `_'.

   The following example shows templates for the initialization and
unload routines for the `mylib' DLL.

          #include <R.h>
          #include <Rinternals.h>
          #include <R_ext/Rdynload.h>

          void
          R_init_mylib(DllInfo *info)
          {
            /* Register routines,
               allocate resources. */
          }

          void
          R_unload_mylib(DllInfo *info)
          {
            /* Release resources. */
          }

   If a shared object/DLL is loaded more than once the most recent
version is used.  More generally, if the same symbol name appears in
several shared objects, the most recently loaded occurrence is used.
The `PACKAGE' argument and registration (see the next section) provide
good ways to avoid any ambiguity in which occurrence is meant.

   On Unix-alikes the paths used to resolve dynamically linked dependent
libraries are fixed (for security reasons) when the process is launched,
so `dyn.load' will only look for such libraries in the locations set by
the `R' shell script (_via_ `etc/ldpaths') and in the OS-specific
defaults.

   Windows allows more control (and less security) over where dependent
DLLs are looked for.  On all versions this includes the `PATH'
environment variable, but with lowest priority: note that it does not
include the directory from which the DLL was loaded.  It is possible to
add a single path with quite high priority _via_ the `DLLpath' argument
to `dyn.load'.  This is (by default) used by `library.dynam' to include
the package's `libs/i386' or `libs/x64' directory in the DLL search
path.



Local Variables:
coding: iso-8859-1
End:
