Jlink to create a custom jvm image

Java Conceptuel Diagram

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 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





Discover More
How to bundle a jvm in a Gradle application targeting Windows, Linux or Macos

The gradle application plugin does not give the possibility to embed a jvm. This page shows how to do with a minimal knowledge of Gradle code
Java Conceptuel Diagram
Java - Module

A Java module is a packaging format that create a modular JAR file. It's a feature of JDK 9 from the Java Platform Module System (JPMS) that divide the monolithic rt.jar and tools.jar files into 75 distinct...
Java Conceptuel Diagram
Java - Runtime Image

A runtime image permits to run Java class and have then at minimal a jvm (ie java) Prior to Java 9, there was only two fix run-time image JRE (a complete Java SE Platform implementation) JDK...



Share this page:
Follow us:
Task Runner