2 Building R

2.1 Autotools

If you have ever compiled an open source project from scratch, you should be familiar with the file layout of r-source:

ls
#> COPYING         Makefile.fw     VERSION-NICK    doc/            share/
#> ChangeLog       Makefile.in     config.site     etc/            src/
#> INSTALL         README          configure       m4/             tests/
#> Makeconf.in     VERSION         configure.ac    po/             tools/

R is configured for your system and built into binaries using the Autotools build system. Two important Autotools files are:

  • configure: This is an executable script that configures the build system for your particular machine.

  • Makefile.in: From this template, the configure script creates a Makefile. This file contains instructions for the command make, which is the workhorse of a build system.

Normally you build open source softwares with the following incantation (do not run this just yet, wait after reading about the build directory in the next sections):

./configure && make && make install

For building R you need an additional step. First install the recommended packages:

# Download recommended packages
tools/rsync-recommended

./configure && make all && make install

2.2 The build directory

Running configure and make inside the root directory of the R sources is not very practical because they create files all over the place. These files can’t be gitignored effectively and will get in the way of your workflow. To avoid littering the repository with generated files, we are going to build R from a separate directory.

The build directory can in principle be created anywhere you like. We recommend always creating it inside the root directory as build. If you have followed the instructions in Tweak the repository, it should already be created and gitignored.

Always call the configure script from inside the build directory:

cd build
../configure

This should take a couple of minutes. Once configured, your build directory looks like this:

ls
#> Makeconf                Makefrag.m              libconftest.dSYM/       src/
#> Makefile                config.log              libtool                 tests/
#> Makefrag.cc             config.status           m4/                     tools/
#> Makefrag.cc_lo          doc/                    po/
#> Makefrag.cxx            etc/                    share/

You’ll recognise the Makefile file we mentioned earlier. You’ll also find several directories mirroring the file hierarchy from the root folder. The most important are src and tests. These directories contain makefiles of their own:

ls src
#> Makefile        extra/          library/        modules/        scripts/
#> appl/           include/        main/           nmath/          unix/

ls tests
#> Embedding/      Examples/       Makefile

Given the similarity of the file hierarchies it is easy to confuse the root and build directories.

  • The root directory contains all the sources, saved outputs for unit tests, and other revisioned files. You will develop from the root directory.

  • The build directory contains all the makefiles that allow you to interact with the build system. From the build directory you’ll build R, recompile parts of R, run tests, etc.

2.3 Location of installation

We have run configure but we haven’t specified any parameter. You can discover all the supported options with:

../configure --help

One important parameter is the location where you’d like to install R. It is normally decided by the --prefix=path argument.

../configure --prefix=/usr/local

On macOS systems it is often more practical to install R as an application framework. In that case, supply --enable-R-framework instead of --prefix. The advantage of installing as a framework is that you can use the convenient RSwitch dropdown menu to switch to the development version.

../configure --enable-R-framework

2.4 Environment variables

configure --help lists all influential environment variables. You can set envvars by passing them to the configure script. For instance, we might want to set CFLAGS to enable debugging symbols and disable compiler optimisations. This considerably improves the debugging experience:

../configure CFLAGS="-g -O0"

Other important envvars are:

  • CPPFLAGS and LDFLAGS. By default they point to /usr/local/include and /usr/local/lib. On macOS systems, this is where libraries installed with brew are linked.

  • CC which points to gcc by default. On macOS systems, this is an alias for the system clang.

2.5 Making R on macOS

I personally use the following script to build R on macOS. It should be run from the build directory, and the build directory should be a folder inside the root directory:

#!/bin/bash


# R recommends setting this to avoid issues with programs like sed:
export LANG=C

export R_ARCH=""

# Get version in major.minor format:
VERSION=`sed 's/\([0-9]*.[0-9]*\).[0-9]*.*/\1/' ../VERSION`

# Use version-dev as default folder target:
TARGET=${1:-$VERSION-dev}


# Download recommended packages
../tools/rsync-recommended

../configure \
    --enable-R-framework FW_VERSION=${TARGET} \
    --with-aqua=yes \
    --with-x=yes \
    --enable-memory-profiling \
    CFLAGS="-g -O0" && \
  make all && \
  make install

This script:

  • Installs R as an application framework whose version is suffixed with -dev. The suffix is useful if you’d like to install a patched version of an already released R. If you’re working exclusively on the development version, this is not as useful since the framework is set to the next unreleased version and cannot interfere with your regular installations.

  • Installs the recommended packages. These packages are needed for running unit tests.

  • Enables Aqua and X. This adds some compilation time but is useful if you plan to use the development version for actual data analysis or if you’d like to patch the graphical devices.

  • Enables the R memory profiler.

  • Sets CFLAGS to include debugging symbols and disable optimisations.

  • Runs make all to build R and make install to install it as a framework.

The framework is automatically enabled after make install. You should get the following disclaimer if you run R:

R --version
#> R Under development (unstable) (2019-09-12 r77181) -- "Unsuffered Consequences"
#> Copyright (C) 2019 The R Foundation for Statistical Computing
#> Platform: x86_64-apple-darwin18.0.0 (64-bit)

2.5.1 Compilation troubleshooting

  • No Fortran compiler found

    Install gfortran from https://mac.r-project.org/tools/. Add /usr/local/gfortran/bin to your PATH or pass FC=/usr/local/gfortran/bin F77=$FC to the configure script.

    Other warnings and errors about fortran may also be resolved by installing gfortran from that location.

  • PCRE2 library and headers are required

    brew install pcre2

  • libcurl >= 7.28.0 library and headers are required with support for https

    brew install curl-openssl

  • liblzma library and headers are required

    brew install xz

  • zlib library and headers are required

    brew install zlib

  • configure error: cannot run C compiled programs

    xcode-select --install

  • libcurl >= 7.28.0 library and headers are required with support for https

    Take anaconda off of your PATH (SO).

  • X11 headers/libs are not available

    Install XQuartz from https://www.xquartz.org/.

  • Run make clean in the build directory after installing a new version of macOS. If you forget you will likely see errors about specific and versioned header files and libraries.

  • Your personal Makevars file influences the compilation of recommended packages. This might be a source of compilation issues if the environment variables set up there are not up to date (for instance F77 and FC set to gfortran-8 when the current installed version is gfortran-9).

  • ld: can’t write output file: Rscript for architecture x86_64

    This is a permission issue. You’ve likely run sudo make install which builds Rscript and now that file is owned by root. From the build folder, run:

    sudo rm src/unix/Rscript