-
Notifications
You must be signed in to change notification settings - Fork 1
/
README.qmd
209 lines (131 loc) · 11.7 KB
/
README.qmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
---
format: gfm
default-image-extension: ""
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "man/figures/README-",
out.width = "100%"
)
is_html <- knitr::is_html_output()
```
# rJavaEnv: Java Environments for R Projects <a href="https://www.ekotov.pro/rJavaEnv/"><img src="man/figures/logo.png" align="right" height="134" alt="rJavaEnv website" /></a>
<!-- badges: start -->
[](https://www.repostatus.org/#active)
[](https://lifecycle.r-lib.org/articles/stages.html#stable){target="_blank"} [](https://CRAN.R-project.org/package=rJavaEnv){target="_blank"}
[](https://CRAN.R-project.org/package=rJavaEnv){target="_blank"}
[](https://CRAN.R-project.org/package=rJavaEnv){target="_blank"}
[](https://github.com/e-kotov/rJavaEnv/actions/workflows/R-CMD-check.yaml)
<!-- [](https://github.com/e-kotov/rJavaEnv/actions?query=workflow%3Apkgcheck) -->
[](https://app.codecov.io/github/e-kotov/rJavaEnv)
[](https://doi.org/10.32614/CRAN.package.rJavaEnv)
[](https://doi.org/10.5281/zenodo.11403009)
<!-- badges: end -->
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](https://www.ekotov.pro/rJavaEnv/articles/rJavaEnv.html#note-linux) for details.**
```{r results="asis", eval = !is_html, include = !is_html, include = FALSE}
glue::glue('<script type="application/ld+json">
{glue::glue_collapse(readLines("inst/schemaorg.json"), sep = "\n")}
</script>')
```
## Install
Install from CRAN:
```r
install.packages('rJavaEnv')
```
Install latest release from **R-multiverse**:
```r
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:
```r
if (!requireNamespace("remotes", quietly = TRUE)) {
install.packages("remotes")
}
remotes::install_github("e-kotov/rJavaEnv@dev", force = TRUE)
```
## Simple Example
```r
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` and `PATH` environment variables to point to the installed (symlinked) `Java` distribution;
- add code to `.Rprofile` file in the current directory/project to set `JAVA_HOME` and `PATH` 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](https://cran.r-project.org/web/packages/policies.html), 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:
```r
rje_consent(provided = TRUE)
```
## Using `rJavaEnv` with `targets` and `callr`
Just insert this line into the begining of any script that you run with `targets` or `callr`:
```r
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`](https://www.ekotov.pro/rJavaEnv/articles/multiple-java-with-targets-callr.html).
## Cleanup
If you do not want to use `rJavaEnv` anymore, please clear the cache folders before removing the package:
```r
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:
```r
java_env_unset()
```
## Functions Overview
The package has several core functions:
1. `java_quick_install()`
* Downloads, installs, and sets Java environment in the current working/project directory, all in one line of code.
2. `java_check_version_cmd()`
* Checks the installed Java version using terminal commands. For packages like [`opentripplanner`](https://github.com/ropensci/opentripplanner){target="_blank"}, that performs Java calls using command line.
3. `java_version_check_rjava()`
* Checks the installed `Java` version using `rJava` in a separate R session. For `rJava`-dependent packages such as [`r5r`](https://github.com/ipeaGIT/r5r){target="_blank"}.
4. `java_download()`
* Downloads a specified version and distribution of `Java`.
5. `java_install()`
* Installs a `Java` distribution file into current (or user-specified) project directory.
6. `java_env_set()`
* Sets the `JAVA_HOME` and `PATH` environment variables to a given path in current R session and/or in the `.Rprofile` file in the project directory.
7. `java_env_unset()`
* Remove the `JAVA_HOME` and `PATH` 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).
8. `java_list()`
* Lists all or some `Java` versions linked in the current project (or cached distributions or installations).
9. `java_clear()`
* Removes all or some `Java` versions linked in the current project (or cached distributions or installations).
10. `use_java()`
* Same as `java_quick_install()`, but in a less intrusive way. Does not copy or link the `Java` 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](https://www.ekotov.pro/rJavaEnv/reference/index.html){target="_blank"}.
For detailed usage, see the [Quick Start Vignette](https://www.ekotov.pro/rJavaEnv/articles/rJavaEnv.html) (work in progress).
## Limitations
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`](https://github.com/ipeaGIT/r5r){target="_blank"}. With packages like [`opentripplanner`](https://github.com/ropensci/opentripplanner){target="_blank"}, 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`](https://github.com/r-lib/callr){target="_blank"} package to run R scripts in separate R sessions. Another option is to use the [`targets`](https://github.com/ropensci/targets){target="_blank"} 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.
## Future work
The future work includes:
- Add support for more `Java` distributions and versions
- Take care of [`R CMD javareconf`](https://solutions.posit.co/envs-pkgs/using-rjava/#reconfigure-r){target="_blank"}
- 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 specific `Java`-dependent R packages
I am open to suggestions and contributions, welcome to [issues](https://github.com/e-kotov/rJavaEnv/issues){target="_blank"} and [pull requests](https://github.com/e-kotov/rJavaEnv/pulls){target="_blank"}.
## Acknowledgements
I thank rOpenSci for the [Dev Guide](https://devguide.ropensci.org/){target="_blank"}, as well as Hadley Wickham and Jennifer Bryan for the [R Packages](https://r-pkgs.org/){target="_blank"} book.
Package hex sticker logo is partially generated by DALL-E by OpenAI. The logo also contains the original R logo.
## Citation
```{r echo=FALSE, results='asis'}
print(citation("rJavaEnv"), bibtex = FALSE)
```
BibTeX:
```
```{r echo=FALSE, results='asis'}
toBibtex(citation("rJavaEnv"))
```
```