JEP 282: jlink: The Java Linker

AuthorJean-Francois Denise
OwnerJim Laskey
Created2015/07/16 12:55
Updated2016/11/29 17:57
TypeFeature
StatusCompleted
Componenttools / jlink
ScopeJDK
Discussionjigsaw dash dev at openjdk dot java dot net
EffortL
DurationL
Priority2
Reviewed byAlan Bateman, Alex Buckley, Iris Clark, Jim Laskey, Mandy Chung, Mark Reinhold
Endorsed byBrian Goetz
Release9
Issue8131679
DependsJEP 261: Module System
Relates toJEP 220: Modular Run-Time Images
JEP 275: Modular Java Application Packaging

Summary

Create a tool that can assemble and optimize a set of modules and their dependencies into a custom run-time image as defined in JEP 220. Define a plugin mechanism for transformation and optimization during the assembly process, and for the generation of alternative image formats.

Non Goals

This JEP does not commit the resulting tool to generate anything other than a modular run-time image. The plugin mechanism can be used to generate other image formats.

It is not a goal of this JEP to define a standard or supported API for plugins. Instead, the plugin API will be strictly experimental. A future JEP may re-visit this topic once experience has been obtained using the plugin API defined by this JEP.

Motivation

JEP 261 defines link time as 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.

Link time is an opportunity to do whole-world optimizations that are otherwise difficult at compile time or costly at runtime. An example would be to optimize a computation when all its inputs become constant (i.e., not unknown). A follow-up optimization would be to remove code that is no longer reachable.

Description

A basic invocation of the linker tool, jlink, is:

$ jlink --module-path <modulepath> --add-modules <modules> --limit-modules <modules> --output <path>

where:

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

Other options that jlink will support include:

Plugins

The plugin API will be strictly experimental and may be the subject of a future JEP.

jlink gathers the classes, native libraries, and configuration files into a set of resources. These resources are fed through a pipeline of transformers, which are defined by plugins. Each transformer may transform the resources into new resources before they are fed to the next transformation in the pipeline. After all transformers have been applied, the tool feeds the final set of resources to an image builder.

Example built-in plugins that jlink will provide:

Other plugins that may be developed:

Plugins are packaged as modules and placed on the plugin module path, which is specified by the --plugins-module-path option. Plugins can add command-line options to jlink so that they can be enabled and configured. For example, the strip debug plugin adds the option --strip-java-debug to the command-line interface.

Open design issues

Alternatives

The alternative to a linking tool is to use platform-specific JDK and JRE image-build scripts. This approach would make it difficult to create custom run-time images.

Testing

Beyond the expected set of unit tests to exercise the tool and the experimental plugin API, the JDK build will regularly exercise jlink by creating the JDK and JRE run-time images.

Risks and Assumptions

The set of requirements for the tool is not complete at this time. The tool's extensibility is expected to evolve.

Dependences