R Installation and Administration ¶

1.1 Getting and unpacking the sources ¶

The simplest way is to download the most recent R-x.y.z.tar.gz file, and unpack it with

tar -xf R-x.y.z.tar.gz

on systems that have a suitable¹ tar installed. On other systems you need to have the gzip program installed, when you can use

gzip -dc R-x.y.z.tar.gz | tar -xf -

The pathname of the directory into which the sources are unpacked should not contain spaces, as most make programs (and specifically GNU make) do not expect spaces.

If you want the build to be usable by a group of users, set umask before unpacking so that the files will be readable by the target group (e.g., umask 022 to be usable by all users). Keep this setting of umask whilst building and installing.

If you use a fairly recent GNU version of tar and do this as a root account (which on Windows includes accounts with administrator privileges) you may see many warnings about changing ownership. In which case you can use

tar --no-same-owner -xf R-x.y.z.tar.gz

and perhaps also include the option --no-same-permissions. (These options can also be set in the TAR_OPTIONS environment variable: if more than one option is included they should be separated by spaces.)

1.2 Getting patched and development versions ¶

A patched version of the current release, ‘r-patched’, and the current development version, ‘r-devel’, are available as daily tarballs and via access to the R Subversion repository. (For the two weeks prior to the release of a minor (4.x.0) version, ‘r-patched’ tarballs may refer to beta/release candidates of the upcoming release, the patched version of the current release being available via Subversion.)

The tarballs are available from https://cran.r-project.org/src/base-prerelease. Download R-patched.tar.gz or R-devel.tar.gz (or the .tar.bz2 versions) and unpack as described in the previous section. They are built in exactly the same way and on the same platform as distributions of R releases. Notice, that you probably want to use the CRAN master site for this, due to propagation delays. An alternative source of daily snapshots is maintained at https://stat.ethz.ch/R/daily/.

• Using Subversion and rsync

svn checkout https://svn.r-project.org/R/trunk/ path

wget -r -l1 --no-parent -A\*.gz -nd -P src/library/Recommended \
  https://CRAN.R-project.org/src/contrib/dir
./tools/link-recommended

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

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

or

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

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

‘refman’

Printed versions of the help pages for selected base packages (around 2200 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-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 5.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 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.)

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

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}}{}

or

\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.4.2.

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

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.

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.

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

• Debugging Symbols
• OpenMP Support
• C++ Support
• C standards
• Link-Time Optimization

make install-strip

R_OPENMP_CFLAGS

SHLIB_OPENMP_CFLAGS
SHLIB_OPENMP_CXXFLAGS
SHLIB_OPENMP_FFLAGS

CXX
CXXFLAGS
CXXPICFLAGS
CXXSTD

CXX11
CXX11STD
CXX11FLAGS
CXX11PICFLAGS

CXX14
CXX14STD
CXX14FLAGS
CXX14PICFLAGS

CXX17
CXX17STD
CXX17FLAGS
CXX17PICFLAGS

CXX20
CXX20STD
CXX20FLAGS
CXX20PICFLAGS

CXX23
CXX23STD
CXX23FLAGS
CXX23PICFLAGS

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)

AR=gcc-ar
RANLIB=gcc-ranlib

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

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

AR=llvm-ar
RANLIB=llvm-ranlib

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

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

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.

3.1 Building from source ¶

It is possible to use other 64-bit toolchains (including ‘MSYS2’) with UCRT support to build R, but this manual only documents that used for recent binary distributions of R. When using other toolchains, makefiles of R and packages may need to be adapted.

• The Windows toolset
• LaTeX

3.2 Checking the build ¶

You can test a build by running

make check

The recommended packages can be checked by

make check-recommended

Other levels of checking are

make check-devel

for a more thorough check of the R functionality, and

make check-all

for both check-devel and check-recommended.

If a test fails, there will almost always be a .Rout.fail file in the directory being checked (often tests/Examples or tests): examine the file to help pinpoint the problem.

Parallel checking of package sources (part of make check-devel and make check-recommended) is possible: see the environment variable TEST_MC_CORES to the maximum number of processes to be run in parallel.

3.3 Testing an Installation ¶

The Windows installer contains a set of test files used when building R.

The toolset is not needed to run these tests, but more comprehensive analysis of errors will be given if diff is in the path.

Launch either Rgui or Rterm (preferred), preferably with --vanilla. Then run

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: testInstalledBasic writes results in the tests folder of the R home directory (as given by R.home()) and testInstalledPackages under the current directory unless a different one is specified by outDir.

For the tests folder to be writeable, one normally needs to install R to a directory other than the default C:\Program Files. The installer also allows to install R without Administrator privileges, see the R Windows FAQ for more details.

The results of example(md5sums) when testing tools may differ from the reference output as some files are installed with Windows’ CRLF line endings. Also, expect differences in reg-plot-latin1.pdf.

One can also run tests from the toolset shell (e.g. bash) similarly to a Unix-like installation. 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

Remember that LaTeX needs to be on the path.

4.1 Running R under macOS ¶

There are two ways to run R on macOS from a CRAN binary distribution.

There is a GUI console normally installed with the R icon in /Applications which you can run by double-clicking (e.g. from Launchpad or Finder). (If you cannot find it there it was possibly installed elsewhere so try searching for it in Spotlight.) This is usually referred to as R.APP to distinguish it from command-line R: its user manual is currently part of the macOS FAQ at https://cran.r-project.org/bin/macosx/RMacOSX-FAQ.html and can be viewed from R.APP’s ‘Help’ menu.

You can run command-line R and Rscript from a Terminal²⁰ so these can be typed as commands as on any other Unix-alike: see the next chapter of this manual. There are some small differences which may surprise users of R on other platforms, notably the default location of the personal library directory (under ~/Library/R, e.g. ~/Library/R/arm64/4.4/library), and that warnings, messages and other output to stderr are highlighted in bold.

Those using the zsh shell (the default for new user accounts) might find the command R being masked by the zsh builtin r (which recalls commands). One can use a full path to R in an alias, or add disable r to ~/.zshrc.

It has been reported that running R.APP may fail if no preferences are stored, so if it fails when launched for the very first time, try it again (the first attempt will store some preferences).

Users of R.APP need to be aware of the ‘App Nap’ feature (https://developer.apple.com/library/archive/releasenotes/MacOSX/WhatsNewInOSX/Articles/MacOSX10_9.html) which can cause R tasks to appear to run very slowly when not producing output in the console. Here are ways to avoid it:

• Ensure that the console is completely visible (or at least the activity indicator at the top right corner is visible).
• In a Terminal, run

  defaults write org.R-project.R NSAppSleepDisabled -bool YES
  

  (see https://developer.apple.com/library/archive/releasenotes/MacOSX/WhatsNewInOSX/Articles/MacOSX10_9.html).

Using the X11 graphics device or the X11-based versions of View() and edit() for data frames and matrices (the latter are the default for command-line R but not R.APP) requires XQuartz to be installed.

Under some rather nebulous circumstances messages have been seen from fontconfig about missing/unreadable configuration files when using cairo-based devices, especially X11(type = "cairo"). With XQuartz installed there are two fontconfig areas from different versions and it can help to set

setenv FONTCONFIG_PATH /opt/X11/lib/X11/fontconfig

Another symptom has been that italic/oblique fonts are replaced by upright ones.

4.2 Uninstalling under macOS ¶

R for macOS consists of two parts: the GUI (R.APP) and the R framework. Un-installation is as simple as removing those folders (e.g. by dragging them onto the Bin²¹). The typical installation will install the GUI into the /Applications/R.app folder and the R framework into the /Library/Frameworks/R.framework folder. The links to R and Rscript in /usr/local/bin should also be removed.

If you want to get rid of R more completely using a Terminal, simply run:

sudo rm -Rf /Library/Frameworks/R.framework /Applications/R.app \
   /usr/local/bin/R /usr/local/bin/Rscript

The installation consists of up to four Apple packages:²² for the ‘Apple Silicon’ build, org.R-project.arm64.R.fw.pkg, org.R-project.arm64.R.GUI.pkg, org.r-project.arm64.tcltk and org.r-project.arm64.texinfo. You can use sudo pkgutil --forget if you want the Apple Installer to forget about the package without deleting its files (useful for the R framework when installing multiple R versions in parallel), or after you have deleted the files. NB: the package names are case-sensitive and the R domain is named inconsistently.

Uninstalling the Tcl/Tk and Texinfo components (which are installed under /opt/R/arm64 on a ‘arm64’ build and /opt/R/x86_64 for an ‘x86_64’ one) is not as simple. You can list the files they installed in a Terminal by e.g.

pkgutil --files org.r-project.arm64.tcltk
pkgutil --files org.r-project.arm64.texinfo

(For the ‘Intel build, replace arm64 by x86_64.) These are paths relative to /, the root of the file system.

If you are not compiling R nor installing packages from source you could remove all of /opt/R/arm64 or /opt/R/x86_64.

4.3 Multiple versions ¶

The installer will remove any previous version²³ of the R framework which it finds installed. This can be avoided by using pkgutil --forget (see the previous section). However, note that different versions are installed under /Library/Frameworks/R.framework/Versions as 4.4-arm64 (or 4.4-x86_64), 4.3 and so on, so it is not possible to have different ‘4.x.y’ versions installed for the same ‘x’ and CPU type.

R.APP will always run the ‘current’ version of R, that is the last installed version.

6.1 Default packages ¶

The set of packages loaded on startup is by default

> getOption("defaultPackages")
[1] "datasets"  "utils"     "grDevices" "graphics"  "stats"     "methods"

(plus, of course, base) and this can be changed by setting the option in startup code (e.g. in ~/.Rprofile). It is initially set to the value of the environment variable R_DEFAULT_PACKAGES if set (as a comma-separated list). Setting R_DEFAULT_PACKAGES=NULL ensures that only package base is loaded.

Changing the set of default packages is normally used to reduce the set for speed when scripting: in particular not using methods will reduce the start-up time by a factor of up to two. But it can also be used to customize R, e.g. for class use. Rscript also checks the environment variable R_SCRIPT_DEFAULT_PACKAGES; if set, this takes precedence over R_DEFAULT_PACKAGES.

6.2 Managing libraries ¶

R packages are installed into libraries, which are directories in the file system containing a subdirectory for each package installed there.

R comes with a single library, R_HOME/library which is the value of the R object ‘.Library’ containing the standard and recommended²⁶ packages. Both sites and users can create others and make use of them (or not) in an R session. At the lowest level ‘.libPaths()’ can be used to add paths to the collection of libraries or to report the current collection.

R will automatically make use of a site-specific library R_HOME/site-library if this exists (it does not in a vanilla R installation). This location can be overridden by setting²⁷ ‘.Library.site’ in R_HOME/etc/Rprofile.site, or (not recommended) by setting the environment variable R_LIBS_SITE.

Users can have one or more libraries, normally specified by the environment variable R_LIBS_USER. This has a default value (to see it, use ‘Sys.getenv("R_LIBS_USER")’ within an R session), but that is only used if the corresponding directory actually exists (which by default it will not).

Both R_LIBS_USER and R_LIBS_SITE can specify multiple library paths, separated by colons (semicolons on Windows).

6.3 Installing packages ¶

Packages may be distributed in source form or compiled binary form. Installing source packages which contain C/C++/Fortran code requires that compilers and related tools be installed. Binary packages are platform-specific and generally need no special tools to install, but see the documentation for your platform for details.

Note that you may need to specify implicitly or explicitly the library to which the package is to be installed. This is only an issue if you have more than one library, of course.

Ensure that the environment variable TMPDIR is either unset (and /tmp exists and can be written in and executed from) or is the absolute path to a valid temporary directory, not containing spaces.

For most users it suffices to call ‘install.packages(pkgname)’ or its GUI equivalent if the intention is to install a CRAN package and internet access is available.²⁸ On most systems ‘install.packages()’ will allow packages to be selected from a list box (typically with thousands of items).

To install packages from source on a Unix-alike use in a terminal

R CMD INSTALL -l /path/to/library pkg1 pkg2 ...

The part ‘-l /path/to/library’ can be omitted, in which case the first library of a normal R session is used (that shown by .libPaths()[1]).

There are a number of options available: use R CMD INSTALL --help to see the current list.

Alternatively, packages can be downloaded and installed from within R. First choose your nearest CRAN mirror using chooseCRANmirror(). Then download and install packages pkg1 and pkg2 by

> install.packages(c("pkg1", "pkg2"))

The essential dependencies of the specified packages will also be fetched. Unless the library is specified (argument lib) the first library in the library search path is used: if this is not writable, R will ask the user (in an interactive session) if the default personal library should be created, and if allowed to will install the packages there.

If you want to fetch a package and all those it depends on (in any way) that are not already installed, use e.g.

> install.packages("Rcmdr", dependencies = TRUE)

install.packages can install a source package from a local .tar.gz file (or a URL to such a file) by setting argument repos to NULL: this will be selected automatically if the name given is a single .tar.gz file.

install.packages can look in several repositories, specified as a character vector by the argument repos: these can include a CRAN mirror, Bioconductor, R-forge, rforge.net, local archives, local files, …). Function setRepositories() can select amongst those repositories that the R installation is aware of.

Something which sometimes puzzles users is that install.packages() may report that a package which they believe should be available is not found. Some possible reasons:

• The package, such as grid or tcltk, is part of R itself and not otherwise available.
• The package is not in the available repositories, so check which have been selected by

  getOption("repos")
  

• The package is available, but not for the current version of R or for the type of OS (Unix/Windows). To retrieve the information on available versions of package pkg, use

  av <- available.packages(filters=list())
  av[av[, "Package"] == pkg, ]
  

  in your R session, and look at the ‘Depends’ and ‘OS_type’ fields (there may be more than one matching entry). If the package depends on a version of R later than the one in use, it is possible that an earlier version is available which will work with your version of R: for CRAN look for ‘Old sources’ on the package’s CRAN landing page and manually retrieve an appropriate version (of comparable age to your version of R).

Naive users sometimes forget that as well as installing a package, they have to use library to make its functionality available.

• Windows
• macOS
• Customizing package compilation
• Multiple sub-architectures
• Byte-compilation
• External software

FLIBS = -L/Library/Frameworks/R.framework/Resources/lib -lgfortran -lquadmath

SDK=/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk
CC = /usr/local/clang/bin/clang -isysroot $(SDK)
CXX = /usr/local/clang/bin/clang++ -isysroot $(SDK)
CXX11 = $CXX
CXX14 = $CXX
CXX17 = $CXX
CXX20 = $CXX
CXX23 = $CXX
CFLAGS = -g -O2 -Wall -pedantic -Wconversion -Wno-sign-conversion
CXXFLAGS = -g -O2 -Wall -pedantic -Wconversion -Wno-sign-conversion
CXX11FLAGS = $CXXFLAGS
CXX14FLAGS = $CXXFLAGS
CXX17FLAGS = $CXXFLAGS
CXX20FLAGS = $CXXFLAGS
CXX23FLAGS = $CXXFLAGS

FC = /opt/gfortran/bin/gfortran
(arm64)
FLIBS =  -L/opt/gfortran/lib/gcc/aarch64-apple-darwin20.0/12.2.0
  -L/opt/gfortran/lib -lgfortran -lemutls_w -lquadmath
(Intel)
FLIBS =  -L/opt/gfortran/lib/gcc/x86_64-apple-darwin20.0/12.2.0
  -L/opt/gfortran/lib -lgfortran -lquadmath

SHLIB_OPENMP_CFLAGS = -fopenmp
SHLIB_OPENMP_CXXFLAGS = -fopenmp

./configure CC=clang CFLAGS=-O2 CXX=clang++ CXXFLAGS=-O2

## for C code
CFLAGS = -g -O -mtune=native
## for C++ code
CXXFLAGS = -g -O -mtune=native
## for C++11 code
CXX11FLAGS = -g -O -mtune=native
## for fixed-form Fortran code
FFLAGS = -g -O -mtune=native
## for C17 code
C17FLAGS = -g -O -mtune=native -Wno-strict-prototypes

FC = /opt/gfortran/bin/gfortran
(arm64)
FLIBS =  -L/opt/gfortran/lib/gcc/aarch64-apple-darwin20.0/12.2.0
  -L/opt/gfortran/lib -lgfortran -lemutls_w -lquadmath
(Intel)
FLIBS =  -L/opt/gfortran/lib/gcc/x86_64-apple-darwin20.0/12.2.0
  -L/opt/gfortran/lib -lgfortran -lquadmath

R CMD INSTALL --libs-only pkg

export R_LD_LIBRARY_PATH="`R RHOME`/lib:/opt/local/lib"

6.4 Updating packages ¶

The command update.packages() is the simplest way to ensure that all the packages on your system are up to date. It downloads the list of available packages and their current versions, compares it with those installed and offers to fetch and install any that have later versions on the repositories.

An alternative interface to keeping packages up-to-date is provided by the command packageStatus(), which returns an object with information on all installed packages and packages available at multiple repositories. The print and summary methods give an overview of installed and available packages, the upgrade method offers to fetch and install the latest versions of outdated packages.

One sometimes-useful additional piece of information that packageStatus() returns is the status of a package, as "ok", "upgrade" or "unavailable" (in the currently selected repositories). For example

> inst <- packageStatus()$inst
> inst[inst$Status != "ok", c("Package", "Version", "Status")]
                  Package Version      Status
Biobase           Biobase   2.8.0 unavailable
RCurl               RCurl   1.4-2     upgrade
Rgraphviz       Rgraphviz  1.26.0 unavailable
rgdal               rgdal  0.6-27     upgrade

6.5 Removing packages ¶

Packages can be removed in a number of ways. From a command prompt they can be removed by

R CMD REMOVE -l /path/to/library pkg1 pkg2 ...

From a running R process they can be removed by

> remove.packages(c("pkg1", "pkg2"),
                  lib = file.path("path", "to", "library"))

Finally, one can just remove the package directory from the library.

6.6 Setting up a package repository ¶

Utilities such as install.packages can be pointed at any CRAN-style repository, and R users may want to set up their own. The ‘base’ of a repository is a URL such as https://www.stats.ox.ac.uk/pub/RWin/: this must be an URL scheme that download.packages supports (which also includes ‘https://’, ‘ftp://’ and ‘file://’). Under that base URL there should be directory trees for one or more of the following types of package distributions:

• "source": located at src/contrib and containing .tar.gz files. Other forms of compression can be used, e.g. .tar.bz2 or .tar.xz files. Complete repositories contain the sources corresponding to any binary packages, and in any case it is wise to have a src/contrib area with a possibly empty PACKAGES file.
• "win.binary": located at bin/windows/contrib/x.y for R versions x.y.z and containing .zip files for Windows.
• "mac.binary": located at bin/macosx/big-sur-arm64/contrib/4.y or bin/macosx/big-sur-x86_64/contrib/4.y for the CRAN builds for macOS for R versions 4.y.z, containing .tgz files. (bin/macosx/contrib/4.y for y = 0, 1 or 2.)

Each terminal directory must also contain a PACKAGES file. This can be a concatenation of the DESCRIPTION files of the packages separated by blank lines, but only a few of the fields are needed. The simplest way to set up such a file is to use function write_PACKAGES in the tools package, and its help explains which fields are needed. Optionally there can also be PACKAGES.rds and PACKAGES.gz files, downloaded in preference to PACKAGES. (If you have a mis-configured server that does not report correctly non-existent files you may need these files.)

To add your repository to the list offered by setRepositories(), see the help file for that function.

Incomplete repositories are better specified via a contriburl argument than via being set as a repository.

A repository can contain subdirectories, when the descriptions in the PACKAGES file of packages in subdirectories must include a line of the form

Path: path/to/subdirectory

—once again write_PACKAGES is the simplest way to set this up.

6.7 Checking installed source packages ¶

It can be convenient to run R CMD check on an installed package, particularly on a platform which uses sub-architectures. The outline of how to do this is, with the source package in directory pkg (or a tarball filename):

R CMD INSTALL -l libdir pkg > pkg.log 2>&1
R CMD check -l libdir --install=check:pkg.log pkg

Where sub-architectures are in use the R CMD check line can be repeated with additional architectures by

R --arch arch CMD check -l libdir --extra-arch --install=check:pkg.log pkg

where --extra-arch selects only those checks which depend on the installed code and not those which analyse the sources. (If multiple sub-architectures fail only because they need different settings, e.g. environment variables, --no-multiarch may need to be added to the INSTALL lines.) On Unix-alikes the architecture to run is selected by --arch: this can also be used on Windows with R_HOME/bin/R.exe, but it is more usual to select the path to the Rcmd.exe of the desired architecture.

So on Windows to install, check and package for distribution a source package from a tarball which has been tested on another platform one might use

.../bin/x64/Rcmd INSTALL -l libdir tarball --build > pkg.log 2>&1

7.1 Locales ¶

A locale is a description of the local environment of the user, including the preferred language, the encoding of characters, the currency used and its conventions, and so on. Aspects of the locale are accessed by the R functions Sys.getlocale and Sys.localeconv.

The system of naming locales is OS-specific. There is quite wide agreement on schemes, but not on the details of their implementation. A locale needs to specify

• A human language. These are generally specified by a lower-case two-character abbreviation following ISO 639 (see e.g. https://en.wikipedia.org/wiki/ISO_639-1).
• A ‘territory’, used mainly to specify the currency. These are generally specified by an upper-case two-character abbreviation following ISO 3166 (see e.g. https://en.wikipedia.org/wiki/ISO_3166).
• A charset encoding, which determines both how a byte stream should be divided into characters, and which characters the subsequences of bytes represent. Sometimes the combination of language and territory is used to specify the encoding, for example to distinguish between traditional and simplified Chinese.
• Optionally, a modifier, for example to indicate that Austria is to be considered pre- or post-Euro. The modifier is also used to indicate the script (@latin, @cyrillic for Serbian, @iqtelif) or language dialect (e.g. @saaho, a dialect of Afar, and @bokmal and @nynorsk, dialects of Norwegian regarded by some OSes as separate languages, no and nn).

R is principally concerned with the first (for translations) and third. Note that the charset may be deducible from the language, as some OSes offer only one charset per language.

• Locales under Unix-alikes
• Locales under Windows
• Locales under macOS

7.2 Localization of messages ¶

The preferred language for messages is by default taken from the locale. This can be overridden first by the setting of the environment variable LANGUAGE and then³⁴ by the environment variables LC_ALL, LC_MESSAGES and LANG. (The last three are normally used to set the locale and so should not be needed, but the first is only used to select the language for messages.) The code tries hard to map locales to languages, but on some systems (notably Windows) the locale names needed for the environment variable LC_ALL do not all correspond to XPG language names and so LANGUAGE may need to be set. (One example is ‘LC_ALL=es’ on Windows which sets the locale to Estonian and the language to Spanish.)

It is usually possible to change the language once R is running via (not Windows) Sys.setlocale("LC_MESSAGES", "new_locale"), or by setting an environment variable such as LANGUAGE, provided³⁵ the language you are changing to can be output in the current character set. But this is OS-specific, and has been known to stop working on an OS upgrade. Note that translated messages may be cached, so attempting to change the language of an error that has already been output in another language may not work.

Messages are divided into domains, and translations may be available for some or all messages in a domain. R makes use of the following domains.

• Domain R for the C-level error and warning messages from the R interpreter.
• Domain R-pkg for the R stop, warning and message messages in each package, including R-base for the base package.
• Domain pkg for the C-level messages in each package.
• Domain RGui for the menus etc of the R for Windows GUI front-end.

Dividing up the messages in this way allows R to be extensible: as packages are loaded, their message translation catalogues can be loaded too.

R can be built without support for translations, but it is enabled by default.

R-level and C-level domains are subtly different, for example in the way strings are canonicalized before being passed for translation.

Translations are looked for by domain according to the currently specified language, as specifically as possible, so for example an Austrian (‘de_AT’) translation catalogue will be used in preference to a generic German one (‘de’) for an Austrian user. However, if a specific translation catalogue exists but does not contain a translation, the less specific catalogues are consulted. For example, R has catalogues for ‘en_GB’ that translate the Americanisms (e.g., ‘gray’) in the standard messages into English.³⁶ Two other examples: there are catalogues for ‘es’, which is Spanish as written in Spain and these will by default also be used in Spanish-speaking Latin American countries, and also for ‘pt_BR’, which are used for Brazilian locales but not for locales specifying Portugal.

Translations in the right language but the wrong charset are made use of by on-the-fly re-encoding. The LANGUAGE variable (only) can be a colon-separated list, for example ‘se:de’, giving a set of languages in decreasing order of preference. One special value is ‘en@quot’, which can be used in a UTF-8 locale to have American error messages with pairs of single quotes translated to Unicode directional quotes.

If no suitable translation catalogue is found or a particular message is not translated in any suitable catalogue, ‘English’³⁷ is used.

See https://developer.r-project.org/Translations30.html for how to prepare and install translation catalogues.

9.1 Unix-alikes ¶

If R has not already been made in the directory tree, configure must be run as described in the main build instructions.

Then (in src/nmath/standalone)

make

will make standalone libraries libRmath.a and libRmath.so (libRmath.dylib on macOS): ‘make static’ and ‘make shared’ will create just one of them.

To use the routines in your own C or C++ programs, include

#define MATHLIB_STANDALONE
#include <Rmath.h>

and link against ‘-lRmath’ (and ‘-lm’ if needed on your OS). The example file test.c does nothing useful, but is provided to test the process (via make test). Note that you will probably not be able to run it unless you add the directory containing libRmath.so to the LD_LIBRARY_PATH environment variable (libRmath.dylib, DYLD_FALLBACK_LIBRARY_PATH on macOS).

The targets

make install
make uninstall

will (un)install the header Rmath.h and shared and static libraries (if built). Both prefix= and DESTDIR are supported, together with more precise control as described for the main build.

‘make install’ installs a file for pkg-config to use by e.g.

$(CC) `pkg-config --cflags libRmath` -c test.c
$(CC) `pkg-config --libs libRmath` test.o -o test

On some systems ‘make install-strip’ will install a stripped shared library.

9.2 Windows ¶

You need to set up³⁹ almost all the tools to make R and then run (in a Unix-like shell)

(cd ../../gnuwin32; make MkRules)
(cd ../../include; make -f Makefile.win config.h Rconfig.h Rmath.h)
make -f Makefile.win

Alternatively, in a cmd.exe shell use

cd ../../include
make -f Makefile.win config.h Rconfig.h Rmath.h
cd ../nmath/standalone
make -f Makefile.win

This creates a static library libRmath.a and a DLL Rmath.dll. If you want an import library libRmath.dll.a (you don’t need one), use

make -f Makefile.win shared implib

To use the routines in your own C or C++ programs using MinGW-w64, include

#define MATHLIB_STANDALONE
#include <Rmath.h>

and link against ‘-lRmath’. This will use the first found of libRmath.dll.a, libRmath.a and Rmath.dll in that order, so the result depends on which files are present. You should be able to force static or dynamic linking via

-Wl,-Bstatic -lRmath -Wl,Bdynamic
-Wl,-Bdynamic -lRmath

or by linking to explicit files (as in the ‘test’ target in Makefile.win: this makes two executables, test.exe which is dynamically linked, and test-static.exe, which is statically linked).

It is possible to link to Rmath.dll using other compilers, either directly or via an import library: if you make a MinGW-w64 import library as above, you will create a file Rmath.def which can be used (possibly after editing) to create an import library for other systems such as Visual C++.

If you make use of dynamic linking you should use

#define MATHLIB_STANDALONE
#define RMATH_DLL
#include <Rmath.h>

to ensure that the constants like NA_REAL are linked correctly. (Auto-import will probably work with MinGW-w64, but it is better to be sure. This is likely to also work with VC++, Borland and similar compilers.)