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.

(2)

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.

(3)

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

(4)

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

(5)

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

(6)

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

(7)

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

(8)

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

(9)

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

(10)

even one wrapped in \donttest.

(11)

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

(12)

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.

(13)

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

(14)

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

(15)

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

(16)

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.

(17)

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

(18)

Using .hpp is not guaranteed to be portable.

(19)

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

(20)

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

(21)

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

(22)

e.g. https://tools.ietf.org/html/rfc4180.

(23)

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

(24)

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

(25)

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

(26)

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

(27)

http://www.openmp.org/, https://en.wikipedia.org/wiki/OpenMP, https://computing.llnl.gov/tutorials/openMP/

(28)

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

(29)

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.

(30)

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

(31)

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

(32)

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

(33)

Windows default, not MinGW-w64 default.

(34)

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

(35)

some Windows toolchains had the typo ‘_REENTRANCE’ instead.

(36)

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.

(37)

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

(38)

The changes are linked from https://isocpp.org/std/standing-documents/sd-6-sg10-feature-test-recommendations.

(39)

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

(40)

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

(41)

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

(42)

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.

(43)

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.

(44)

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

(45)

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 http://www.opencsw.org. The source repository is ftp://ftp.astron.com/pub/file/.

(46)

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

(47)

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.

(48)

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

(49)

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

(50)

loading, examples, tests, running vignette code

(51)

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

(52)

called .metadata.

(53)

which is an error: GNU make uses GNUmakefile.

(54)

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

(55)

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

(56)

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.

(57)

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.

(58)

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

(59)

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

(60)

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

(61)

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

(62)

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.

(63)

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

(64)

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

(65)

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

(66)

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

(67)

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

(68)

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.

(69)

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)

http://fortranwiki.org/fortran/show/Modernizing+Old+Fortran may help explain some of the warnings from gfortran -Wall -pedantic.

(71)

See http://people.ds.cam.ac.uk/nmm1/fortran/paper_07.pdf.

(72)

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

(73)

or where supported the variants _Exit and _exit.

(74)

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

(75)

in libselinux.

(76)

At least Linux and Windows, but not macOS.

(77)

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

(78)

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

(79)

some versions of macOS did not.

(80)

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

(81)

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

(82)

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

(83)

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

(84)

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

(85)

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

(86)

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.

(87)

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

(88)

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

(89)

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

(90)

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

(91)

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

(92)

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.

(93)

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.

(94)

Text between or after list items is discouraged.

(95)

as defined by the R function trimws.

(96)

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

(97)

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

(98)

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.