Quickly install Java Development Kit (JDK)
without administrative
privileges and set environment variables in current R session or project
to solve common issues with ‘Java’ environment management in ‘R’.
Recommended to users of Java
/{rJava}
-dependent R
packages such as
{r5r}
, {opentripplanner}
, {xlsx}
, {openNLP}
, {rWeka}
,
{RJDBC}
, {tabulapdf}
, and many more. {rJavaEnv}
prevents common
problems like Java
not found, Java
version conflicts, missing Java
installations, and the inability to install Java
due to lack of
administrative privileges. {rJavaEnv}
automates the download,
installation, and setup of the Java
on a per-project basis by setting
the relevant JAVA_HOME
in the current R
session or the current
working directory (via .Rprofile
, with the user’s consent). Similar to
what {renv}
does for R
packages, {rJavaEnv}
allows different
Java
versions to be used across different projects, but can also be
configured to allow multiple versions within the same project (e.g. with
the help of {targets}
package). Note: there are a few extra steps
for ‘Linux’ users, who don’t have any ‘Java’ previously installed in
their system, and who prefer package installation from source, rather
then installing binaries from ‘Posit Package Manager’. See
documentation
for details.
Install from CRAN:
install.packages('rJavaEnv')
Install latest release from R-multiverse:
install.packages('rJavaEnv',
repos = c('https://community.r-multiverse.org', 'https://cloud.r-project.org')
)
You can also install the development version of rJavaEnv
from GitHub:
if (!requireNamespace("remotes", quietly = TRUE)) {
install.packages("remotes")
}
remotes::install_github("e-kotov/rJavaEnv@dev", force = TRUE)
rJavaEnv::java_quick_install(version = 21)
This will:
-
download
Java
21 distribution compatible with the current operating system and processor architecture into a local cache folder; -
extract the downloaded
Java
distribution into another cache folder; -
create a symbolic link (for macOS and Linux) or junction (for Windows, if that fails, just copies the files) rjavaenv/
platform
/processor_architecture
/java_version
in the current directory/project to point to the cached installation; -
set the current session’s
JAVA_HOME
andPATH
environment variables to point to the installed (symlinked)Java
distribution; -
add code to
.Rprofile
file in the current directory/project to setJAVA_HOME
andPATH
environment variables when the project is opened in RStudio.
As part of normal operation, rJavaEnv
will update the JAVA_HOME
and
PATH
environment variables in the current R session, the local cache
in your R package library, and the .Rprofile
file in the
project/current working directory. In line with CRAN
policies,
explicit user consent is required before making these changes.
Therefore, the first time you run any function from rJavaEnv
that
makes such changes, you will be asked for consent. To explicitly consent
and/or to prevent interruptions in non-interactive mode, you can use the
rje_consent()
function:
rje_consent(provided = TRUE)
Just insert this line into the begining of any script that you run with
targets
or callr
:
rJavaEnv::use_java("21")
This acts exactly like java_quick_install()
, but only sets the
environment variables in the current session and does not copy or link
Java
binaries into the project directory.
More details are in the vignette Multiple Java
environments in one
project with targets
and
callr
.
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()
The package has several core functions:
java_quick_install()
- Downloads, installs, and sets Java environment in the current working/project directory, all in one line of code.
java_check_version_cmd()
- Checks the installed Java version using terminal commands. For
packages like
opentripplanner
, that performs Java calls using command line.
- Checks the installed Java version using terminal commands. For
packages like
java_version_check_rjava()
- Checks the installed
Java
version usingrJava
in a separate R session. ForrJava
-dependent packages such asr5r
.
- Checks the installed
java_download()
- Downloads a specified version and distribution of
Java
.
- Downloads a specified version and distribution of
java_install()
- Installs a
Java
distribution file into current (or user-specified) project directory.
- Installs a
java_env_set()
- Sets the
JAVA_HOME
andPATH
environment variables to a given path in current R session and/or in the.Rprofile
file in the project directory.
- Sets the
java_env_unset()
- Remove the
JAVA_HOME
andPATH
environment variables from the.Rrpofile
file in the project directory (but not in the current R session, please restart the session so that R picks up the system Java).
- Remove the
java_list()
- Lists all or some
Java
versions linked in the current project (or cached distributions or installations).
- Lists all or some
java_clear()
- Removes all or some
Java
versions linked in the current project (or cached distributions or installations).
- Removes all or some
use_java()
- Same as
java_quick_install()
, but in a less intrusive way. Does not copy or link theJava
installation folder from cache into the project directory and does not create or edit your.Rprofile
file. Only sets requested java in the current R session.
See more details on all the functions in the Reference.
For detailed usage, see the Quick Start Vignette (work in progress).
Currently, rJavaEnv
only supports major Java
versions such as 8, 11,
17, 21, 22. The download and install functions ignore the minor version
of the Java
distribution and just downloads the latest stable
subversion of the specified major version. This is done to simplify the
process and avoid the need to update the package every time a new minor
version of Java
is released. For most users this should be sufficient,
but this is substandard for full reproducibility.
The main limitation is that if you want to switch to another Java
environment, you will most likely have to restart the current R session
and set the JAVA_HOME
and PATH
environment variables to the desired
Java
environment using rJavaEnv::java_env_set()
. This cannot be done
dynamically within the same R session due to the way Java is initialized
in R, particularly with the rJava
-dependent packages such as
r5r
. With packages like
opentripplanner
, that performs Java
calls using command line, you can switch Java
environments dynamically
within the same R session as much as you want.
Therefore, if you need to use R packages that depend on different Java
versions within the same project, you will have to create separate R
scripts for each Java
environment and run them in separate R sessions.
One effective way of doing this is to use the
callr
package to run R scripts in
separate R sessions. Another option is to use the
targets
package to manage the whole
project workflow, which, as a side effect, will lead to all R scripts
being run in separate R sessions. To use rJavaEnv
with targets
, you
will need to download and install several Java environments using
rJavaEnv::java_download()
and rJavaEnv::java_install()
and set the
relevant path with rJavaEnv::java_env_set()
at the beginning of each
function that requires a certain Java
version.
The future work includes:
-
Add support for more
Java
distributions and versions -
Take care of
R CMD javareconf
-
Possibly add support for specifying
Java
version beyond the major version -
Possibly allow downloading several
Java
distributions in one function call, e.g. different major versions of the same ‘flavour’ or different ‘flavours’ of the same major version -
Possibly add automation to get the
Java
that is required by specificJava
-dependent R packages
I am open to suggestions and contributions, welcome to issues and pull requests.
I thank rOpenSci for the Dev Guide, as well as Hadley Wickham and Jennifer Bryan for the R Packages book.
Package hex sticker logo is partially generated by DALL-E by OpenAI. The logo also contains the original R logo.
To cite package ‘rJavaEnv’ in publications use:
Kotov E (2024). rJavaEnv: Java Environments for R Projects. doi:10.32614/CRAN.package.rJavaEnv https://doi.org/10.32614/CRAN.package.rJavaEnv, https://github.com/e-kotov/rJavaEnv.
BibTeX:
@Manual{rjavaenv,
title = {rJavaEnv: Java Environments for R Projects},
author = {Egor Kotov},
year = {2024},
url = {https://github.com/e-kotov/rJavaEnv},
doi = {10.32614/CRAN.package.rJavaEnv},
}