R Compiler Tools for Rcpp on macOS before R 4.2.0

programming
cpp
Author

James Balamuta

Published

May 18, 2021

This is a historical post that covers how to install the macOS toolchain for versions of R starting for R 4.1.0 - 4.1.3 (the R 4.1.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.1.0 - 4.1.3 series. The post is structured primarily for macOS Big Sur 11 and higher users.

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.1.0 - R 4.1.3 toolchain based on Section: C.3 macOS of R Installation and Administration. These components are:

  1. Xcode Command Line Tools (“Xcode CLI”): 12.4 (Intel) or 13.1 (Apple Silicon M-series)
  2. GNU Fortran:
    • Intel: gfortran 8.2
    • Apple Silicon M-series: Experimental GNU Fortran 11 arm64 fork

The gfortran component is dependent on the version of R and macOS hardware 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 macOS hardware specific gfortran binary

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

The version of gfortran changes based on the version of R and macOS hardware being used. Please ensure that you are using the correct version of gfortran for your version of R and macOS hardware.

If you are unsure of your macOS hardware, please go to the Apple menu () in the upper left and select About This Mac.

  • If you are using an Intel Mac (Chips should say “Intel”), please use the Intel download and commands.
  • If you are using an Apple Silicon M-series Mac (Chips should say “M1” or “M2”), please use the Apple Silicon M-series download command.

For R 4.1.0 - R 4.1.3, you will need to install either gfortran 8.2 (Intel) or the Experimental GNU Fortran 11 arm64 fork (Apple Silicon M-series). The R project makes available an installer Intel and a binary tarball for Apple Silicon M-series.

You can download the appropriate version from the following links:

After you’ve identified the appropriate version of gfortran for your macOS hardware, please download and install it by:

Download the Intel gfortran installer from:

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

Double click the downloaded .dmg installer file and follow the prompts to install.

Next, 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.1.0 - R 4.1.3 on Intel macs
PATH=${PATH}:/usr/local/gfortran/bin
# End gfortran to PATH ----
EOF

Please open Terminal and paste the following command to download Apple Silicon (M-series) gfortran binary tarball:

# Download the gfortran tarball
curl -O https://mac.r-project.org/libs-arm64/gfortran-f51f1da0-darwin20.0-arm64.tar.gz

Next, extract the tarball and install gfortran into /opt/R/arm64/gfortran by running the following command:

# Extract and install gfortran into /opt/R/arm64/gfortran
sudo tar fxz gfortran-f51f1da0-darwin20.0-arm64.tar.gz -C /

The sudo command will prompt you for your user password. This is required to install gfortran into the /opt/R/arm64/gfortran directory.

Finally, use the following command to setup the appropriate paths for gfortran:

cat << 'EOF' >> ~/.Renviron
# Add gfortran to PATH ----
# Required for R 4.1.0 - R 4.1.3 on M-series macs
PATH=${PATH}:/opt/R/arm64/gfortran/bin
# End gfortran to PATH ----
EOF

The later Terminal 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.

If you have previously installed a version of gfortran and modified your ~/.Renviron file, please ensure that you update or remove your ~/.Renviron file to ensure that the correct version of gfortran is being used.

You can modify your ~/.Renviron file by running the following command:

file.edit("~/.Renviron")

Alternatively, you can remove your custom ~/.Renviron file by running the following command:

file.remove("~/.Renviron")

Though, please ensure that you back up your ~/.Renviron file if you have any customizations you want to keep.

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, macOS hardware being used, 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!