tentackle-jlink:layers

Full name:

org.tentackle:tentackle-jlink-maven-plugin:25.20.0.0:layers

Description:

Materializes the getLayers() configuration for local development, without running the full (slow) jlink/jpackage pipeline.

Writes each declared layer's own dependencies into target/tentackle-layers/mp/<name>/ and a matching target/tentackle-layers/layers.properties, whose leaf entry points directly at the project's own compiled output (target/classes) rather than a copy of it. All paths in the generated file are absolute, so the working directory of the run configuration does not matter. This is what an IDE run/debug configuration needs to launch org.tentackle.common.LayerBootstrap locally; see the layers.md documentation for the exact run-configuration recipe.

Bind this goal to an early phase such as process-classes in projects that use getLayers(), so a plain mvn compile keeps it up to date:

  <execution>
    <goals><goal>layers</goal></goals>
  </execution>

A project without getLayers() configured does not need this goal at all.

Attributes:

Requires a Maven project to be executed.
Requires dependency resolution of artifacts in scope: runtime.
The goal is thread-safe and supports parallel builds.
Binds by default to the lifecycle phase: process-classes.

Required Parameters

Name	Type	Since	Description
`<imageDirectory>`	`File`	`-`	The directory created by jlink holding the image. Default: `${project.build.directory}/jlink`
`<layersDirectory>`	`File`	`-`	The directory to materialize the layers into. Default: `${project.build.directory}/tentackle-layers`
`<mainClass>`	`String`	`-`	The name of the main class.
`<variablesPrecedence>`	`String`	`-`	Defines the precedence of properties and variables. By default, system properties are overridden by maven properties which are overridden by the extra template variables. The case-insensitive keywords are: `system, sys`: for system properties `maven, mvn, properties, props, pom`: maven properties `variables, vars, var, extras, extra, template`: extra template variables Default: `system, maven, variables`

Optional Parameters

Name	Type	Since	Description
`<addModules>`	`List<String>`	`-`	Extra jre or jdk modules to add to the image. Useful to add the runtime localization module or extra tools in the bin-directory. Example: <addModules> <addModule>jdk.localedata</addModule> <addModule>jdk.jcmd</addModule> </addModules>
`<charset>`	`String`	`-`	The encoding to read and write files. Applied JVM-wide, see `org.tentackle.maven.AbstractTentackleMojo.determineEncoding()` . Default: `${project.build.sourceEncoding}`
`<classpathDependencies>`	`List<ClasspathDependency>`	`-`	Dependencies that should go to the classpath instead of the module-path.
`<compress>`	`String`	`-`	Compression of resources. Corresponds to the `jlink` option `--compress`, i.e. `zip-0` to `zip-9` (the legacy values `0`, `1` and `2` are deprecated since Java 21).
`<excludeModules>`	`List<String>`	`-`	Modules to exclude. Necessary only if a dependency refers to removed api even if not used at all at runtime. <excludeModules> <excludeModule>jdk8internals</excludeModule> </excludeModules>
`<extraClassifier>`	`String`	`-`	Additional classifier to add to deployed artifacts.
`<extraClasspathElements>`	`List<String>`	`-`	Extra classpath elements. Pathnames are relative to the image root.
`<extraDirectories>`	`List<File>`	`-`	Extra directories to copy to the image.
`<failOnAutomaticRequired>`	`Boolean`	`-`	Controls the behavior if an automatic module is required. default: log such modules as warnings true: log as an error and let the build fail false: log as info This flag is ignored, if a classpath application is built, i.e., no `mainModule` is given.
`<ignoreSigningInformation>`	`boolean`	`-`	Suppresses a fatal error when signed modular JARs are linked in the runtime image. Corresponds to the `jlink` option `--ignore-signing-information` Default: `false`
`<jdepsTool>`	`File`	`-`	Explicit path to the `jdeps` tool. Only if toolchains cannot be used. See also: org.tentackle.maven.AbstractTentackleMojo.getToolchain() User Property: `jdepsTool`
`<jdkToolchain>`	`Map<String,String>`	`-`	Toolchain for invocation of external tools. Explicitly specifies the `"jdk"` toolchain for this plugin only. Overrides the toolchain selected by the maven-toolchain-plugin, if any. Example: <jdkToolchain> <version>25</version> </jdkToolchain> To deselect the toolchain configured by the maven-toolchain-plugin: <jdkToolchain></jdkToolchain>
`<jlinkOptions>`	`List<String>`	`-`	Extra jlink options. Provided for platform-specific or hidden options, such as `--upgrade-files`.
`<jlinkTool>`	`File`	`-`	Explicit path to the `jlink` tool. Only if toolchains cannot be used. See also: org.tentackle.maven.AbstractTentackleMojo.getToolchain() User Property: `jlinkTool`
`<layers>`	`List<Layer>`	`-`	Named, isolated `ModuleLayer`s for dependencies that must run isolated from each other - typically because two of them need different, otherwise conflicting versions of the same module. If empty (the default), the application is built exactly as without this feature at all: a single, unlayered boot `ModuleLayer`. If not empty, `mainClass` is launched by `org.tentackle.common.LayerBootstrap` instead of directly, which builds the configured `ModuleLayer` graph at startup and then hands off to the real main class. See the `layers.md` documentation. See also: leafLayer
`<leafLayer>`	`String`	`-`	The name of the layer holding the application's own `mainModule` , used as the `leaf` entry of the generated `layers.properties`. Required if `layers` is not empty, and must not collide with any of their names.
`<mainModule>`	`String`	`-`	The name of the module holding the main class. If missing, the plugin will build an application running on the classpath.
`<minLogLevel>`	`String`	`-`	The minimum logging `java.util.logging.Level` to redirect java.util logging to the maven logger. Any name or value accepted by `java.util.logging.Level.parse(java.lang.String)` . Default: `WARNING`
`<modulePathOnly>`	`List<String>`	`-`	List of full-blown modules that should be moved to the module path explicitly. By default, all full-blown modules are passed to the jlink tool. If a module is listed for the module path only, the module will be moved to the `mp` folder instead. This may become necessary if a 3rd-party full-blown module (illegally!) requires automatic modules, which would cause all artifacts to be moved to the module path by this plugin automatically, since the jlink tool can only handle full-blown modules. Please notice that this workaround is only available for non-required modules, i.e., modules that "plug in" via the ServiceFinder or some other dependency injection mechanism. The main module of a layered application (see `layers`) is always module-path-only, without being listed here. If all modules must be moved to the `mp` folder, the single values `true`, `all` or `*` can be used as a shortcut. Examples: <modulePathOnly> <!-- kwik 0.10.9 illegally requires automatic module io.whitfin:siphash --> <module>org.tentackle.quic</module> <module>tech.kwik.core</module> </modulePathOnly> or <modulePathOnly>all</modulePathOnly>
`<noHeaderFiles>`	`boolean`	`-`	Suppress the `include` directory. Corresponds to the `jlink` option `--no-header-files`. Default: `false`
`<noManPages>`	`boolean`	`-`	Suppress the `man` directory. Corresponds to the `jlink` option `--no-man-pages` Default: `false`
`<resourcesDirectory>`	`File`	`-`	The directory holding extra resources, such as logger configurations or database credentials, that will be copied to the `conf` directory. Defaults to the maven-resources-plugin's destination directory, usually `target/classes`. If no resources must be copied, for example, in server-images for production, set this to any non-existent directory, for example `"none"`. Default: `${project.build.directory}/classes`
`<saveOpts>`	`File`	`-`	The optional file holding the jlink options. Corresponds to the `jlink` option `--save-opts`.
`<skip>`	`Boolean`	`-`	Skips processing. If not set, defaults to true if packaging is "pom" and the execution is recursive (see `org.tentackle.maven.AbstractTentackleMojo.isSkippedByDefault()` ).
`<stripDebug>`	`boolean`	`-`	Strip debug information. Corresponds to the `jlink` option `--strip-debug`. Default: `false`
`<templateDir>`	`File`	`-`	The directory holding the script templates. Default: `${project.basedir}/templates`
`<variables>`	`Map<String,Object>`	`-`	Extra variables for template or artifact generation. For example, the subproject's basedir: <variables> <project>${project.basedir}</project> </variables> And then use it in `package-image.ftl` for file paths, such as: --icon ${project}/src/pkg/myapp.ico
`<verbosity>`	`String`	`-`	The verbosity. One of "default", "info" or "debug". Other values are treated as "default". If not set, debug is turned on by Maven's global debug flag (see command line switch `-X`). Default: `${tentackle.verbosity}`
`<withUpdater>`	`boolean`	`-`	Enables the auto-update feature. For the `jlink` goal an extra update script will be generated via the `JLinkMojo.getUpdateTemplate()`. The update script will be named `bin/update.<extension>` where the extension is derived from the platform (`cmd` on Windows, otherwise `sh` for unixes). For the `jpackage` goal an extra ZIP-file is created holding the jpackage image's files and an update script generated via `getPackageUpdateTemplate()`. For an implementation of the auto-update feature see the Tentackle modules `tentackle-update` and `tentackle-fx-rdc-update`. Whereas `tentackle-update` can be used by any kind of application, the frontend part `tentackle-fx-rdc-update` requires a Tentackle FX application.
`<zipDirectory>`	`File`	`-`	The directory where to store the ZIP files. Default: `${project.build.directory}`

Parameter Details

<addModules>

Extra jre or jdk modules to add to the image.
Useful to add the runtime localization module or extra tools in the bin-directory.

Example:

<addModules>
  <addModule>jdk.localedata</addModule>
  <addModule>jdk.jcmd</addModule>
</addModules>

Type: java.util.List<java.lang.String>
Required: No

<charset>

The encoding to read and write files.
Applied JVM-wide, see org.tentackle.maven.AbstractTentackleMojo.determineEncoding() .

Type: java.lang.String
Required: No
Default: ${project.build.sourceEncoding}

<classpathDependencies>

Dependencies that should go to the classpath instead of the module-path.

Type: java.util.List<org.tentackle.maven.plugin.jlink.ClasspathDependency>
Required: No

<compress>

Compression of resources.
Corresponds to the jlink option --compress, i.e. zip-0 to zip-9 (the legacy values 0, 1 and 2 are deprecated since Java 21).

Type: java.lang.String
Required: No

<excludeModules>

Modules to exclude.
Necessary only if a dependency refers to removed api even if not used at all at runtime.

<excludeModules>
  <excludeModule>jdk8internals</excludeModule>
</excludeModules>

Type: java.util.List<java.lang.String>
Required: No

<extraClassifier>

Additional classifier to add to deployed artifacts.

Type: java.lang.String
Required: No

<extraClasspathElements>

Extra classpath elements.
Pathnames are relative to the image root.

Type: java.util.List<java.lang.String>
Required: No

<extraDirectories>

Extra directories to copy to the image.

Type: java.util.List<java.io.File>
Required: No

<failOnAutomaticRequired>

Controls the behavior if an automatic module is required.

default: log such modules as warnings
true: log as an error and let the build fail
false: log as info

This flag is ignored, if a classpath application is built, i.e., no mainModule is given.

Type: java.lang.Boolean
Required: No

<ignoreSigningInformation>

Suppresses a fatal error when signed modular JARs are linked in the runtime image.
Corresponds to the jlink option --ignore-signing-information

Type: boolean
Required: No
Default: false

<imageDirectory>

The directory created by jlink holding the image.

Type: java.io.File
Required: Yes
Default: ${project.build.directory}/jlink

<jdepsTool>

Explicit path to the jdeps tool.
Only if toolchains cannot be used.
See also: org.tentackle.maven.AbstractTentackleMojo.getToolchain()

Type: java.io.File
Required: No
User Property: jdepsTool

<jdkToolchain>

Toolchain for invocation of external tools.
Explicitly specifies the "jdk" toolchain for this plugin only. Overrides the toolchain selected by the maven-toolchain-plugin, if any.

Example:

  <jdkToolchain>
    <version>25</version>
  </jdkToolchain>

To deselect the toolchain configured by the maven-toolchain-plugin:

  <jdkToolchain></jdkToolchain>

Type: java.util.Map<java.lang.String, java.lang.String>
Required: No

<jlinkOptions>

Extra jlink options.
Provided for platform-specific or hidden options, such as --upgrade-files.

Type: java.util.List<java.lang.String>
Required: No

<jlinkTool>

Explicit path to the jlink tool.
Only if toolchains cannot be used.
See also: org.tentackle.maven.AbstractTentackleMojo.getToolchain()

Type: java.io.File
Required: No
User Property: jlinkTool

<layers>

Named, isolated ModuleLayers for dependencies that must run isolated from each other - typically because two of them need different, otherwise conflicting versions of the same module.

If empty (the default), the application is built exactly as without this feature at all: a single, unlayered boot ModuleLayer. If not empty, mainClass is launched by org.tentackle.common.LayerBootstrap instead of directly, which builds the configured ModuleLayer graph at startup and then hands off to the real main class. See the layers.md documentation.

See also: leafLayer

Type: java.util.List<org.tentackle.maven.plugin.jlink.Layer>
Required: No

<layersDirectory>

The directory to materialize the layers into.

Type: java.io.File
Required: Yes
Default: ${project.build.directory}/tentackle-layers

<leafLayer>

The name of the layer holding the application's own mainModule , used as the leaf entry of the generated layers.properties. Required if layers is not empty, and must not collide with any of their names.

Type: java.lang.String
Required: No

<mainClass>

The name of the main class.

Type: java.lang.String
Required: Yes

<mainModule>

The name of the module holding the main class.
If missing, the plugin will build an application running on the classpath.

Type: java.lang.String
Required: No

<minLogLevel>

The minimum logging java.util.logging.Level to redirect java.util logging to the maven logger.
Any name or value accepted by java.util.logging.Level.parse(java.lang.String) .

Type: java.lang.String
Required: No
Default: WARNING

<modulePathOnly>

List of full-blown modules that should be moved to the module path explicitly.
By default, all full-blown modules are passed to the jlink tool. If a module is listed for the module path only, the module will be moved to the mp folder instead.
This may become necessary if a 3rd-party full-blown module (illegally!) requires automatic modules, which would cause all artifacts to be moved to the module path by this plugin automatically, since the jlink tool can only handle full-blown modules.

Please notice that this workaround is only available for non-required modules, i.e., modules that "plug in" via the ServiceFinder or some other dependency injection mechanism.

The main module of a layered application (see layers) is always module-path-only, without being listed here.

If all modules must be moved to the mp folder, the single values true, all or * can be used as a shortcut.

Examples:

   <modulePathOnly>
       <!-- kwik 0.10.9 illegally requires automatic module io.whitfin:siphash -->
       <module>org.tentackle.quic</module>
       <module>tech.kwik.core</module>
   </modulePathOnly>

  <modulePathOnly>all</modulePathOnly>

Type: java.util.List<java.lang.String>
Required: No

<noHeaderFiles>

Suppress the include directory.
Corresponds to the jlink option --no-header-files.

Type: boolean
Required: No
Default: false

<noManPages>

Suppress the man directory.
Corresponds to the jlink option --no-man-pages

Type: boolean
Required: No
Default: false

<resourcesDirectory>

The directory holding extra resources, such as logger configurations or database credentials, that will be copied to the conf directory.
Defaults to the maven-resources-plugin's destination directory, usually target/classes.
If no resources must be copied, for example, in server-images for production, set this to any non-existent directory, for example "none".

Type: java.io.File
Required: No
Default: ${project.build.directory}/classes

<saveOpts>

The optional file holding the jlink options.
Corresponds to the jlink option --save-opts.

Type: java.io.File
Required: No

<skip>

Skips processing.
If not set, defaults to true if packaging is "pom" and the execution is recursive (see org.tentackle.maven.AbstractTentackleMojo.isSkippedByDefault() ).

Type: java.lang.Boolean
Required: No

<stripDebug>

Strip debug information.
Corresponds to the jlink option --strip-debug.

Type: boolean
Required: No
Default: false

<templateDir>

The directory holding the script templates.

Type: java.io.File
Required: No
Default: ${project.basedir}/templates

<variables>

Extra variables for template or artifact generation.

For example, the subproject's basedir:

 <variables>
   <project>${project.basedir}</project>
 </variables>

And then use it in package-image.ftl for file paths, such as:

  --icon ${project}/src/pkg/myapp.ico

Type: java.util.Map<java.lang.String, java.lang.Object>
Required: No

<variablesPrecedence>

Defines the precedence of properties and variables.
By default, system properties are overridden by maven properties which are overridden by the extra template variables.

The case-insensitive keywords are:

system, sys: for system properties
maven, mvn, properties, props, pom: maven properties
variables, vars, var, extras, extra, template: extra template variables

Type: java.lang.String
Required: Yes
Default: system, maven, variables

<verbosity>

The verbosity.
One of "default", "info" or "debug". Other values are treated as "default".
If not set, debug is turned on by Maven's global debug flag (see command line switch -X).

Type: java.lang.String
Required: No
Default: ${tentackle.verbosity}

<withUpdater>

Enables the auto-update feature.

For the jlink goal an extra update script will be generated via the JLinkMojo.getUpdateTemplate(). The update script will be named bin/update.<extension> where the extension is derived from the platform (cmd on Windows, otherwise sh for unixes).

For the jpackage goal an extra ZIP-file is created holding the jpackage image's files and an update script generated via getPackageUpdateTemplate().

For an implementation of the auto-update feature see the Tentackle modules tentackle-update and tentackle-fx-rdc-update. Whereas tentackle-update can be used by any kind of application, the frontend part tentackle-fx-rdc-update requires a Tentackle FX application.

Type: boolean
Required: No

<zipDirectory>

The directory where to store the ZIP files.

Type: java.io.File
Required: No
Default: ${project.build.directory}