Appendix B — Configuration on a Unix-alike

B.1 Configuration options

configure has many options: running

./configure --help

will give a list. Probably the most important ones not covered elsewhere are (defaults in brackets)

--with-x: use the X Window System [yes]
--x-includes=DIR: X include files are in DIR
--x-libraries=DIR: X library files are in DIR
--with-readline: use readline library (if available) [yes]
--enable-R-profiling: attempt to compile support for Rprof() [yes]
--enable-memory-profiling: attempt to compile support for Rprofmem() and tracemem() [no]
--enable-R-shlib: build R as a shared/dynamic library [no]
--enable-BLAS-shlib: build the BLAS as a shared/dynamic library [yes, except on AIX]

You can use --without-foo or --disable-foo for the negatives.

You will want to use --disable-R-profiling if you are building a profiled executable of R (e.g. with -pg). Support for R profiling requires OS support for POSIX threads (aka pthreads), which are available on all mainstream Unix-alike platforms.

Flag --enable-R-shlib causes the make process to build R as a dynamic (shared) library, typically called libR.so, and link the main R executable R.bin against that library. This can only be done if all the code (including system libraries) can be compiled into a dynamic library, and there may be a performance¹ penalty. So you probably only want this if you will be using an application which embeds R. Note that C code in packages installed on an R system linked with --enable-R-shlib is linked against the dynamic library and so such packages cannot be used from an R system built in the default way. Also, because packages are linked against R they are on some OSes also linked against the dynamic libraries R itself is linked against, and this can lead to symbol conflicts.

¹ We have measured 15–20% on i686 Linux and around 10% on x86_64 Linux.

For maximally effective use of valgrind, R should be compiled with Valgrind instrumentation. The configure option is --with-valgrind-instrumentation=level, where level is 0, 1 or 2. (Level 0 is the default and does not add anything.) The system headers for valgrind are required: on Linux they may be in a separate package such as valgrind-devel.

If you need to re-configure R with different options you may need to run make clean or even make distclean before doing so.

The configure script has other generic options added by autoconf and which are not supported for R: in particular building for one architecture on a different host is not possible.

B.2 Internationalization support

Translation of messages is supported via GNU gettext unless disabled by the configure option --disable-nls. The configure report will show NLS as one of the ‘Additional capabilities’ if support has been compiled in, and running in an English locale (but not the C locale) will include

  Natural language support but running in an English locale

in the greeting on starting R.

B.3 Configuration variables

If you need or want to set certain configure variables to something other than their default, you can do that by either editing the file config.site (which documents many of the variables you might want to set: others can be seen in file etc/Renviron.in) or on the command line as

./configure VAR=value

If you are building in a directory different from the sources, there can be copies of config.site in the source and the build directories, and both will be read (in that order). In addition, if there is a file ~/.R/config, it is read between the config.site files in the source and the build directories.

There is also a general autoconf mechanism for config.site files, which are read before any of those mentioned in the previous paragraph. This looks first at a file specified by the environment variable CONFIG_SITE, and if not is set at files such as /usr/local/share/config.site and /usr/local/etc/config.site in the area (exemplified by /usr/local) where R would be installed.

These variables are precious, implying that they do not have to be exported to the environment, are kept in the cache even if not specified on the command line, checked for consistency between two configure runs (provided that caching is used), and are kept during automatic reconfiguration as if having been passed as command line arguments, even if no cache is used.

See the variable output section of configure --help for a list of all these variables.

If you find you need to alter configure variables, it is worth noting that some settings may be cached in the file config.cache, and it is a good idea to remove that file (if it exists) before re-configuring. Note that caching is turned off by default: use the command line option --config-cache (or -C) to enable caching.

B.3.1 Setting paper size

One common variable to change is R_PAPERSIZE, which defaults to a4, not letter. (Valid values are a4, letter, legal and executive.)

This is used both when configuring R to set the default, and when running R to override the default. It is also used to set the paper size when making PDF manuals.

The configure default will most often be a4 if R_PAPERSIZE is unset. (If the program paperconf is found, present in many Linux distributions, or the environment variable PAPERSIZE is set, these are used to produce the default.)

B.3.2 Setting the browsers

Another precious variable is R_BROWSER, the default HTML browser, which should take a value of an executable in the user’s path or specify a full path.

Its counterpart for PDF files is R_PDFVIEWER.

B.3.3 Compilation flags

If you have libraries and header files, e.g., for GNU readline, in non-system directories, use the variables LDFLAGS (for libraries, using -L flags to be passed to the linker) and CPPFLAGS (for header files, using -I flags to be passed to the C/C++ preprocessors), respectively, to specify these locations. These default to -L/usr/local/lib (LDFLAGS, -L/usr/local/lib64 on most 64-bit Linux OSes) and -I/usr/local/include (CPPFLAGS, but note that on most systems /usr/local/include is regarded as a system include directory and so instances in that macro will be skipped) to catch the most common cases. If libraries are still not found, then maybe your compiler/linker does not support re-ordering of -L and -l flags. In this case, use a different compiler (or a front-end shell script which does the re-ordering).

These flags can also be used to build a faster-running version of R. On most platforms using gcc, having -O3 in CFLAGS and FFLAGS produces worthwhile performance gains with gcc and gfortran, but may result in a less reliable build (both segfaults and incorrect numeric computations have been seen). On systems using the GNU linker (especially those using R as a shared library), it is likely that including -Wl,-O1 in LDFLAGS is worthwhile, and '-Bdirect,--hash-style=both,-Wl,-O1’ is recommended at https://lwn.net/Articles/192624/. Tuning compilation to a specific CPU family (e.g. -mtune=native for gcc) can give worthwhile performance gains, especially on older architectures such as ix86.

B.3.4 Making manuals

The default settings for making the manuals are controlled by R_RD4PDF and R_PAPERSIZE.

B.4 Setting the shell

By default the shell scripts such as R will be #!/bin/sh scripts (or using the SHELL chosen by configure). This is almost always satisfactory, but on a few systems /bin/sh is not a Bourne shell or clone, and the shell to be used can be changed by setting the configure variable R_SHELL to a suitable value (a full path to a shell, e.g. /usr/local/bin/bash).

B.5 Using make

To build in a separate directory you need a make that supports the VPATH variable, for example GNU make and dmake.

If you want to use a make by another name, for example if your GNU make is called gmake, you need to set the variable MAKE at configure time, for example

./configure MAKE=gmake

B.6 Using Fortran

To compile R, you need a Fortran 90 compiler. The current default is to search for gfortran, g95, xlf95 f95, fort, ifort, ifc, efc, pgfortran, pgf95 lf95, ftn, nagfor, xlf90, f90, pgf90, pghpf, epcf90. (Note that these are searched for by name, without checking the standard of Fortran they support.) The command and flags used should support fixed-form Fortran with extension .f: in the unusual case that a specific flag is needed for free-form Fortran with extension .f90 or .f95, this can be specified as part of FCFLAGS.

The search mechanism can be changed using the configure variable FC which specifies the command that runs the Fortran compiler. If your Fortran compiler is in a non-standard location, you should set the environment variable PATH accordingly before running configure, or use the configure variable FC to specify its full path.

If your Fortran libraries are in slightly peculiar places, you should also look at LD_LIBRARY_PATH (or your system’s equivalent) to make sure that all libraries are on this path.

Note that only Fortran compilers which convert identifiers to lower case are supported.

You must set whatever compilation flags (if any) are needed to ensure that Fortran integer is equivalent to a C int pointer and Fortran double precision is equivalent to a C double pointer. This is checked during the configuration process.

Some of the Fortran code makes use of DOUBLE COMPLEX and COMPLEX*16 variables. This is checked for at configure time, as well as its equivalence to the Rcomplex C structure defined in R_ext/Complex.h.

gfortran 10 by default gives a compilation error for the previously widespread practice of passing a Fortran array element where an array is expected, or a scalar instead of a length-one array. See https://gcc.gnu.org/gcc-10/porting_to.html. gfortran 12 errors in more cases of this.

B.7 Compile and load flags

A wide range of flags can be set in the file config.site or as configure variables on the command line. We have already mentioned

CPPFLAGS: header file search directory (-I) and any other miscellaneous options for the C and C++ preprocessors and compilers
LDFLAGS: path (-L), stripping (-s) and any other miscellaneous options for the linker

and others include

CFLAGS: debugging and optimization flags, C
MAIN_CFLAGS: ditto, for compiling the main program (e.g. when profiling)
SHLIB_CFLAGS: for shared objects (no known examples)
FFLAGS: debugging and optimization flags, fixed-form Fortran
FCFLAGS: debugging and optimization flags, free-form Fortran
SAFE_FFLAGS: ditto for source files which need exact floating point behaviour
MAIN_FFLAGS: ditto, for compiling the main program (e.g. when profiling)
SHLIB_FFLAGS: for shared objects (no known examples)
MAIN_LDFLAGS: additional flags for the main link
SHLIB_LDFLAGS: additional flags for linking the shared objects
LIBnn: the primary library directory, lib or lib64
CPICFLAGS: special flags for compiling C code to be turned into a shared object
FPICFLAGS: special flags for compiling Fortran code to be turned into a shared object
CXXPICFLAGS: special flags for compiling C++ code to be turned into a shared object
DEFS: defines to be used when compiling C code in R itself

Library paths specified as -L/lib/path in LDFLAGS are collected together and prepended to LD_LIBRARY_PATH (or your system’s equivalent), so there should be no need for -R or -rpath flags.

Variables such as CPICFLAGS are determined where possible by configure. Some systems allows two types of PIC flags, for example -fpic and -fPIC, and if they differ the first allows only a limited number of symbols in a shared object. Since R as a shared library has about 6200 symbols, if in doubt use the larger version.

Other variables often set by configure include MAIN_LDFLAGS, SAFE_FFLAGS, SHLIB_LDFLAGS and SHLIB_CXXLDFLAGS: see file config.site in the sources for more documentation on these and others.

To compile a profiling version of R, one might for example want to use MAIN_CFLAGS=-pg, MAIN_FFLAGS=-pg, MAIN_LDFLAGS=-pg on platforms where -pg cannot be used with position-independent code.

Beware: it may be necessary to set CFLAGS and FFLAGS in ways compatible with the libraries to be used: one possible issue is the alignment of doubles, another is the way structures are passed.

On some platforms configure will select additional flags for CFLAGS, CPPFLAGS and LIBS in R_XTRA_CFLAGS (and so on). These are for options which are always required, for example to force IEC 60559 compliance.

B.8 Maintainer mode

There are several files that are part of the R sources but can be re-generated from their own sources by configuring with option --enable-maintainer-mode and then running make in the build directory. This requires other tools to be installed, discussed in the rest of this section.

File configure is created from configure.ac and the files under m4 by autoconf and aclocal (part of the automake package). There is a formal version requirement on autoconf of 2.72 or later, but it is unlikely that anything other than the most recent versions² have been thoroughly tested.

² at the time of revision of this para in early 2024, autoconf-2.72 and automake-1.16.5. Previously autoconf-2.71 was used.

File src/include/config.h is created by autoheader (part of autoconf).

Grammar files *.y are converted to C sources by an implementation of yacc, usually bison -y: these are found in src/main and src/library/tools/src. It is known that earlier versions of bison generate code which reads (and in some cases writes) outside array bounds: bison 3.8.2 is currently used.

The ultimate sources for package compiler are in its noweb directory. To re-create the sources from src/library/compiler/noweb/compiler.nw, the command notangle is required. Some Linux distributions include this command in package noweb. It can also be installed from the sources at https://www.cs.tufts.edu/~nr/noweb/³. The package sources are only re-created even in maintainer mode if src/library/compiler/noweb/compiler.nw has been updated.

³ The links there have proved difficult to access, in which case grab the copy made available at https://developer.r-project.org/noweb-2.11b.tgz.

Footnotes