Chapter 11 Appendix B Configuration on a Unix-alike
B.1 Configuration options
configure has many options: running
will give a list. Probably the most important ones not covered elsewhere are (defaults in brackets)
use the X Window System [yes]
X include files are in DIR
X library files are in DIR
use readline library (if available) [yes]
attempt to compile support for
attempt to compile support for
build R as a shared/dynamic library [no]
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)’.
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 performance57 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.
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 can be requested by option –with-system-valgrind-headers: they will be used if present (on Linux they may be in a separate package such as valgrind-devel). Note though that there is no guarantee that the code in R will be compatible with very old58 or future
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
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 (Debian Linux) program
paperconf is found 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
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 (years ago this was reported to be a problem on HP-UX with the native
cc). 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
FFLAGS produces worthwhile performance gains with
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
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 compile R, you will most likely find it easiest to use GNU
make, although the Sun
make works on Solaris. The native
make has been reported to fail on SGI Irix 6.5 and Alpha/OSF1 (aka Tru64).
To build in a separate directory you need a
make that supports the
VPATH variable, for example GNU
make and Sun
dmake has also been used. e.g, on Solaris 10.
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
B.6 Using FORTRAN
To compile R, you need a FORTRAN compiler. The default is to search for
af77 (in that order)59, and use whichever is found first; if none is found, R cannot be compiled. However, if
gcc, the matching FORTRAN compiler (
gcc 3 and
gcc 4) is used if available.
The search mechanism can be changed using the configure variable
F77 which specifies the command that runs the FORTRAN 77 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
F77 to specify its full 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
COMPLEX*16 variables, which is a Fortran 90 extension. This is checked for at configure time60, but you may need to avoid compiler flags asserting FORTRAN 77 compliance.
Compiling the version of LAPACK in the R sources also requires some Fortran 90 extensions, but these are not needed if an external LAPACK is used.
It might be possible to use
f2c, the FORTRAN-to-C converter (http://www.netlib.org/f2c), via a script. (An example script is given in scripts/f77_f2c: this can be customized by setting the environment variables
CPP.) You will need to ensure that the FORTRAN type
integer is translated to the C type
int. Normally f2c.h contains ‘typedef long int integer;’, which will work on a 32-bit platform but needs to be changed to ‘typedef int integer;’ on a 64-bit platform. If your compiler is not
gcc you will need to set
FPICFLAGS appropriately. Also, the included LAPACK sources contain constructs that
f2c is unlikely to be able to process, so you would need to use an external LAPACK library (such as CLAPACK from http://www.netlib.org/clapack/).
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
header file search directory (-I) and any other miscellaneous options for the C and C++ preprocessors and compilers
path (-L), stripping (-s) and any other miscellaneous options for the linker
and others include
debugging and optimization flags, C
ditto, for compiling the main program
for shared objects
debugging and optimization flags, FORTRAN
ditto for source files which need exact floating point behaviour
ditto, for compiling the main program
for shared objects
additional flags for the main link
additional flags for linking the shared objects
the primary library directory, lib or lib64
special flags for compiling C code to be turned into a shared object
special flags for compiling Fortran code to be turned into a shared object
special flags for compiling C++ code to be turned into a shared object
special flags for compiling Fortran 95 code to be turned into a shared object
defines to be used when compiling C code in R itself
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.
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
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
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
aclocal (part of the automake package). There is a formal version requirement on
autoconf of 2.62 or later, but it is unlikely that anything other than the most recent versions61 have been thoroughly tested.
File src/include/config.h is created by
autoheader (part of autoconf).
Grammar files *.y are converted to C sources by an implementation of
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 2.6.1 was found to be satisfactory.
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/62. The package sources are only re-created even in maintainer mode if src/library/compiler/noweb/compiler.nw has been updated.
It is likely that in future creating
configure will need the GNU ‘autoconf archive’ installed. This can be found at https://www.gnu.org/software/autoconf-archive/ and as a package (usually called autoconf-archive) in most packaged distributions, for example Debian, Fedora, OpenCSW, Homebrew and MacPorts.