Maximize SDKMAN Utility: Tips for .sdkman Configuration

In the previous article, I described the SDKMAN product. Today, I want to explain how to use the .sdkmanrc file to quickly set up and install the necessary SDKs and toolchains in a project.

Basic sdk env usage

The command sdk env init is used to store information about the current JDK in the current project (the current directory). This information is stored in the .sdkmanrc file. The following example shows the process of creating such a file.

# Go to a project locaton
 cd ~/some-java-project/ 
~/some-java-project/ 

# The default version of java in fresh terminal
 java -version
openjdk version "17.0.11" 2024-04-16 LTS
OpenJDK Runtime Environment Microsoft-9388408 (build 17.0.11+9-LTS)
OpenJDK 64-Bit Server VM Microsoft-9388408 (build 17.0.11+9-LTS, mixed mode, sharing)

# setup required version of java
 sdk use java 21.0.6-zulu
Using java version 21.0.6-zulu in this shell.

# create .sdkmanrc file
 sdk env init
.sdkmanrc created.

# Examining the file's contents.
 cat ./.sdkmanrc
# Enable auto-env through the sdkman_auto_env config
# Add key=value pairs of SDKs to use below
java=21.0.6-zulu

When we return to a project location in a new terminal session and run sdk env, the required JDK will be on the path, as shown in the example below:

# default java version
 java -version
openjdk version "17.0.11" 2024-04-16 LTS
OpenJDK Runtime Environment Microsoft-9388408 (build 17.0.11+9-LTS)
OpenJDK 64-Bit Server VM Microsoft-9388408 (build 17.0.11+9-LTS, mixed mode, sharing)

 cd some-java-project/
~/some-java-project/

# change JDK version to required 
 sdk env
Using java version 21.0.6-zulu in this shell.
 ~/pharaoh-projects/some-java-project/ java -version
openjdk version "21.0.6" 2025-01-21 LTS
OpenJDK Runtime Environment Zulu21.40+17-CA (build 21.0.6+7-LTS)
OpenJDK 64-Bit Server VM Zulu21.40+17-CA (build 21.0.6+7-LTS, mixed mode, sharing)

# Restore the preview version
 sdk env clear
Restored java version to 17.0.11-ms (default)

 java -version
openjdk version "17.0.11" 2024-04-16 LTS
OpenJDK Runtime Environment Microsoft-9388408 (build 17.0.11+9-LTS)
OpenJDK 64-Bit Server VM Microsoft-9388408 (build 17.0.11+9-LTS, mixed mode, sharing)
 ~/pharaoh-projects/some-java-project/

The example also shows how to restore the original version of the JDK using sdk env clear.

Store information about additional tools.

The file .sdkmanrc and the sdk env command can also be used to store information about additional tools needed for a project.

For example, if we need to use specific versions of Gradle, Ant, and Scala in the project, we can add this information in the .sdkmanrc file in the format <tool_name>=version, as shown below.

# updated version of file with required  tools
 cat ./.sdkmanrc
java=21.0.6-zulu
gradle=8.12
ant=1.10.9
scala=2.13.9

To install (or be sure) all required tools you have to run sdk env install:

# Install tools 
sdk env install

java 21.0.6-zulu is already installed.
Downloading: gradle 8.12
In progress...
######################################################################## 100.0%#=#=-#  #
Installing: gradle 8.12
Done installing!
Downloading: ant 1.10.9

In progress...
######################################################################## 100.0%
Installing: ant 1.10.9
Done installing!

scala 2.13.9 is already installed.
Using java version 21.0.6-zulu in this shell.
Using gradle version 8.12 in this shell.
Using ant version 1.10.9 in this shell.
Using scala version 2.13.9 in this shell.

The sdk env command will update $PATH for the current session.

 sdk env
Using java version 21.0.6-zulu in this shell.
Using gradle version 8.12 in this shell.
Using ant version 1.10.9 in this shell.
Using scala version 2.13.9 in this shell.

When the .sdkmanrc file is stored with the project, it makes it easy to quickly install the necessary development tools when setting up the project in a new environment or on a continuous integration (CI) system.

Example code:

git clone <my-project>
cd my-project
sdk env install
# enviroment is ready

The article explains how to use the .sdkmanrc file and SDKMAN to manage SDKs and toolchains for projects. It covers initializing the .sdkmanrc file to store specific JDK versions, using commands like `sdk env` to switch environments, and restoring original versions with `sdk env clear`. Additionally, it demonstrates adding multiple tools such as Gradle, Ant, and Scala to the .sdkmanrc file and how to install these tools with `sdk env install`. This setup is useful for quickly preparing development environments, including in CI systems.