2 Installing R under Unix-alikes

R will configure and build under most common Unix and Unix-alike platforms including cpu-*-linux-gnu for the alpha, arm64 (also known as aarch64, ix86, mips, mipsel#, ppc64, riscv64, s390x, sparc64, and x86_64 CPUs, aarch64-apple-darwin¹ and x86_64-apple-darwin as well as perhaps (it is tested less frequently on these platforms) x86_64-*-freebsd, x86_64-*-openbsd and powerpc-ibm-aix6*

¹ aka ‘Apple Silicon’, known to some as arm64-apple-darwin.

Only 64-bit platforms are tested regularly, and configure will warn if it encounters a 32-bit one.

In addition, binary distributions are available for some common Linux distributions (see the FAQ for current details) and for macOS. These are installed in platform-specific ways, so for the rest of this chapter we consider only building from the sources.

Cross-building is not possible: installing R builds a minimal version of R and then runs many R scripts to complete the build.

2.1 Simple compilation

First review the essential and useful tools and libraries in Essential and useful other programs under a Unix-alike, and install those you want or need. Ensure that either the environment variable TMPDIR is either unset (and /tmp exists and can be written in and scripts can be executed from) or points to the absolute path to a valid temporary directory (one from which execution of scripts is allowed) which does not contain spaces.

Choose a directory to install the R tree (R is not just a binary, but has additional data sets, help files, font metrics etc). Let us call this place R_HOME. Untar the source code. This should create directories src, doc, and several more under a top-level directory: change to that top-level directory (At this point North American readers should consult Setting paper size.) Issue the following commands:

./configure
make

(See Using make if your make is not called make.) Users of Debian-based 64-bit systems² may need

² which use lib rather than lib64 for their primary 64-bit library directories: attempts are made to detect such systems.

./configure LIBnn=lib
make

Then check the built system works correctly by

make check

Failures are not necessarily problems as they might be caused by missing functionality, but you should look carefully at any reported discrepancies. (Some non-fatal errors are expected in locales that do not support Latin-1, in particular in true C locales and non-UTF-8 non-Western-European locales.) A failure in tests/ok-errors.R may indicate inadequate resource limits (see Running R).

More comprehensive testing can be done by

make check-devel

make check-all

see Testing an Installation for the possibilities of doing this in parallel. Note that these checks are only run completely if the recommended packages are installed. If you have a local CRAN mirror, these checks can be speeded up by either setting environment variable R_CRAN_WEB to its URL, or having a file .R/repositories specifying it (see ?setRepositories).

make check-devel checks the included packages’ tests directories. For grDevices more complete checks will be run if the environment variable R_GRDEVICES_COMPARE_PS_PDF is set: those checks are skipped on platforms using musl such as Alpine Linux, and it knows about differences from transliterations in macOS 14 and later.

Parallel make is supported for building R but not for the check targets (as the output is likely to be unreadably interleaved, although where supported³ GNU make’s -O may help).

³ not by the version supplied by macOS.

If the configure and make commands execute successfully, a shell-script front-end called R will be created and copied to R_HOME/bin. You can link or copy this script to a place where users can invoke it, for example to /usr/local/bin/R. You could also copy the man page R.1 to a place where your man reader finds it, such as /usr/local/man/man1. If you want to install the complete R tree to, e.g., /usr/local/lib/R, see Installation. Note: you do not need to install R: you can run it from where it was built.

You do not necessarily have to build R in the top-level source directory (say, TOP_SRCDIR). To build in BUILDDIR, run

cd BUILDDIR
TOP_SRCDIR/configure
make

and so on, as described further below. This has the advantage of always keeping your source tree clean and is particularly recommended when you work with a version of R from Subversion. (You may need GNU make to allow this, and you will need no spaces in the path to the build directory. It is unlikely to work if the source directory has previously been used for a build.)

There are many settings which can be customized when building R and most are described in the file config.site in the top-level source directory. This can be edited, but for an installation using BUILDDIR it is better to put the changed settings in a newly-created file config.site in the build directory.

Now rehash if necessary, type R, and read the R manuals and the R FAQ (files FAQ or doc/manual/R-FAQ.html, or https://CRAN.R-project.org/doc/FAQ/R-FAQ.html which always has the version for the latest release of R).

Note: if you already have R installed, check that where you installed R replaces or comes earlier in your path than the previous installation. Some systems are set up to have /usr/bin (the standard place for a system installation) ahead of /usr/local/bin (the default place for installation of R) in their default path, and some do not have /usr/local/bin on the default path.

2.2 Help options

R by default provides help pages as plain text displayed in a pager, with the options (see the help for help) of displaying help as HTML or PDF.

By default HTML help pages are created when needed rather than being built at install time.

If you need to disable the server and want HTML help, there is the option to build HTML pages when packages are installed (including those installed with R). This is enabled by the configure option --enable-prebuilt-html. Whether R CMD INSTALL (and hence install.packages) pre-builds HTML pages is determined by looking at the R installation and is reported by R CMD INSTALL --help: it can be overridden by specifying one of the INSTALL options --html or --no-html.

The server is disabled by setting the environment variable R_DISABLE_HTTPD to a non-empty value, either before R is started or within the R session before HTML help (including help.start) is used. It is also possible that system security measures will prevent the server from being started, for example if the loopback interface has been disabled. See ?tools::startDynamicHelp for more details.

2.3 Making the manuals

There is a set of manuals that can be built from the sources,

fullrefman: Printed versions of all the help pages for base and recommended packages (around 3900 pages).
refman: Printed versions of the help pages for selected base packages (around 2300 pages)
R-FAQ: R FAQ
R-intro: “An Introduction to R”.
R-data: “R Data Import/Export”.
R-admin: “R Installation and Administration”, this manual.
R-exts: “Writing R Extensions”.
R-ints: “R Internals”.
R-lang: “The R Language Definition”.

To make these (with fullrefman rather than refman), use

make pdf      to create PDF versions
make info     to create info files (not ‘refman’ nor ‘fullrefman’).

You will not be able to build any of these unless you have texi2any version 6.1 or later installed, and for PDF you must have texi2dvi and texinfo.tex installed (which are part of the GNU Texinfo distribution but are, especially texinfo.tex, often made part of the TeX package texinfo in re-distributions). The path to texi2any can be set by macro TEXI2ANY in config.site. NB: texi2any requires perl.

The PDF versions can be viewed using any recent PDF viewer: they have hyperlinks that can be followed. The info files are suitable for reading online with Emacs or the standalone GNU info program. The PDF versions will be created using the paper size selected at configuration (default ISO a4): this can be overridden by setting R_PAPERSIZE on the make command line, or setting R_PAPERSIZE in the environment and using make -e. (If re-making the manuals for a different paper size, you should first delete the file doc/manual/version.texi. The usual value for North America would be letter.)

There are some issues with making the PDF reference manual, fullrefman.pdf or refman.pdf. The help files contain both non-ASCII characters (e.g. in text.Rd) and upright quotes, neither of which are contained in the standard LaTeX Computer Modern fonts. We have provided the following alternatives:

times

(The default.) Using standard PostScript fonts, Times Roman, Helvetica and Courier. This works well both for on-screen viewing and for printing. One disadvantage is that the Usage and Examples sections may come out rather wide: this can be overcome by using in addition either of the options inconsolata (on a Unix-alike only if found by configure) or beramono, which replace the Courier monospaced font by Inconsolata or Bera Sans Mono respectively. (You will need the LaTeX package inconsolata⁴ or bera installed.)

⁴ Instructions on how to install the latest version are at https://www.ctan.org/tex-archive/fonts/inconsolata/.

Note that in most LaTeX installations this will not actually use the standard fonts for PDF, but rather embed the URW clones NimbusRom, NimbusSans and (for Courier, if used) NimbusMon.

This needs LaTeX packages times, helvetic and (if used) courier installed.

lm

Using the Latin Modern fonts. These are not often installed as part of a TeX distribution, but can obtained from https://www.ctan.org/tex-archive/fonts/ps-type1/lm/ and mirrors. This uses fonts rather similar to Computer Modern, but is not so good on-screen as times.

The default can be overridden by setting the environment variable R_RD4PDF. (On Unix-alikes, this will be picked up at install time and stored in etc/Renviron, but can still be overridden when the manuals are built, using make -e.) The usual⁵ default value for R_RD4PDF is times,inconsolata,hyper: omit inconsolata if you do not have LaTeX package inconsolata installed. hyper is always enabled (with a fallback if LaTeX package hyperref is not installed).

⁵ on a Unix-alike, inconsolata is omitted if not found by configure.

Further options, e.g for hyperref, can be included in a file Rd.cfg somewhere on your LaTeX search path. For example, if you prefer to hyperlink the text and not the page number in the table of contents use

\ifthenelse{\boolean{Rd@use@hyper}}{\hypersetup{linktoc=section}}{}

\ifthenelse{\boolean{Rd@use@hyper}}{\hypersetup{linktoc=all}}{}

to hyperlink both text and page number.

Any generated PDF manuals can be compacted by

make compact-pdf

provided qpdf and gs are available (see ?tools::compactPDF for how to specify them if not on the path).

E-book versions of most of the manuals in one or both of .epub and .mobi formats can be made by running in doc/manual one of

make ebooks
make epub
make mobi

This requires ebook-convert from Calibre, or from most Linux distributions. If necessary the path to ebook-convert can be set as make macro EBOOK by editing doc/manual/Makefile (which contains a commented value suitable for macOS) or using make -e.

2.4 Installation

To ensure that the installed tree is usable by the right group of users, set umask appropriately (perhaps to 022) before unpacking the sources and throughout the build process.

After

./configure
make
make check

(or, when building outside the source, TOP_SRCDIR/configure, etc) have been completed successfully, you can install the complete R tree to your system by typing

make install

A parallel make can be used (but run make before make install). Those using GNU make 4.0 or later may want to use make -j n -O to avoid interleaving of output.

This will install to the following directories:

prefix/bin or bindir: the front-end shell script and other scripts and executables
prefix/man/man1 or mandir/man1: the man page
prefix/LIBnn/R or libdir/R: all the rest (libraries, on-line help system, …). Here LIBnn is usually lib, but may be lib64 on some 64-bit Linux systems. This is known as the R home directory.

where prefix is determined during configuration (typically /usr/local) and can be set by running configure with the option --prefix, as in

./configure --prefix=/where/you/want/R/to/go

where the value should be an absolute path. This causes make install to install the R script to /where/you/want/R/to/go/bin, and so on. The prefix of the installation directories can be seen in the status message that is displayed at the end of configure. The installation may need to be done by the owner of prefix, often a root account.

There is the option of using make install-strip (see Debugging Symbols).

You can install into another directory tree by using

make prefix=/path/to/here install

at least with GNU make (but not some other Unix makes).

More precise control is available at configure time via options: see configure --help for details. (However, most of the ‘Fine tuning of the installation directories’ options are not used by R.)

Configure options --bindir and --mandir are supported and govern where a copy of the R script and the man page are installed.

The configure option --libdir controls where the main R files are installed: the default is eprefix/LIBnn, where eprefix is the prefix used for installing architecture-dependent files, defaults to prefix, and can be set via the configure option --exec-prefix.

Each of bindir, mandir and libdir can also be specified on the make install command line (at least for GNU make).

The configure or make variables rdocdir and rsharedir can be used to install the system-independent doc and share directories to somewhere other than libdir. The C header files can be installed to the value of rincludedir: note that as the headers are not installed into a subdirectory you probably want something like rincludedir=/usr/local/include/R-4.5.0 Under development.

If you want the R home to be something other than libdir/R, use rhome: for example

make install rhome=/usr/local/lib64/R-4.5.0 Under development

will use a version-specific R home on a non-Debian Linux 64-bit system.

If you have made R as a shared/static library you can install it in your system’s library directory by

make prefix=/path/to/here install-libR

where prefix is optional, and libdir will give more precise control.⁶ However, you should not install to a directory mentioned in LDPATHS (e.g. /usr/local/lib64) if you intend to work with multiple versions of R, since that directory may be given precedence over the lib directory of other R installations.

⁶ This will be needed if more than one sub-architecture is to be installed.

make install-strip

will install stripped executables, and on platforms where this is supported, stripped libraries in directories lib and modules and in the standard packages.

Note that installing R into a directory whose path contains spaces is not supported, and some aspects (such as installing source packages) will not work.

To install info and PDF versions of the manuals, use one or both of

make install-info
make install-pdf

Once again, it is optional to specify prefix, libdir or rhome (the PDF manuals are installed under the R home directory).

More precise control is possible. For info, the setting used is that of infodir (default prefix/info, set by configure option --infodir). The PDF files are installed into the R doc tree, set by the make variable rdocdir.

A staged installation is possible, that it is installing R into a temporary directory in order to move the installed tree to its final destination. In this case prefix (and so on) should reflect the final destination, and DESTDIR should be used: see https://www.gnu.org/prep/standards/html_node/DESTDIR.html.

You can optionally install the run-time tests that are part of make check-all by

make install-tests

which populates a tests directory in the installation.

2.5 Uninstallation

You can uninstall R by

make uninstall

optionally specifying prefix etc in the same way as specified for installation.

This will also uninstall any installed manuals. There are specific targets to uninstall info and PDF manuals in file doc/manual/Makefile.

Target uninstall-tests will uninstall any installed tests, as well as removing the directory tests containing the test results.

An installed shared/static libR can be uninstalled by

make prefix=/path/to/here uninstall-libR

2.6 Sub-architectures

Now 32-bit builds are unsupported, this section is only of historical interest, although in future the mechanisms could be used for different CPU types on the same OS (e.g. x86_64 and aarch64).

Some platforms can support closely related builds of R which can share all but the executables and dynamic objects. Examples include builds under Linux for different CPUs or 32- and 64-bit builds.

R supports the idea of architecture-specific builds, specified by adding r_arch=name to the configure line. Here name can be anything non-empty, and is used to name subdirectories of lib, etc, include and the package libs subdirectories. Example names from other software are the use of sparcv9 on Sparc Solaris and 32 by gcc on x86_64 Linux.

If you have two or more such builds you can install them over each other (and for 32/64-bit builds on one architecture, one build can be done without r_arch). The space savings can be considerable: on x86_64 Linux a basic install (without debugging symbols) took 74Mb, and adding a 32-bit build added 6Mb. If you have installed multiple builds you can select which build to run by

R --arch=name

and just running R will run the last build that was installed.

R CMD INSTALL will detect if more than one build is installed and try to install packages with the appropriate library objects for each. This will not be done if the package has an executable configure script or a src/Makefile file. In such cases you can install for extra builds by

R --arch=name CMD INSTALL --libs-only pkg1 pkg2 ...

If you want to mix sub-architectures compiled on different platforms (for example x86_64 Linux and i686 Linux), it is wise to use explicit names for each, and you may also need to set libdir to ensure that they install into the same place.

When sub-architectures are used the version of Rscript in e.g. /usr/bin will be the last installed, but architecture-specific versions will be available in e.g. /usr/lib64/R/bin/exec${R_ARCH}. Normally all installed architectures will run on the platform so the architecture of Rscript itself does not matter. The executable Rscript will run the R script, and at that time the setting of the R_ARCH environment variable determines the architecture which is run.

When running post-install tests with sub-architectures, use

R --arch=name CMD make check[-devel|all]

to select a sub-architecture to check.

Sub-architectures were also used on Windows, but by selecting executables within the appropriate bin directory such as R_HOME/bin/x64. As from R 4.2.0 only the x64 subdirectory is used.

2.7 Other Options

There are many other installation options, most of which are listed by configure --help. Almost all of those not listed elsewhere in this manual are either standard autoconf options not relevant to R or intended for specialist uses by the R developers.

One that may be useful when working on R itself is the option --disable-byte-compiled-packages, which ensures that the base and recommended packages are not byte-compiled. (Alternatively the (make or environment) variable R_NO_BASE_COMPILE can be set to a non-empty value for the duration of the build.)

Option --with-internal-tzcode makes use of R’s own code and copy of the IANA database for managing timezones. This will be preferred where there are issues with the system implementation, usually involving times after 2037 or before 1916. An alternative time-zone directory⁷ can be used, pointed to by environment variable TZDIR: this should contain files such as Europe/London. On all tested OSes the system timezone was deduced correctly, but if necessary it can be set as the value of environment variable TZ.

⁷ How to prepare such a directory is described in file src/extra/tzone/Notes in the R sources.

⁸ But on Windows problems have been seen with case-changing functions on accented Latin-1 characters.

Options --with-internal-iswxxxxx, --with-internal-towlower and --with-internal-wcwidth control the replacement of the system wide-character classification (such as iswprint), case-changing (wctrans) and width (wcwidth and wcswidth) functions by ones contained in the R sources. Replacement of the classification functions has been done for many years on macOS and AIX (and Windows): option --with-internal-iswxxxxx allows this to be suppressed on those platforms or used on others. Replacing the case-changing functions is the default on macOS and Windows. Replacement of the width functions has also been done for many years and remains the default. These options will only matter to those working with non-ASCII character data, especially in languages written in a non-Western script⁸ (which includes ‘symbols’ such as emoji). Note that one of those iswxxxxx is iswprint which is used to decide whether to output a character as a glyph or as a \U{xxxxxx} escape—for example, try "\U1f600", an emoji. The width functions are of most importance in East Asian locale: their values differ between such locales. (Replacing the system functions provides a degree of platform-independence (including to OS updates) but replaces it with a dependence on the R version.)

2.7.1 Debugging Symbols

By default, configure adds a flag (usually -g) to the compilation flags for C, Fortran and C++ sources. This will slow down compilation and increase object sizes of both R and packages, so it may be a good idea to change those flags (set CFLAGS etc in config.site before configuring, or edit files Makeconf and etc/Makeconf between running configure and make).

Having debugging symbols available is useful both when running R under a debugger (e.g., R -d gdb) and when using sanitizers and valgrind, all things intended for experts.

Debugging symbols (and some others) can be ‘stripped’ on installation by using

make install-strip

How well this is supported depends on the platform: it works best on those using GNU binutils. On x86_64 Linux a typical reduction in overall size was from 92MB to 66MB. On macOS debugging symbols are not by default included in .dylib and .so files, so there is negligible difference.

2.7.2 OpenMP Support

By default configure searches for suitable flags⁹ for OpenMP support for the C, C++ (default standard) and Fortran compilers.

⁹ for example, -fopenmp, -fiopenmp, -xopenmp or -qopenmp. This includes for clang and the Intel and Oracle compilers.

Only the C result is currently used for R itself, and only if MAIN_LD/DYLIB_LD were not specified. This can be overridden by specifying

R_OPENMP_CFLAGS

Use for packages has similar restrictions (involving SHLIB_LD and similar: note that as Fortran code is by default linked by the C (or C++) compiler, both need to support OpenMP) and can be overridden by specifying some of

SHLIB_OPENMP_CFLAGS
SHLIB_OPENMP_CXXFLAGS
SHLIB_OPENMP_FFLAGS

Setting these to an empty value will disable OpenMP for that compiler (and configuring with --disable-openmp will disable all detection¹⁰ of OpenMP). The configure detection test is to compile and link a standalone OpenMP program, which is not the same as compiling a shared object and loading it into the C program of R’s executable. Note that overridden values are not tested.

¹⁰ This does not necessarily disable use of OpenMP – the configure code allows for platforms where OpenMP is used without a flag. For the flang compiler in late 2017, the Fortran runtime always used OpenMP.

2.7.3 C++ Support

C++ is not used by R itself, but support is provided for installing packages with C++ code via make macros defined in file etc/Makeconf (and with explanations in file config.site):

CXX
CXXFLAGS
CXXPICFLAGS
CXXSTD

CXX11
CXX11STD
CXX11FLAGS
CXX11PICFLAGS

CXX14
CXX14STD
CXX14FLAGS
CXX14PICFLAGS

CXX17
CXX17STD
CXX17FLAGS
CXX17PICFLAGS

CXX20
CXX20STD
CXX20FLAGS
CXX20PICFLAGS

CXX23
CXX23STD
CXX23FLAGS
CXX23PICFLAGS

The macros CXX etc are those used by default for C++ code. configure will attempt to set the rest suitably, choosing for CXXSTD and CXX11STD a suitable flag such as -std=gnu++17 for C++17 support (which is required if C++ is to be supported by default). Inferred values can be overridden in file config.site or on the configure command line: user-supplied values will be tested by compiling some C++11/14/17/20/23 code.

It may be that there is no suitable flag for C++14/17/20/23 support with the default compiler, in which case a different compiler could be selected for CXX14/CXX17/CXX20/CXX23 with its corresponding flags.

If no suitable compiler/flag is found for the default C++ compiler, one can be set in file config.site via macros CXX and CXXSTD. A user-specified compiler does not need to pass the C++17 tests, so do this at your own risk as some packages may not compile.

The -std flag is supported by the GCC, clang++ and Intel compilers. Currently accepted values are (plus some synonyms)

g++:     c++11 gnu+11 c++14 gnu++14 c++17 gnu++17 c++2a gnu++2a (from 8)
         c++20 gnu++20 (from 10) c++23 gnu++23 c++2b gnu++2b (from 11)
Intel:   c++11  gnu+11 c++14 gnu++14 c++17 gnu++17
         c++20 gnu++20 (from 2021.1) c++2b gnu++2b (from 2022.2)
         c++23 gnu++23 (at least from 2024.0)

(Those for LLVM clang++ are documented at https://clang.llvm.org/cxx_status.html, and follow g++: -std=c++20 is supported from Clang 10, -std=c++2b from Clang 13 and -std=c++23 from Clang 17. Apple Clang supports -std=c++2b from 13.1.6 and -std=c++23 from 16.0.0.)

‘Standards’ for g++ starting with gnu enable ‘GNU extensions’: what those are is hard to track down.

For the use of C++ in R packages, see Writing R Extensions. Prior to R 3.6.0 the default C++ standard was that of the compiler used: currently it is C++17.

https://en.cppreference.com/w/cpp/compiler_support indicates which versions of common compilers support (parts of) which C++ standards. GCC introduced C++17 support gradually, but version 7 should suffice.

2.7.4 C standards

Compiling R requires C99 or later: C11 and C17 are minor updates, but the substantial update planned for ‘C23’ (now expected ca April 2024) will also be supported.

As from R 4.3.0 there is support for packages to indicate their preferred C version. Macros CC17, C17FLAGS, CC23 and C23FLAGS can be set in config.site (there are examples there). Those for C17 should support C17 or earlier and not allow C23 additions so for example bool, true and false can be used as identifiers. Those for C23 should support new types such as bool.

Some compilers warn enthusiastically about prototypes. For most, omitting -Wstrict-prototypes in C17FLAGS suffices. However, versions 15 and later of LLVM clang and 14.0.3 and later of Apple clang warn by default in all modes if -Wall or -pedantic is used, and may need -Wno-strict-prototypes.

2.7.5 Link-Time Optimization

There is support for using link-time optimization (LTO) if the toolchain supports it: configure with flag --enable-lto. When LTO is enabled it is used for compiled code in add-on packages unless the flag --enable-lto=R is used¹¹.

¹¹ Then recommended packages installed as part of the R installation do use LTO, but not packages installed later.

¹² A complete CRAN installation reduced from 50 to 35GB.

The main benefit seen to date from LTO has been detecting long-standing bugs in the ways packages pass arguments to compiled code and between compilation units. Benchmarking in 2020 with gcc/gfortran 10 showed gains of a few percent in increased performance and reduction in installed size for builds without debug symbols, but large size reductions for some packages¹² with debug symbols. (Performance and size gains are said to be most often seen in complex C++ builds.)

Whether toolchains support LTO is often unclear: all of the C compiler, the Fortran compiler¹³ and linker have to support it, and support it by the same mechanism (so mixing compiler families may not work and a non-default linker may be needed). It has been supported by the GCC and LLVM projects for some years with diverging implementations.

¹³ although there is the possibility to exclude Fortran but that misses some of the benefits.

LTO support was added in 2011 for GCC 4.5 on Linux but was little used before 2019: compiler support has steadily improved over those years and --enable-lto=R is nowadays used for some routine CRAN checking.

Unfortunately --enable-lto may be accepted but silently do nothing useful if some of the toolchain does not support LTO: this is less common than it once was.

Various macros can be set in file config.site to customize how LTO is used. If the Fortran compiler is not of the same family as the C/C++ compilers, set macro LTO_FC (probably to empty). Macro LTO_LD can be used to select an alternative linker should that be needed.

2.7.6 LTO with GCC

This has been tested on Linux with gcc/gfortran 8 and later: that needed setting (e.g. in config.site)

AR=gcc-ar
RANLIB=gcc-ranlib

For non-system compilers or if those wrappers have not been installed one may need something like

AR="ar --plugin=/path/to/liblto_plugin.so"
RANLIB="ranlib --plugin=/path/to/liblto_plugin.so"

and NM may be needed to be set analogously. (If using an LTO-enabled build to check packages, set environment variable UserNM¹⁴ to gcc-nm.)

¹⁴ not NM as we found make overriding that.

With GCC 5 and later it is possible to parallelize parts of the LTO linking process: set the make macro LTO to something like LTO=-flto=8 (to use 8 threads), for example in file config.site.

Under some circumstances and for a few packages, the PIC flags have needed overriding on Linux with GCC 9: e.g use in config.site:

CPICFLAGS=-fPIC
CXXPICFLAGS=-fPIC
CXX11PICFLAGS=-fPIC
CXX14PICFLAGS=-fPIC
CXX17PICFLAGS=-fPIC
CXX20PICFLAGS=-fPIC
FPICFLAGS=-fPIC

We suggest only using these if the problem is encountered (it had not been seen on CRAN with GCC 10–14 at the time of writing).

Note that R may need to be re-compiled after even a minor update to the compiler (e.g. from 13.1 to 13.2).

2.7.7 LTO with LLVM

LLVM supports another type of LTO called ‘Thin LTO’ as well as a similar implementation to GCC, sometimes called ‘Full LTO’. (See https://clang.llvm.org/docs/ThinLTO.html.) Currently the LLVM compilers relevant to R are clang and flang for which this can be selected by setting macro LTO=-flto=thin. LLVM has

AR=llvm-ar
RANLIB=llvm-ranlib

(but macOS does not, and these are not needed there). Where the linker supports a parallel backend for Thin LTO this can be specified via the macro LTO_LD: see the URL above for per-linker settings and further linking optimizations.)

For example, on macOS one might use

LTO=-flto=thin
LTO_FC=
LTO_LD=-Wl,-mllvm,-threads=4

to use Thin LTO with 4 threads for C/C++ code, but skip LTO for Fortran code compiled with gfortran.

It is said to be particularly beneficial to use -O3 for clang in conjunction with LTO.

It seems that flang may support LTO, but with no documentation as yet.

The 2020s versions of Intel’s C/C++ compilers are based on LLVM and as such support LLVM-style LTO, both ‘full’ and ‘thin’. This might use something like

LTO=-flto=thin -flto-jobs=8

2.7.8 LTO for package checking

LTO effectively compiles all the source code in a package as a single compilation unit and so allows the compiler (with sufficient diagnostic flags such as -Wall) to check consistency between what are normally separate compilation units.

With gcc/gfortran 9.x and later¹⁵ LTO will flag inconsistencies in calls to Fortran subroutines/functions, both between Fortran source files and between Fortran and C/C++. gfortran 8.4, 9.2 and later can help understanding these by extracting C prototypes from Fortran source files with option -fc-prototypes-external, e.g. that (at the time of writing) Fortran LOGICAL corresponds to int_least32_t * in C.

¹⁵ probably also 8.4 and later.

2.8 Testing an Installation

Full post-installation testing is possible only if the test files have been installed with

make install-tests

which populates a tests directory in the installation.

If this has been done, two testing routes are available. The first is to move to the home directory of the R installation (as given by R RHOME or from R as R.home()) and run

cd tests
## followed by one of
../bin/R CMD make check
../bin/R CMD make check-devel
../bin/R CMD make check-all

and other useful targets are test-BasePackages and test-Recommended to run tests of the standard and recommended packages (if installed) respectively.

This re-runs all the tests relevant to the installed R (including for example the code in the package vignettes), but not for example the ones checking the example code in the manuals nor making the standalone Rmath library. This can occasionally be useful when the operating environment has been changed, for example by OS updates or by substituting the BLAS (see Shared BLAS).

Parallel checking of packages may be possible: set the environment variable TEST_MC_CORES to the maximum number of processes to be run in parallel. This affects both checking the package examples (part of make check) and package sources (part of make check-devel and make check-recommended). It does require a make command which supports the make -j n option: most do.

Alternatively, the installed R can be run, preferably with --vanilla. Then

pdf("tests.pdf") ## optional, but prevents flashing graphics windows
Sys.setenv(LC_COLLATE = "C", LC_TIME = "C", LANGUAGE = "en")
tools::testInstalledBasic("both")
tools::testInstalledPackages(scope = "base")
tools::testInstalledPackages(scope = "recommended")

runs the basic tests and then all the tests on the standard and recommended packages. These tests can be run from anywhere: the basic tests write their results in the tests folder of the R home directory and run fewer tests than the first approach: in particular they do not test things which need Internet access—that can be tested by

tools::testInstalledBasic("internet")

It is possible to test the installed packages (but not their package-specific tests) by testInstalledPackages even if make install-tests was not run. The outputs are written under the current directory unless a different one is specified by outDir.

Note that the results may depend on the language set for times and messages: for maximal similarity to reference results you may want to try setting (before starting the R session)

LANGUAGE=en

and use a UTF-8 or Latin-1 locale.

Footnotes