Chapter 10 Concept index

Jump to:   .   \  
A   B   C   D   E   F   G   H   I   L   M   N   O   P   R   S   T   U   V   W   Z  

Index Entry




.install_extras file:


Writing package vignettes

.Rbuildignore file:


Building package tarballs

.Rinstignore file:


Package subdirectories






Allocating storage:


Allocating storage





Bessel functions:


Mathematical functions

Beta function:


Mathematical functions

Building binary packages:


Building binary packages

Building source packages:


Building package tarballs


C++ code, interfacing:


Interfacing C++ code

Calling C from FORTRAN and vice versa:


Calling C from FORTRAN and vice versa

Checking packages:


Checking packages



Package subdirectories



Preparing translations




cleanup file:


Package structure



Conditional text

configure file:


Package structure

Copying objects:


Named objects and copying



Creating R packages

Creating packages:


Creating R packages

Creating shared objects:


Creating shared objects

Cross-references in documentation:



cumulative hazard:


Distribution functions




Debugging compiled code




Details of R types:


Details of R types

Distribution functions from C:


Distribution functions

Documentation, writing:


Writing R documentation files

Dynamic loading:


dyn.load and dyn.unload

dynamic pages:


Dynamic pages


Editing Rd files:


Editing Rd files




Error handling from C:


Error handling

Error handling from FORTRAN:


Error handling from FORTRAN

Evaluating R expressions from C:


Evaluating R expressions from C

external pointer:


External pointers and weak references


Figures in documentation:





External pointers and weak references

Finding variables:


Finding and setting variables


Gamma function:


Mathematical functions

Garbage collection:


Garbage Collection

Generic functions:


Generic functions and methods


handling character data:


Handling character data

Handling lists:


Handling lists

Handling R objects in C:


Handling R objects in C


IEEE special values:


Missing and special values

IEEE special values:


Missing and IEEE values

INDEX file:


The INDEX file




Inspecting R objects when debugging:


Inspecting R objects




Interfaces to compiled code:


Interface functions .C and .Fortran

Interfaces to compiled code:


Interface functions .Call and .External

Interfacing C++ code:


Interfacing C++ code



Allowing interrupts








Lists and tables in documentation:


Lists and tables


Marking text in documentation:


Marking text

Mathematics in documentation:



Memory allocation from C:


Memory allocation

Memory use:


Profiling R code for memory use

Method functions:


Generic functions and methods

Missing values:


Missing and special values

Missing values:


Missing and IEEE values




Package namespaces



Package subdirectories

Numerical analysis subroutines from C:


Numerical analysis subroutines

Numerical derivatives:


Calculating numerical derivatives




OpenMP support



Platform and version information

Operating system access:


Operating system access





Package builder:


Building package tarballs

Package structure:


Package structure

Package subdirectories:


Package subdirectories



Creating R packages

Parsing R code from C:


Parsing R code from C

Platform-specific documentation:


Platform-specific sections

Printing from C:



Printing from FORTRAN:


Printing from FORTRAN

Processing Rd format:


Processing documentation files



Profiling R code for speed



Profiling R code for memory use



Profiling compiled code


Random numbers in C:


Random numbers

Random numbers in C:


Distribution functions

Random numbers in FORTRAN:


Calling C from FORTRAN and vice versa

Registering native routines:


Registering native routines


Setting variables:


Finding and setting variables

Sort functions from C:


Utility functions



Writing package vignettes




Building package tarballs

Tidying R code:


Tidying R code


user-defined macros:


User-defined macros


Version information from C:


Platform and version information



Writing package vignettes



Controlling visibility


weak reference:


External pointers and weak references





Jump to:   .   \  
A   B   C   D   E   F   G   H   I   L   M   N   O   P   R   S   T   U   V   W   Z  



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.


This seems to be commonly used for a file in ‘markdown’ format. Be aware that most users of R will not know that, nor know how to view such a file: platforms such as macOS and Windows do not have a default viewer set in their file associations. The CRAN package web pages render such files in HTML: the converter used expects the file to be encoded in UTF-8.


currently, top-level files .Rbuildignore and .Rinstignore, and vignettes/.install_extras.


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


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


and required by CRAN, so checked by R CMD check –as-cran.


But it is checked for Open Source packages by R CMD check –as-cran.


Duplicate definitions may trigger a warning: see User-defined macros.


As from R 3.4.0, will try to extract an email address from a Contact field if there is no BugReports field.


even one wrapped in \donttest.


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


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.


but they should be in the encoding declared in the DESCRIPTION file.


This is true for OSes which implement the ‘C’ locale: Windows’ idea of the ‘C’ locale uses the WinAnsi charset.


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


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.


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


Using .hpp is not guaranteed to be portable.


There is also ‘APPLE_CC’, but that indicates a compiler with Apple-specific features, not the OS. It is used in Rinlinedfuns.h.


the POSIX terminology, called ‘make variables’ by GNU make.


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. Be careful not to use output with the option –timings (and note that –as-cran sets it).




People who have trouble with case are advised to use .rda as a common error is to refer to abc.RData as abc.Rdata!


The script should only assume a POSIX-compliant /bin/sh – see In particular bash extensions must not be used, and not all R platforms have a bash command, let alone one at /bin/bash. All known shells used with R support the use of backticks, but not all support ‘$(cmd)’.


in POSIX parlance: GNU make calls these ‘make variables’.


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



Default builds of clang 3.8.0 and later have support for OpenMP, but the libomp run-time library may not be installed.


In most implementations the _OPENMP macro has value a date which can be mapped to an OpenMP version: for example, value 201307 is the date of version 4.0 (July 2013). However this may be used to denote the latest version which is partially supported, not that which is fully implemented.


GCC since 4.7, hence R builds for Windows since R 3.3.0, which also support OpenMP 4.0.


People do use older versions of OSes such as Ubuntu 12.04LTS and Debian Wheezy LTS which have GCC 4.4.


as did the GCC-based Apple implementation, but not the Intel/LLVM OpenMP runtime on macOS.


Windows default, not MinGW-w64 default.


Which it was at the time of writing with GCC, Oracle, Intel and Clang compilers.


some Windows toolchains had the typo ‘_REENTRANCE’ instead.


A few OSes (AIX, IRIX, Windows) do not need special flags for such code, but most do—although compilers will often generate PIC code when not asked to do so.


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


The changes are linked from


Values 199711, 201103L and 201402L are most commonly used for C++98, C++11 and C++14 respectively, but some compilers set 1L.


Some distributions, notably Debian, have supplied a build of clang with g++’s headers and library. Conversely, Apple’s command named g++ is based on clang using libc++.


For details of these and related macros, see file in the R sources.


As from R 3.4.0, configure attempts to supply a C++14 compiler only if explicitly requested. However, earlier versions of R will use the default C++14 mode of g++ 6 and later.


See or It seems a reasonable assumption that any compiler promising some C++14 conformance will provide these—e.g. g++ 4.9.x did but 4.8.5 did not.


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


A suitable file.exe is part of the Windows toolset: it checks for gfile if a suitable file is not found: the latter is available in the OpenCSW collection for Solaris at The source repository is


An exception is made for subdirectories with names starting ‘win’ or ‘Win’.


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.


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


For example, in early 2014 gdata declared ‘Imports: gtools’ and gtools declared ‘Imports: gdata’.


loading, examples, tests, running vignette code


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


called .metadata.


which is an error: GNU make uses GNUmakefile.


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


unless inhibited by using ‘BuildVignettes: no’ in the DESCRIPTION file.


provided the conditions of the package’s license are met: many, including CRAN, see the omission of source components as incompatible with an Open Source license.


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.


Note that lazy-loaded datasets are not in the package’s namespace so need to be accessed via ::, e.g.


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


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


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


This was necessary at least prior to R 3.0.2 as the methods package looked for its own R code on the search path.


This defaults to the same pattern as exportPattern: use something like exportClassPattern(“^$”) to override this.


if it does, there will be opaque warnings about replacing imports if the classes/methods are also imported.


People use to open a device at a particular size: that is not portable but using = TRUE) helps.


Solaris make does not accept CRLF-terminated Makefiles; Solaris warns about and some other makes ignore incomplete final lines.


This was apparently introduced in SunOS 4, and is available elsewhere provided it is surrounded by spaces.


GNU make, BSD make formerly in FreeBSD and macOS, AT&T make as implemented on Solaris, pmake in FreeBSD, ‘Distributed Make’ (dmake), part of Oracle Studio and available in other versions.


For example, test options -a and -e are not portable, and not supported in the AT&T Bourne shell used on Solaris 10/11, even though they are in the 2008 POSIX standard. Nor does Solaris support ‘$(cmd)’.

(70) may help explain some of the warnings from gfortran -Wall -pedantic.




but note that long long is not a standard C++98 type, and C++ compilers set up for strict checking will reject it.


or where supported the variants _Exit and _exit.


This and srandom are in any case not portable. They are in POSIX but not in the C99 standard, and not available on Windows.


in libselinux.


At least Linux and Windows, but not macOS.


except perhaps the simplest kind as used by download.file() in non-interactive use.


Whereas the GNU linker reorders so -L options are processed first, the Solaris one does not.


some versions of macOS did not.


For example, the ability to handle ‘https://’ URLs, which even the build in some major Linux distributions in 2017 did not possess.


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


These are not needed for the default compiler settings on ‘x86_64’ but are likely to be needed on ‘ix86’.


Select ‘Save as’, and select ‘Reduce file size’ from the ‘Quartz filter’ menu’: this can be accessed in other ways, for example by Automator.


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


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


This is seen on Linux, Solaris and FreeBSD, although each has other ways to turn on all extensions, e.g. defining _GNU_SOURCE, EXTENSIONS or _BSD_SOURCE: the GCC compilers by default define _GNU_SOURCE unless a strict standard such as -std=c99 is used. On macOS extensions are declared unless one of these macros is given too small a value.


Solaris 10 does not recognize this value of _POSIX_C_SOURCE, nor values of _XOPEN_SOURCE beyond 600.


E.g. gcc 5.3 in C++11 mode.


There is a portable way to do this in Fortran 2003 (ieee_is_nan() in module ieee_arithmetic), but ironically that is not supported in the commonly-used versions 4.x of GNU Fortran. A pretty robust alternative is to test if(my_var /= my_var).


which often is the same as the header included by the C compiler, but some compilers have wrappers for some of the C headers.


e.g. \alias, \keyword and \note sections.


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.


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.


Text between or after list items is discouraged.


as defined by the R function trimws.


Currently it is rendered differently only in HTML conversions, and LaTeX conversion outside ‘\usage’ and ‘\examples’ environments.


a common example in CRAN packages is \link[mgcv]{gam}.


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.


See the examples section in the file Paren.Rd for an example.


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.


R has to be built to enable this, but the option –enable-R-profiling is the default.


For Unix-alikes these are intervals of CPU time, and for Windows of elapsed time.


With the exceptions of the commands listed below: an object of such a name can be printed via an explicit call to print.


at the time of writing mainly for 10.9 with some support for 10.8, none for the current 10.10.


Those in some numeric, logical, integer, raw, complex vectors and in memory allocated by R_alloc.


including using the data sections of R vectors after they are freed.


small fixed-size arrays by default in gfortran, for example.


currently on Linux and macOS (including the builds from Xcode 7 and later), with some support for Solaris. On some platforms the runtime library, libasan, needs to be installed separately, and for checking C++ you may also need libubsan.




part of the LLVM project and in distributed in llvm RPMs and .debs on Linux. It is not currently shipped by Apple.


as Ubuntu is said to do.


installed on some Linux systems as asan_symbolize, and obtainable from it makes use of llvm-symbolizer if available.


including gcc 7.1 and clang 4.0.0: for gcc it is implied by -fsanitize=address.


On some platforms the runtime library, libubsan, needs to be installed separately.


or the user manual for your version of clang, e.g. (the paths have differed for some versions)


but works better if inlining and frame pointer optimizations are disabled.


possibly after some platform-specific translation, e.g. adding leading or trailing underscores.


Note that this is then not checked for over-runs by option CBoundsCheck = TRUE.


Strictly this is OS-specific, but no exceptions have been seen for many years.


For calls from within a namespace the search is confined to the DLL loaded for that package.


For unregistered entry points the OS’s dlsym routine is used to find addresses. Its performance varies considerably by OS and even in the best case it will need to search a much larger symbol table than, say, the table of .Call entry points.


Because it is a standard package, one would need to rename it before attempting to reproduce the account here.


whether or not ‘LinkingTo’ is used.


so there needs to be a corresponding import or importFrom entry in the NAMESPACE file.


Even including C system headers in such a block has caused compilation errors.


with an exception for the Solaris C++ compiler, removed in R 3.4.0.



For example, ‘_GLIBCXX_USE_CXX11_ABI’ in g++ 5.1 and later:


dyld on macOS, and DYLD_LIBRARY_PATHS below.


That is, similar to those defined in S version 4 from the 1990s: these are not kept up to date and are not recommended for new projects. Prior to R 3.3.0 it was not compatible with defining R_NO_REMAP.


see The R API: note that these are not all part of the API.


SEXP is an acronym for Simple EXPression, common in LISP-like language syntaxes.


If no coercion was required, coerceVector would have passed the old object through unchanged.


You can assign a copy of the object in the environment frame rho using defineVar(symbol, duplicate(value), rho)).


see Character encoding issues for why this might not be what is required.


This is only guaranteed to show the current interface: it is liable to change.


Known problems are redefining LENGTH, error, length, vector and warning


also part of C++11.


It is an optional C11 extension.


but see the second paragraph of see Portable C and C++ code.



It is defined by the Intel compilers, but also hides unsatisfied references and so cannot be used with R. It is not supported by the AIX nor Solaris compilers.


In the parlance of macOS this is a dynamic library, and is the normal way to build R on that platform.


but these are not part of the automated test procedures and so little tested.


At least according to POSIX 2004 and later. Earlier standards prescribed sys/time.h and HP-UX continued to use that: R_ext/eventloop.h will include it from R 3.4.0 if HAVE_SYS_TIME_H is defined.


at least on platforms where the values are available, that is having getrlimit and on Linux or having sysctl supporting KERN_USRSTACK, including FreeBSD and OS X.


An attempt to use only threads in the late 1990s failed to work correctly under Windows 95, the predominant version of Windows at that time.