Configuring an External R Installation to Work with RLink
RLink facilitates seamless communication between Wolfram Language and R, relying specifically on R's rJava package and the JRI native library. Although RLink offers out-of-the-box convenience by bundling prebuilt JRI libraries for various historical R versions on Windows and macOS, there are instances where additional steps are necessary to ensure a successful connection.
This technical document is aimed at addressing challenges that might arise when invoking the InstallR function with default parameters leads to an unsuccessful outcome. Such scenarios are more common on Linux systems and occasionally on other platforms, particularly for more recent R versions where prebuilt JRI libraries are not yet integrated into RLink.
This configuration process is typically a one-time endeavor per unique R installation. Once completed, the R–Wolfram Language connection remains robust. By adhering to this guide, users can seamlessly integrate RLink with their chosen R distribution.
Prerequisites
R
It is assumed that some version of R has already been installed. Having more than one version of R installed is not a problem, but certain steps in the configuration procedure will differ in that case, as described in this document.
Java Development Kit (JDK)
To configure R for use with RLink, it is generally required that a reasonably modern version of Java/Java Development Kit (JDK) is installed. JDK 11 or newer is recommended.
Download and install the JDK while also keeping a record of its installation directory, as it will be necessary for upcoming steps.
macOS
One good option is the JDK from Azul.
Example path to the installed JDK:
/Library/Java/JavaVirtualMachines/zulu-17.jdk/Contents/Home
Windows
One good option is the JDK from Azul.
Example path to the installed JDK:
C:\Program Files\Zulu\zulu-17
Linux
The exact installation procedure will depend on the type of JDK and the flavor of Linux used. Here is an example using OpenJDK 17 and CentOS Linux:
sudo yum install java-17-openjdk-devel
On a Debian-based distribution, the relevant command might look similar to this:
sudo apt install -y openjdk-17-jdk
Example path to the installed JDK:
/usr/lib/jvm/java-17-openjdk
Build/Development Tools
macOS
In some cases on macOS, installation of Apple Developer Tools might be required, in particular Xcode. It is recommended to first try the following simpler method described, and only proceed with the installation if that method fails.
Windows
There are no additional requirements for Windows for the purposes of this technical note.
In this technical note, the process of building the rJava R package from source on Windows is not covered due to its relative complexity on Windows. For more modern versions of R, in the vast majority of cases, the precompiled binary version of this package is available on CRAN for Windows. For older versions of R, RLink already comes with prebuilt JRI libraries.
Linux
On Linux, the R configuration/build process for the rJava R package generally involves compilation of C and Java source code, which means that standard development tools have to be installed. The installation procedure for these might depend on the Linux flavor.
Here is an example for Red Hat–derived Linux flavors:
sudo yum groupinstall "Development Tools"
In some cases, additional libraries might be required:
sudo yum install ncurses-devel zlib-devel texinfo gtk+-devel gtk2-devel
sudo yum install qt-devel tcl-devel tk-devel kernel-headers kernel-devel
The exact set of required libraries and tools depends on the Linux flavor and particular details of the setup for a given Linux machine.
R Configuration Process
The procedure described here has to only be carried out once per given R installation. It is generally similar for all supported platforms and consists of installing the rJava R package and noting the path to it. However, some details are platform specific.
macOS
1. Open the terminal and go to the R installation folder. A typical path to that folder should look like this:
/Library/Frameworks/R.framework/Versions/4.1-arm64/Resources
2. If the R version to be used is the only one installed or the system's default version, type the following in the terminal:
./R
Otherwise, execute the following lines in the terminal (these are generally necessary to make sure that the started R REPL refers to the intended version of R rather than to the current global default):
export R_HOME=$(pwd)
cd bin/exec
export PATH=$(pwd):$PATH
./R
3. The R prompt should appear and will look similar to this:
4. It is recommended, although not always required, to set the JAVA_HOME environmental variable to the installed JDK's home path. To do that, type the following into R's REPL (inserting the correct path to the JDK):
Sys.setenv(JAVA_HOME="/Library/Java/JavaVirtualMachines/zulu-11.jdk/Contents/Home")
install.packages('rJava', repos='http://cran.us.r-project.org', dependencies=TRUE)
The resulting output for a successful installation should look something like this:
The possible warning regarding the X11 module (not present on the previous screenshot) can safely be ignored.
6. To confirm the successful package installation and find the package's location, type:
find.package('rJava')
The result should look similar to this:
It is important to note this path somewhere, since it will be used to point RLink to the built JRI library.
7. At this point, you can exit the R REPL:
8. Please note that the full path to the folder with the JRI library—that one has to point RLink at—is the previously mentioned path with the jri subfolder appended:
This completes the R configuration process for macOS.
Possible Issues
rJava Package Has to Be Built from Source
In some cases, particularly for older versions of R, the prebuilt rJava package might not be available on R distribution servers. In this case, it has to be built from source. If doing this, you can see a screen similar to the following after entering the mirror selection in step 5 of the previously described procedure:
On macOS, successful completion of this step requires that Apple Developer Tools be installed, in particular Xcode. This might also require certain additional steps.
If Xcode has been installed, one should type "y" or "yes" in the prompt. The compilation process will then proceed.
The Error "clang: error: unsupported option '-fopenmp'" During rJava Build Process
The compilation of the rJava package from source, described previously, may result in the following compilation error:
If this happens, a few additional steps will be required. Please follow steps 1 and 2 of the general procedure described previously. Then you will need to install Clang/OpenMP (Homebrew is assumed here as a package manager for the following instructions). Type the following in the terminal prompt:
brew install llvm libomp
export CC=/usr/local/opt/llvm/bin/clang
It will also be necessary to set/export the JAVA_HOME environmental variable (use the correct path to the installed JDK):
export JAVA_HOME=/Library/Java/JavaVirtualMachines/openjdk-11.jdk/Contents/Home
This is followed by this command (sample output shown), executed from the Resources/bin directory:
./R CMD javareconf
After this, follow the steps of the original procedure starting with step 3. Type "yes" when prompted to build rJava from source. The build process should proceed normally.
Windows
1. Open the Windows command-line console and go to the R installation folder. It is best if you can do that with administrator privileges, although this is not a strict requirement.
A typical path to that folder might look like this:
C:\Program Files\R\R-4.3.1
cd bin
2. Enter the interactive R console/REPL:
R
The R prompt should appear. It will look similar to this:
3. In the R REPL, set the JAVA_HOME environmental variable to the path to the installed JDK as follows (insert the correct path for your system):
Sys.setenv(JAVA_HOME="C:\\Program Files\\Zulu\\zulu-11")
Make sure to use double slashes to separate the segments of the path.
install.packages('rJava', repos='http://cran.us.r-project.org', dependencies=TRUE)
The sample output in the event of a successful installation might look like this:
It might happen, particularly when the command-line shell is launched without administrator privileges, that the standard R library location is not writable. In that case, R will ask you to allow it to use an alternative library location where the package will be stored. Type "y" for all questions to allow it to do that.
It might also happen that the available binary version is not the latest one, in which case R will ask whether to continue using the binary version or build the library from source. One should answer "n" to the prompt to continue using the available binary version:
5. To confirm the successful package installation and find the package's location, type:
find.package('rJava')
The result should look similar to this:
It is important to note this path somewhere, since it will be used to point RLink to the built JRI library.
6. At this point, one can exit the R REPL:
7. Please note that the full path to the folder with JRI library—that one has to point RLink at—is the previously mentioned path with the jri/x64 subfolder path appended:
This completes the R configuration process for Windows
Additional Information
Some additional information on the rJava installation/build process on Windows can be found here.
Linux
1. Open the terminal and go to the R installation folder. A typical path to that folder might look like this:
/opt/R/4.3.1/lib64/R
If the R version to be used is not the only one installed, execute the following lines in the terminal (these will ensure that the correct version of R is being started with the correct libraries):
export R_HOME=$(pwd)
export LD_LIBRARY_PATH=$(pwd)/lib
2. It is recommended, but not always required, to also run the following (insert the correct path to the installed JDK here):
export JAVA_HOME=/usr/lib/jvm/java-11-openjdk
It is often also necessary to execute the following:
sudo update-alternatives --config java
Choose the correct Java version in the offered selection (enter the selection in the prompt):
Next, configure R to use the selected Java/JDK version:
sudo ./bin/R CMD javareconf
The sample output upon success might look like this:
If the R version to be used is the only one installed or the system's default version, type the following in the terminal:
./R
cd bin/exec
export PATH=$(pwd):$PATH
./R
The R prompt should appear. It will look similar to this:
install.packages('rJava', repos='http://cran.us.r-project.org', dependencies=TRUE)
In the event the standard R library is not a writable location for the current user, a prompt offering to save the package in a different location may appear:
If that is the case, type "y" for both prompts.
The resulting output for the successful installation should look similar to this:
5. To confirm the successful package installation and find the package's location, type:
find.package('rJava')
The result might look similar to this:
It is important to note this path somewhere, since it will be used to point RLink to the built JRI library.
6. At this point, you can exit the R REPL:
7. Please note that the full path to the folder with the JRI library—that one has to point RLink at—is the previously mentioned path with the jri subfolder appended:
This completes the R configuration process for Linux.
Possible Issues
"Unable to run a simple JNI program" Error
You might encounter such an error during the rJava package build process. It might look like this:
In this particular case, the error appeared because the wrong version of the JDK was used (JDK 1.8). This error should not appear after you go through all the substeps in step 2, since those are responsible for configuring the correct version of Java/JDK to be used for a given R session.
Using RLink with Configured External R Distribution
Once a given R distribution has been configured to be used with RLink, you can use RLink with this distribution. Following are examples of connecting RLink to a properly configured R distribution on different supported platforms.
macOS
Here is a typical example of how you should start RLink with a properly configured external R installation on macOS.
Windows
Here is a typical example of how one starts RLink with a properly configured external R installation on Windows.
Linux
Here is a typical example of how one starts RLink with a properly configured external R installation on Linux.