Chapter 10 Concept index
A B C D E F G H I L M N O P R S T U V W Z
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,
bug.report will try to extract an email address from a
Contact field if there is no
even one wrapped in
This includes all packages directly called by
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 http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html. 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.
g77 up to 2011, and some pre-built versions of R for Unix OSes still do.
The changes are linked from https://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations.
201402L are most commonly used for C++98, C++11 and C++14 respectively, but some compilers set
Some distributions, notably Debian, have supplied a build of
g++’s headers and library. Conversely, Apple’s command named
g++ is based on
For details of these and related macros, see file config.site 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 https://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations or http://en.cppreference.com/w/cpp/experimental/feature_test. 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.
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 http://www.opencsw.org. The source repository is ftp://ftp.astron.com/pub/file/.
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
loading, examples, tests, running vignette code
called CVS or .svn or .arch-ids or .bzr or .git (but not files called .git) or .hg.
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
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
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.
dev.new() to open a device at a particular size: that is not portable but using
dev.new(noRStudioGD = TRUE) helps.
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.
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)’.
http://fortranwiki.org/fortran/show/Modernizing+Old+Fortran 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
srandom are in any case not portable. They are in POSIX but not in the C99 standard, and not available on Windows.
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
_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.
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.
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
Currently it is rendered differently only in HTML conversions, and LaTeX conversion outside ‘\usage’ and ‘\examples’ environments.
a common example in CRAN packages is
There is only a fine distinction between
\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
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
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 https://llvm.org/svn/llvm-project/compiler-rt/trunk/lib/asan/scripts/asan_symbolize.py: it makes use of
llvm-symbolizer if available.
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) http://llvm.org/releases/4.0.0/tools/clang/docs/UsersManual.html.
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
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: https://gcc.gnu.org/onlinedocs/libstdc++/manual/using_dual_abi.html.
dyld on macOS, and
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
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
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
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
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.