R Compiler Tools for Rcpp on macOS before R 4.1.0

programming
cpp
Author

James Balamuta

Published

April 24, 2020

This is a historical post that covers how to install the macOS toolchain for versions of R starting for R 4.0.0 - 4.0.5 (the R 4.0.z series).

For the current version of R (4.5.0 - 4.5.z), please see the post: R Compiler Tools for Rcpp on macOS.

For R versions between R:

Intro

The objective behind this post is to provide users with information on how to setup the macOS toolchain for compiling used in the R 4.0.0 - 4.0.5 series. The post is structured primarily for macOS 10.13 (High Sierra) and higher.

Removing Old Installation Files

If you previously used either the clang4, clang6, clang7, or the macos-rtools installer, please consider deleting the old components that were installed.

Instructions for uninstallation can be found here:

Uninstalling the R development toolchain on macOS

That said, please remove both ~/.R/Makevars and ~/.Renviron files prior to continuing as they were set in a prior iteration. You can achieve this by using:

unlink("~/.R/Makevars")
unlink("~/.Renviron")

Alternatively, if there is contents inside of the ~/.Renviron file that must be retained, please look for where the PATH variable is listed and remove any part with clang.

Open the file in R using:

file.edit("~/.Renviron")

Next, find and remove:

PATH="/usr/local/clang7/bin:${PATH}"

Then, save and close the file. You may need to restart R for the changes to take effect.

Installation Instructions

One of the primary ways to setup the R toolchain for compiled code on macOS is to use either the automated R package installer or to individually install each element yourself.

There are two components to the R 4.0.0 - R 4.0.5 toolchain based on Section: C.3 macOS of R Installation and Administration. These components are:

  1. Xcode Command Line Tools (“Xcode CLI”):
    • Xcode CLI 12.4 or higher is required for R 4.0.4 - 4.0.5.
    • Xcode CLI 10.1 or higher is required for R 4.0.0 - 4.0.3.
  2. GNU Fortran: gfortran 8.2

The gfortran component is dependent on the version of R being used.

For historical information about the toolchain, please see: R macOS toolchain evolution

Automatic Installation

The instructions in the next section breakdown how to install the different components for a toolchain on macOS. If you are unfamiliar with Terminal, please consider using the unofficial macOS Rtools installer R package.

This installer R package is community maintained and is not affiliated with either R Core or CRAN. Hence, this installer R package is unofficial.

You can see a video of the installation process here:

Run the following command in your R console to install the package:

# install.packages("remotes")
remotes::install_github("coatless-mac/macrtools")

With the package, you can run inside of R:

macrtools::install_macos_rtools()

Once done, please restart R to ensure that the changes take effect.

You can find source of the package at:

https://github.com/coatless-mac/macrtools

Manual Install Guide

This guide provides a step-by-step breakdown of the actions required to setup the toolchain. As a result, this guide will use both installers and script commands ia Terminal.app found in /Applications/Utilities/. Terminal is macOS’ equivalent to Linux’s shell and Window’s command line. From Terminal, we will install only the XCode Command Line Tools (“Xcode CLI”). These provide the system headers used to build the official CRAN binary for R.

XCode Command Line Tools

  1. Open the Terminal from /Applications/Utilities/
  2. Type the following into Terminal

Anytime the Xcode CLI toolchain updates, you must re-run this command.

sudo xcode-select --install
  1. Press “Install”
  2. Verify installation by typing into terminal:
gcc --version

Install the gfortran binary

The next step is to install the appropriate gfortran binary for your version of R.

For R 4.0.0 - R 4.0.5, you will need to install gfortran 8.2 (Intel). The R project makes available an installer package for the gfortran binary.

You can download the gfortran installer by using:

https://mac.r-project.org/tools/gfortran-8.2-Mojave.dmg

Once downloaded, you can install it by double-clicking the downloaded .dmg installer file and follow the prompts to install.

Once the installer is done, please open Terminal and paste the following command to setup the appropriate paths for gfortran:

cat << 'EOF' >> ~/.Renviron
# Add gfortran to PATH ----
# Required for R 4.0.0 - R 4.0.5 on Intel macs
PATH=${PATH}:/usr/local/gfortran/bin
# End gfortran to PATH ----
EOF

These commands append the appropriate path to the gfortran binary onto the PATH variable within the ~/.Renviron file. When R starts up, it will read the ~/.Renviron file and set the PATH variable appropriately ensuring that gfortran is available to R when compiling code.

Quick check

To verify that everything is working appropriately, let’s do a quick C++ program using Rcpp and Armadillo.

First, let’s install Rcpp and RcppArmadillo within R.

install.packages(c('Rcpp', 'RcppArmadillo'))

Create a new file, name the follow: helloworld.cpp

By adding the .cpp extension, the file is viewed as being C++ code.

Within the file write:

#include <RcppArmadillo.h>   

// [[Rcpp::depends(RcppArmadillo)]]

// [[Rcpp::export]]
void hello_world() {
  Rcpp::Rcout << "Hello World!" << std::endl;  
}

// After compile, this function will be immediately called using
// the below snippet and results will be sent to the R console.

/*** R
hello_world() 
*/

Compile the function using:

Rcpp::sourceCpp('path/to/file/helloworld.cpp')

where 'path/to/file/' is the location containing helloworld.cpp

If everything is installed appropriately, then you should see the following in the console:

hello_world()
# Hello World!

In addition, you should have a new function within the global environment scope called “hello_world”. You can call this function like a normal R function via:

hello_world()

Common Errors

The following are debugged errors that you may run into.

make: gfortran: No such file or directory

If you try to compile code that uses Fortran without a correct version of gfortran for the R version being used, you may see the following error:

make: gfortran: No such file or directory
make: *** [/Library/Frameworks/R.framework/Resources/etc/Makeconf:196: object.o] Error 127
ERROR: compilation failed for package ‘package’

Please ensure that you have installed the correct version of gfortran for your version of R installed and that you have added the appropriate path to your ~/.Renviron file.

fatal error: ‘omp.h’ file not found

If you try to compile code that uses OpenMP, you may see the following error:

clang: warning: argument unused during compilation: '-fopenmp'
fatal error: 'omp.h' file not found

Beginning with R 4.0.0 the CRAN distributed version of R loses the ability to use OpenMP without a custom setup. This custom setup is reserved for advanced users. You can read more about this in the OpenMP support on macOS post.

OpenMP is not part of the default toolchain on macOS as Apple does not ship a version of clang with OpenMP support. However, it is possible to use the OpenMP headers and link against the OpenMP runtime library if you extract and install the appropriate files. This is considered an “advanced” setup and is not recommended for most users. Please see the OpenMP support on macOS post for details.

Acknowledgements

Thanks to dr.ing. MPH Verouden for catching a couple of errors in the post and letting me know!