Skip to content

Commit

Permalink
update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@e-kotov
e-kotov committed May 26, 2024
1 parent 5fd0213 commit 622a164
Show file tree
Hide file tree
Showing 2 changed files with 38 additions and 27 deletions.
32 changes: 18 additions & 14 deletions README.Rmd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ knitr::opts_chunk$set(

<!-- badges: end -->


The goal of `rJavaEnv` is to manage multiple Java JDK in R projects by automating the process of downloading, installing and configuring Java environments on a per-project basis. This package is inspired by the [`renv`](https://rstudio.github.io/renv/){target="_blank"} package for managing R environments in R projects.

The idea is that you can request a specific Java Development Kit (JDK) in your project, and `rJavaEnv` will download and install the requested Java environment in a project-specific directory and set the PATH variable for when you are using this project.
Expand All @@ -29,6 +30,9 @@ Therefore, you can have Amazon Corretto Java 21 for a project that uses [`r5r`](
Actually, you do not have to have any Java installed on your machine at all.
Each Java JDK 'flavour' will quietly live with all its executables in the respective project directory without contaminating your system.

**WARNING** This package is in the early stages of development and is not yet ready for production use. Function names, arguments, and behaviour may change in future versions.


## Installation

You can install the development version of `rJavaEnv` like so:
Expand All @@ -45,11 +49,11 @@ This will download Java 21 distribution, install it in the current project direc

```{r}
library(rJavaEnv)
java_quick_install(version = 21)
```
```{r echo=FALSE, include=FALSE, message=FALSE, warning=FALSE, error=FALSE}
clear_java_distributions_cache()
unlink("./bin", recursive = TRUE)


```{r cache=T}
java_quick_install(version = 21)
```


Expand All @@ -61,23 +65,23 @@ This will be useful if you want to manage multiple Java environments in your pro
### Download Java

The distribution will be cached in the user-specific data directory.
Let us download Java 8 and 21 from default flavour (currently, Amazon Corretto).
Let us download Java 8 and 22 from default flavour (currently, Amazon Corretto).
The function's output is the path to the downloaded Java distribution file.

```{r}
```{r cache=T}
java_8_distrib_path <- rJavaEnv::download_java(version = 8)
java_21_distrib_path <- rJavaEnv::download_java(version = 21)
java_22_distrib_path <- rJavaEnv::download_java(version = 22)
```

### Install Java

Install Java 8 and 21 from the downloaded file into current project/working directory.
Install Java 8 and 22 from the downloaded file into current project/working directory.
The default install path is into ./bin/`platform`/`processor_architecture`/ folder in the current working/project directory, but can be customised, see docs for `rJavaEnv::install_java()`.
The output of the function is the path to the installed Java directory. Note that by default `rJavaEnv::install_java()` sets the JAVA_HOME and PATH environment variables to the installed Java directory, but you can turn this off with the `autoset_java_path` argument.

```{r}
```{r cache=T}
java_8_install_path <- rJavaEnv::install_java(java_8_distrib_path)
java_21_install_path <- rJavaEnv::install_java(java_21_distrib_path)
java_22_install_path <- rJavaEnv::install_java(java_22_distrib_path)
```

### Check Java installation
Expand All @@ -88,12 +92,12 @@ That is, you will be able to set the path to any Java in the current session wit

```{r}
rJavaEnv::check_java_version_rjava(java_8_install_path)
rJavaEnv::check_java_version_rjava(java_21_install_path)
rJavaEnv::check_java_version_rjava(java_22_install_path)
```

### Set Java Environment

We have installed two Java environments in our project directory. We installed version 21 the last, so it is the default Java environment, as `rJavaEnv::install_java()` sets the JAVA_HOME and PATH environment variables to the installed Java directory by default. However, since we have not yet initialised Java using `rJava::.jinit()` or by using some other rJava-dependent package, the Java environment is not yet set in the current R session irreversibly. So we can set the desired Java environment manually. The function below sets the JAVA_HOME and PATH environment variables to the desired Java environment.
We have installed two Java environments in our project directory. We installed version 22 the last, so it is the default Java environment, as `rJavaEnv::install_java()` sets the JAVA_HOME and PATH environment variables to the installed Java directory by default. However, since we have not yet initialised Java using `rJava::.jinit()` or by using some other rJava-dependent package, the Java environment is not yet set in the current R session irreversibly. So we can set the desired Java environment manually. The function below sets the JAVA_HOME and PATH environment variables to the desired Java environment.

```{r}
rJavaEnv::set_java_env(java_8_install_path)
Expand Down Expand Up @@ -141,13 +145,13 @@ rJavaEnv::list_java_distributions_cache()

Remove the cache created by the package to store downloaded Java distributions.

```{r}
```{r eval=F}
rJavaEnv::clear_java_distributions_cache(confirm = FALSE)
```

To remove the Java distributions already unpacked into the current working/project folder, just delete the default or user defined folder:

```{r}
```{r eval=T}
unlink("./bin", recursive = TRUE)
```

33 changes: 20 additions & 13 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,10 @@ Actually, you do not have to have any Java installed on your machine at
all. Each Java JDK ‘flavour’ will quietly live with all its executables
in the respective project directory without contaminating your system.

**WARNING** This package is in the early stages of development and is
not yet ready for production use. Function names, arguments, and
behaviour may change in future versions.

## Installation

You can install the development version of `rJavaEnv` like so:
Expand All @@ -56,6 +60,9 @@ project without worrying about Java versions.

``` r
library(rJavaEnv)
```

``` r
java_quick_install(version = 21)
#> Detected platform: macos
#> Detected architecture: arm64
Expand All @@ -74,7 +81,7 @@ your project or if you want to understand the process better.
### Download Java

The distribution will be cached in the user-specific data directory. Let
us download Java 8 and 21 from default flavour (currently, Amazon
us download Java 8 and 22 from default flavour (currently, Amazon
Corretto). The function’s output is the path to the downloaded Java
distribution file.

Expand All @@ -88,17 +95,17 @@ java_8_distrib_path <- rJavaEnv::download_java(version = 8)
```

``` r
java_21_distrib_path <- rJavaEnv::download_java(version = 21)
java_22_distrib_path <- rJavaEnv::download_java(version = 22)
#> Detected platform: macos
#> Detected architecture: arm64
#> You can change the platform and architecture by specifying the 'platform' and 'arch' arguments.
#> Downloading Java 21 (Corretto) for macos arm64 to /Users/ek/Library/Caches/org.R-project.R/R/rJavaEnv/amazon-corretto-21-aarch64-macos-jdk.tar.gz
#> File already exists. Skipping download.
#> Downloading Java 22 (Corretto) for macos arm64 to /Users/ek/Library/Caches/org.R-project.R/R/rJavaEnv/amazon-corretto-22-aarch64-macos-jdk.tar.gz
#> Download completed.
```

### Install Java

Install Java 8 and 21 from the downloaded file into current
Install Java 8 and 22 from the downloaded file into current
project/working directory. The default install path is into
./bin/`platform`/`processor_architecture`/ folder in the current
working/project directory, but can be customised, see docs for
Expand All @@ -115,9 +122,9 @@ java_8_install_path <- rJavaEnv::install_java(java_8_distrib_path)
```

``` r
java_21_install_path <- rJavaEnv::install_java(java_21_distrib_path)
#> Java 21 (amazon-corretto-21-aarch64-macos-jdk.tar.gz) for macos installed at .//bin/java/macos/aarch64/21
#> JAVA_HOME set to .//bin/java/macos/aarch64/21
java_22_install_path <- rJavaEnv::install_java(java_22_distrib_path)
#> Java 22 (amazon-corretto-22-aarch64-macos-jdk.tar.gz) for macos installed at .//bin/java/macos/aarch64/22
#> JAVA_HOME set to .//bin/java/macos/aarch64/22
```

### Check Java installation
Expand All @@ -136,14 +143,14 @@ rJavaEnv::check_java_version_rjava(java_8_install_path)
```

``` r
rJavaEnv::check_java_version_rjava(java_21_install_path)
#> If you set JAVA_HOME to path: .//bin/java/macos/aarch64/21 rJava and other Java-based packages will use Java version: 21.0.3
rJavaEnv::check_java_version_rjava(java_22_install_path)
#> If you set JAVA_HOME to path: .//bin/java/macos/aarch64/22 rJava and other Java-based packages will use Java version: 22.0.1
```

### Set Java Environment

We have installed two Java environments in our project directory. We
installed version 21 the last, so it is the default Java environment, as
installed version 22 the last, so it is the default Java environment, as
`rJavaEnv::install_java()` sets the JAVA_HOME and PATH environment
variables to the installed Java directory by default. However, since we
have not yet initialised Java using `rJava::.jinit()` or by using some
Expand Down Expand Up @@ -226,15 +233,15 @@ distributions.
rJavaEnv::list_java_distributions_cache()
#> Contents of the Java distributions cache folder:
#> [1] "amazon-corretto-21-aarch64-macos-jdk.tar.gz"
#> [2] "amazon-corretto-8-aarch64-macos-jdk.tar.gz"
#> [2] "amazon-corretto-22-aarch64-macos-jdk.tar.gz"
#> [3] "amazon-corretto-8-aarch64-macos-jdk.tar.gz"
```

Remove the cache created by the package to store downloaded Java
distributions.

``` r
rJavaEnv::clear_java_distributions_cache(confirm = FALSE)
#> Java distributions cache cleared.
```

To remove the Java distributions already unpacked into the current
Expand Down

0 comments on commit 622a164

Please sign in to comment.