library(rJavaEnv)
Java
for ‘R’ ProjectsThe basics of using rJavaEnv
are covered in the Quick Start Guide, which demonstrates how to install Java in one line of code. This guide will show you how to have a more fine-grained control over your Java environments. Also see the vignette on using rJavaEnv
with the targets
and callr
packages to manage multiple Java
environments.
library(rJavaEnv)
Assume your project directory is currently in a temporary directory. Feel free to skip that, if you are already working in a desired project directory where you would like to install Java
. In the example outputs below you will see paths that point to a temporary directory, but in a real project you would see your project directory instead.
<- tempdir()
project_dir setwd(project_dir)
You can specify the cache folder location with the rJavaEnv.cache_path
option.
options(rJavaEnv.cache_path = "/path/to/your/desired/cache/folder")
By default the location would be set to whichever path is returned by tools::R_user_dir("rJavaEnv", which = "cache")
. The exact path will depend on the operating system. Our recommendation is to leave this option at it’s default setting. This is similar to how renv
package manages the cache for R
packages.
You can view the current cache location with:
getOption("rJavaEnv.cache_path")
Expected output (on a Windows machine):
"C:\\Users\\user_name\\AppData\\Local/R/cache/R/rJavaEnv"
Expected output (on a macOS machine):
"/Users/user_name/Library/Caches/org.R-project.R/R/rJavaEnv"
Java
JDK distributionsTo download a specific Java distribution, use the java_download
function:
<- java_download(version = 17)
java_17_distr java_17_distr
Expected output (on a Windows machine):
Detected platform: windows
Detected architecture: x64
You can change the platform and architecture by specifying the `platform` and `arch` arguments.
Downloading Java 17 (Corretto) for windows x64 to C:\Users\user_name\AppData\Local/R/cache/R/rJavaEnv/distrib/amazon-corretto-17-x64-windows-jdk.zip
[100%] Downloaded 187323560 bytes...
Download completed.
MD5 checksum verified.
[1] "C:\\Users\\user_name\\AppData\\Local/R/cache/R/rJavaEnv/distrib/amazon-corretto-17-x64-windows-jdk.zip"
This function will download the specified version of Java
JDK (currently defaults to the only supported Corretto distribution by Amazon, more will be added in new package releases).
The function returns the path to the downloaded distribution file, which is just a zip
or gz
archive.
By default, if no cache_path
is specified when calling java_download()
, the distribution is downloaded into the folder defined by getOption("rJavaEnv.cache_path")
. So with this argument you can override the globally set cache folder location for this single download.
java_download()
also allows you to define the operating system and processor architecture with function arguments platform
and arch
(please see the function documentation using ?rJavaEnv::java_download
). For example, this may be useful if you are packaging a Java distribution for Linux while using a Windows or macOS machine. This may also be useful if for some reason automatic OS and CPU detection fails.
For example, this line above will download the Amazon Corretto
Java JDK
version 8 for x86-64 Linux, even though you may be running this code on aarch64 macOS or x86_64 Windows machine:
<- java_download(
java_8_linux64_distr version = 8,
platform = "linux",
arch = "x64"
)
Example expected output (on a Windows machine):
Detected platform: linux
Detected architecture: x64
You can change the platform and architecture by specifying the `platform` and `arch` arguments.
Downloading Java 8 (Corretto) for linux x64 to C:\Users\user_name\AppData\Local/R/cache/R/rJavaEnv/distrib/amazon-corretto-8-x64-linux-jdk.tar.gz
[100%] Downloaded 118096667 bytes...
Download completed.
MD5 checksum verified.
Java
JDK distributionsYou can manage downloaded distributions with the java_list
and java_clear
functions.
java_list("distrib")
Expected output (on a Windows machine):
java_distr_path
1 C:\\Users\\user_name\\AppData\\Local/R/cache/R/rJavaEnv/distrib/amazon-corretto-17-x64-windows-jdk.zip
2 C:\\Users\\user_name\\AppData\\Local/R/cache/R/rJavaEnv/distrib/amazon-corretto-21-x64-windows-jdk.zip
3 C:\\Users\\user_name\\AppData\\Local/R/cache/R/rJavaEnv/distrib/amazon-corretto-8-x64-linux-jdk.tar.gz
java_clear("distrib")
Example expected output (on a Windows machine):
i Existing Java distributions:
1: C:\Users\user_name\AppData\Local/R/cache/R/rJavaEnv/distrib/amazon-corretto-17-x64-windows-jdk.zip
2: C:\Users\user_name\AppData\Local/R/cache/R/rJavaEnv/distrib/amazon-corretto-21-x64-windows-jdk.zip
3: C:\Users\user_name\AppData\Local/R/cache/R/rJavaEnv/distrib/amazon-corretto-8-x64-linux-jdk.tar.gz
i Enter the number of the distribution to delete, 'all' to delete all, or '0' or any other character to cancel:
You can also delete all downloaded distributions without consent with:
java_clear("distrib", delete_all = TRUE)
Example expected output:
Java distributions cache cleared.
Java
JDK distributions into current projectAs we have cleared all downloaded Java
distributions, let us re-download a few of them:
<- java_download(8)
java_8_distr <- java_download(17)
java_17_distr <- java_download(22) java_22_distr
Now that we have downloaded the Java
distributions, we can install any one of them into the project. Installation in the context of rJavaEnv
means extracting the distribution into the installed
cache folder (which is in the same root cache directory as the zip archives of the distributions), and linking the files (via symlinks in macOS
and Linux
, and junctions in Windows
1). If we set the autoset_java_env
argument to FALSE
we will need to set the JAVA_HOME
and PATH
environment variables manually.
java_install(
java_distrib_path = java_17_distr,
autoset_java_env = FALSE)
Example expected output (on a Windows machine):
Java 17 (amazon-corretto-17-x64-windows-jdk.zip) for windows x64 installed at C:\Users\user_name\AppData\Local/R/cache/R/rJavaEnv/installed/windows/x64/17 and symlinked to
C:/Users/user_name/AppData/Local/Temp/75/Rtmp0MasTW/rjavaenv/windows/x64/17
If we did leave autoset_java_env = TRUE
which is a default option, install_java()
function would automatically set the JAVA_HOME
and PATH
environment variables manually in both the current R
session and in the current project/working directory by writing a few lines into the .Rprofile
file in the current working directory. This way each time you would start an R session, the JAVA_HOME
and PATH
environment variables would be set to the correct path to the installed Java
distribution.
Alternatively, you may want to not install Java
into your project, but just unpack the distribution into the cache folder. For this, you can use the java_unpack()
function, passing it the path to the downloaded Java
distribution from before:
<- java_unpack(java_distr_path = java_8_distr) java_home
java_unpack
will return full path to the unpacked Java
distribution that you can use to set the environment variables in the section below using java_env_set()
.
Java
environmentLet us install another downloaded Java
distribution, this time with autoset_java_env = TRUE
:
java_install(
java_distrib_path = java_8_distr,
autoset_java_env = TRUE)
Expected output (on a Windows machine):
Java distribution amazon-corretto-8-x64-windows-jdk.zip already unpacked at C:\Users\user_name\AppData\Local/R/cache/R/rJavaEnv/installed/windows/x64/8
v Current R Session: JAVA_HOME and PATH set to C:\Users\user_name\AppData\Local/R/cache/R/rJavaEnv/installed/windows/x64/8
v Current R Project/Working Directory: JAVA_HOME and PATH set to 'C:\Users\user_name\AppData\Local/R/cache/R/rJavaEnv/installed/windows/x64/8' in .Rprofile at 'C:/Users/user_name/AppData/Local/Temp/75/R
tmp0MasTW'
Java 8 (amazon-corretto-8-x64-windows-jdk.zip) for windows x64 installed at C:\Users\user_name\AppData\Local/R/cache/R/rJavaEnv/installed/windows/x64/8 and symlinked to
C:/Users/user_name/AppData/Local/Temp/75/Rtmp0MasTW/rjavaenv/windows/x64/8
We can now list the Java
versions installed in the project directory:
java_list("project")
Expected output (on a Windows machine):
path platform arch version
1 C:/Users/user_name/AppData/Local/Temp/75/Rtmp0MasTW/rjavaenv/windows/x64/17 windows x64 17
2 C:/Users/user_name/AppData/Local/Temp/75/Rtmp0MasTW/rjavaenv/windows/x64/8 windows x64 8
We first installed Java 17 with autoset_java_env = FALSE
, and then installed Java 8 with autoset_java_env = TRUE
. If we check which version is currently set as the JAVA_HOME
environment variable, we would get the second installed Java
version, which is Java 8.
java_check_version_cmd()
Expected output (on a Windows machine):
JAVA_HOME: C:\Users\user_name\AppData\Local/R/cache/R/rJavaEnv/installed/windows/x64/8
Java path: /c/Users/user_name/AppData/Local/R/cache/R/rJavaEnv/installed/windows/x64/8/bin/java
Java version: "openjdk version \"1.8.0_422\" OpenJDK Runtime Environment Corretto-8.422.05.1 (build 1.8.0_422-b05) OpenJDK 64-Bit Server VM Corretto-8.422.05.1 (build 25.422-b05, mixed mode)"
[1] TRUE
To switch to Java 17 we need to manually set the JAVA_HOME
and PATH
environment variables with java_env_set()
. To identify which path to pass to java_env_set()
, we can use the java_list("project")
function again:
java_list("project")
Expected output (on a Windows machine):
path platform arch version
1 C:/Users/user_name/AppData/Local/Temp/75/Rtmp0MasTW/rjavaenv/windows/x64/17 windows x64 17
2 C:/Users/user_name/AppData/Local/Temp/75/Rtmp0MasTW/rjavaenv/windows/x64/8 windows x64 8
As we can see, the Java 17 is currently number 1 in this list, so we save this path:
<- java_list("project", output = "vector")[1]
java_home_17 java_home_17
Expected output (on a Windows machine):
"C:/Users/user_name/AppData/Local/Temp/75/Rtmp0MasTW/rjavaenv/windows/x64/17"
Now we can reuse this path in the java_env_set()
function:
java_env_set(where = "both", java_home = java_home_17)
Expected output (on a Windows machine):
v Current R Session: JAVA_HOME and PATH set to C:/Users/user_name/AppData/Local/Temp/75/Rtmp0MasTW/rjavaenv/windows/x64/17
v Current R Project/Working Directory: JAVA_HOME and PATH set to 'C:/Users/user_name/AppData/Local/Temp/75/Rtmp0MasTW/rjavaenv/windows/x64/17' in .Rprofile at 'C:/Users/user_name/AppData/Local/Temp/75/R
tmp0MasTW'
And finally we can double check which version of Java
is going to be picked up by the Java
/rJava
-dependent R
package that you are going to use with:
java_check_version_cmd() # for pacakges that use Java via commandline, like opentripplanner
java_check_version_rjava() # for packages that use Java via `rJava`, like r5r
Expected output (on a Windows machine):
JAVA_HOME: C:/Users/user_name/AppData/Local/Temp/75/Rtmp0MasTW/rjavaenv/windows/x64/17
Java path: /c/Users/user_name/AppData/Local/Temp/75/Rtmp0MasTW/rjavaenv/windows/x64/17/bin/java
Java version: "openjdk version \"17.0.12\" 2024-07-16 LTS OpenJDK Runtime Environment Corretto-17.0.12.7.1 (build 17.0.12+7-LTS) OpenJDK 64-Bit Server VM Corretto-17.0.12.7.1 (build
17.0.12+7-LTS, mixed mode, sharing)"
[1] TRUE
Using current session's JAVA_HOME: C:/Users/user_name/AppData/Local/Temp/75/Rtmp0MasTW/rjavaenv/windows/x64/17
With the user-specified JAVA_HOME rJava and other rJava/Java-based packages will use Java version: "17.0.12"
[1] TRUE
If you do not want to use rJavaEnv
anymore, please clear the cache folders before removing the package:
java_clear("project", delete_all = TRUE)
java_clear("installed", delete_all = TRUE)
java_clear("distrib", delete_all = TRUE)
Also, clear the .Rprofile
file in the projects there you used the package:
java_env_unset()
In Windows, it is sometimes impossible to create junctions for files and folders. In this case, the Java
installation will have to be copied into the project folder, which will take some time. This behaviour is the same renv
’s for R packages and is an operating system limitation.↩︎