Jlink to create a custom jvm image

About

The jlink tool allows the creation of a modular run-time images that contains only the required modules (ie a subset of the standard and JDK modules) reducing significantly the size of a bundled runtime image.

Without Jlink, full image (non-modular) such as JREs were copied and unneeded portions were deleted from the copy

It is a module linker tool that:

link, assemble and optimize a set of modules (and their transitive dependences)
into a modular custom run-time image (ie create a modular runtime image)

Link Time

link time is an optional phase between the phases of compile time (the javac command) and run-time (the java run-time launcher).

Link time requires a linking tool that will assemble and optimize a set of modules and their transitive dependencies to create a run-time image or executable

Optimization

Link time is an opportunity to do whole-world optimizations that are otherwise difficult at compile time or costly at run-time.

Example of optimization:

optimize a computation when all its inputs become constant (i.e., not unknown).
remove code that is no longer reachable.

Syntax

jlink \
    --module-path <modulepath> \
    --add-modules <modules> \
    --limit-modules <modules> \
    --output <path> # location of the runtime image created

where:

module-path is the path where observable modules will be discovered by the linker; these can be modular JAR files, JMOD files, or exploded modules - The module path consists of paths to the libraries, JDK modules and the application module.
add-modules names the modules to add to the run-time image; these modules can, via transitive dependencies, cause additional modules to be added
limit-modules limits the universe of observable modules
output is the directory that will contain the resulting run-time image
help to print a usage/help message
version to print version information

The module-path, add-modules, and limit-modules options are described in further detail in JEP 261.

Image Directory Layout

The generated image will have the following directory layout

├── LICENSE
├── README
├── bin
│   ├── app
│   ├── app.bat
│   ├── java
│   └── keytool
└── conf
│    └── /* Java runtime */
└── legal
│    └── /* Java runtime */
└── lib
│    └── /* Java runtime */
└── release

Extension / Plugin

The jlink tool includes a plugin and extension mechanism.

Example

Creating an runtime image tailored to your application

With jdeps, find all java modules required

jdeps \
   --multi-release 11 \ # in a multi-release jar, use the 11
   --print-module-deps \ # output the java module dependency for use in jlink
   --ignore-missing-deps \ # ignore missing deps
   -quiet \ # no warning message
   .\*.jar # only jar as input (all runtime jar are present in the working directory)

Example of output:

java.base,java.compiler,java.desktop,java.management,java.prefs,java.rmi,java.security.sasl,java.sql.rowset,jdk.jdi,jdk.scripting.nashorn,jdk.security.jgss,jdk.unsupported,jdk.xml.dom

Create a modular runtime environment based only on this modules

jlink \
    --no-header-files \
    --no-man-pages \
    --add-modules java.base,java.compiler,java.desktop,java.management,java.prefs,java.rmi,java.security.sasl,java.sql.rowset,jdk.jdi,jdk.scripting.nashorn,jdk.security.jgss,jdk.unsupported,jdk.xml.dom \
    --output runtime-current-os

You get then a runtime image that you can bundle into your application

ls runtime-current-os

bin  conf  legal  lib  release

Release file content is:

cat runtime-current-os/release

JAVA_VERSION="11.0.12"
MODULES="java.base java.compiler java.datatransfer java.xml java.prefs java.desktop java.logging java.management java.security.sasl java.naming java.rmi java.scripting java.security.jgss java.transaction.xa java.sql java.sql.rowset jdk.internal.jvmstat jdk.attach jdk.dynalink jdk.jdwp.agent jdk.jdi jdk.scripting.nashorn jdk.security.jgss jdk.unsupported jdk.xml.dom"

Create an image that runs on other system (cross targeting)

The jlink tool can create a run-time image for another platform (cross targeting)

jlink --module-path $TARGET/jmods  ....

where TARGET is the location of the directory where the JDK for the target system was unzipped the JDK

Example on Windows after downloading a JDK for x64 linux

jlink ^
    --no-header-files ^
    --no-man-pages ^
    --module-path C:\jdk\jdk-11.0.12+7-x64-linux\jmods ^
    --add-modules java.base,java.compiler,java.desktop,java.management,java.prefs,java.rmi,java.security.sasl,java.sql.rowset,jdk.jdi,jdk.scripting.nashorn,jdk.security.jgss,jdk.unsupported,jdk.xml.dom ^
    --output runtime-linux

With docker

You can use docker image to create image for other platform.

Example: Es4x Jlink

Documentation / Reference

jep 282