JMOD

NAME

jmod- create JMOD files and list the content of existing JMOD files  

SYNOPSIS

V]jmodR] (V]createR]|V]extractR]|V]listR]|V]describeR]|V]hashR]) [I]optionsR]] I]jmo-fileR]

Includes the following:

B]Main operation modesR]

V]createR]

Creates a new JMOD archive file.

V]extractR]

Extracts all the files from the JMOD archive file.

V]listR]

Prints the names of all the entries.

V]describeR]

Prints the module details.

V]hashR]

Determines leaf modules and records the hashes of the dependencies that directly and indirectly require them.

B]OptionsR]

I]optionsR]

See B]Options for jmodR].

B]RequiredR]

I]jmo-fileR]

Specifies the name of the JMOD file to create or from which to retrieve information.

DESCRIPTION

B]Note:R] For most development tasks, including deploying modules on the module path or publishing them to a Maven repository, continue to package modules in modular JAR files. The V]jmodR] tool is intended for modules that have native libraries or other configuration files or for modules that you intend to link, with the B]jlinkR] tool, to a runtime image.

The JMOD file format lets you aggregate files other than V].classR] files, metadata, and resources. This format is transportable but not executable, which means that you can use it during compile time or link time but not at run time.

Many V]jmodR] options involve specifying a path whose contents are copied into the resulting JMOD files. These options copy all the contents of the specified path, including subdirectories and their contents, but exclude files whose names match the pattern specified by the V-excludeR] option.

With the V-has-modulesR] option or the V]jmod hashR] command, you can, in each module[aq]s descriptor, record hashes of the content of the modules that are allowed to depend upon it, thus [dq]tying[dq] together these modules. This enables a package to be exported to one or more specificall-named modules and to no others through qualified exports. The runtime verifies if the recorded hash of a module matches the one resolved at run time; if not, the runtime returns an error.  

OPTIONS FOR JMOD

V-clas-pathR] I]pathR]

Specifies the location of application JAR files or a directory containing classes to copy into the resulting JMOD file.

V-cmdsR] I]pathR]

Specifies the location of native commands to copy into the resulting JMOD file.

V-compressR] I]compressR]

Specifies the compression to use in creating the JMOD file. The accepted values are V]zi-[-9]R], where V]zi-0R] provides no compression, and V]zi-9R] provides the best compression. Default is V]zi-6R].

V-configR] I]pathR]

Specifies the location of use-editable configuration files to copy into the resulting JMOD file.

V-dateR]I]TIMESTAMPR]

The timestamp in IS-8601 extended offset dat-time with optional tim-zone format, to use for the timestamp of the entries, e.g. [dq]202-0-12T12:30:0-05:00[dq].

V-dirR] I]pathR]

Specifies the location where V]jmodR] puts extracted files from the specified JMOD archive.

V-dr-runR]

Performs a dry run of hash mode. It identifies leaf modules and their required modules without recording any hash values.

V-excludeR] I]patter-listR]

Excludes files matching the supplied comm-separated pattern list, each element using one the following forms:

[bu]

I]glo-patternR]

[bu]

V]glob:R]I]glo-patternR]

[bu]

V]regex:R]I]rege-patternR]

See the B]VB]FileSystem.getPathMatcherB]R] method for the syntax of I]glo-patternR]. See the B]VB]PatternB]R] class for the syntax of I]rege-patternR], which represents a regular expression.

V-has-modulesR] I]rege-patternR]

Determines the leaf modules and records the hashes of the dependencies directly and indirectly requiring them, based on the module graph of the modules matching the given I]rege-patternR]. The hashes are recorded in the JMOD archive file being created, or a JMOD archive or modular JAR on the module path specified by the V]jmod hashR] command.

V-heade-filesR] I]pathR]

Specifies the location of header files to copy into the resulting JMOD file.

V-helpR] or V-hR]

Prints a usage message.

V-hel-extraR]

Prints help for extra options.

V-lega-noticesR] I]pathR]

Specifies the location of legal notices to copy into the resulting JMOD file.

V-libsR] I]pathR]

Specifies location of native libraries to copy into the resulting JMOD file.

V-mai-classR] I]clas-nameR]

Specifies main class to record in the modul-info.class file.

V-ma-pagesR] I]pathR]

Specifies the location of man pages to copy into the resulting JMOD file.

V-modul-versionR] I]modul-versionR]

Specifies the module version to record in the modul-info.class file.

V-modul-pathR] I]pathR] or V-pR] I]pathR]

Specifies the module path. This option is required if you also specify V-has-modulesR].

V-targe-platformR] I]platformR]

Specifies the target platform.

V-versionR]

Prints version information of the V]jmodR] tool.

V][at]R]I]filenameR]

Reads options from the specified file.

An options file is a text file that contains the options and values that you would ordinarily enter in a command prompt. Options may appear on one line or on several lines. You may not specify environment variables for path names. You may comment out lines by prefixinga hash symbol (V]#R]) to the beginning of the line.

The following is an example of an options file for the V]jmodR] command:

CB]
#Wed Dec 07 00:40:19 EST 2016
create-clas-path mods/com.greetings-modul-path mlib
 -cmds commands-config configfiles-heade-files src/h
 -libs lib-mai-class com.greetings.Main
 -ma-pages man-modul-version 1.0
 -o-arch [dq]x86_x64[dq]-o-name [dq]macOS[dq]
 -o-version [dq]10.10.5[dq] greetingsmod
R]

EXTRA OPTIONS FOR JMOD

In addition to the options described in B]Options for jmodR], the following are extra options that can be used with the command.

V-d-no-resolv-b-defaultR]

Exclude from the default root set of modules

V-war-i-resolvedR]

Hint for a tool to issue a warning if the module is resolved. One of deprecated, deprecate-fo-removal, or incubating.

JMOD CREATE EXAMPLE

The following is an example of creating a JMOD file:

CB]
jmod create-clas-path mods/com.greetings-cmds commands
 -config configfiles-heade-files src/h-libs lib
 -mai-class com.greetings.Main-ma-pages man-modul-version 1.0
 -o-arch [dq]x86_x64[dq]-o-name [dq]macOS[dq]
 -o-version [dq]10.10.5[dq] greetingsmod
R]

Create a JMOD file specifying the date for the entries as V]2022 March 15 00:00:00R]:

CB]
jmod create-clas-path build/foo/classes-date 202-0-15T00:00:00Z
   jmods/foo1.jmod
R]

JMOD HASH EXAMPLE

The following example demonstrates what happens when you try to link a leaf module (in this example, V]maR]) with a required module (V]mbR]), and the hash value recorded in the required module doesn[aq]t match that of the leaf module.

1.

Create and compile the following V].javaR] files:

[bu]

V]jmodhashex/src/ma/modul-info.javaR]

CB]
module ma {
  requires mb;
}
R]

[bu]

V]jmodhashex/src/mb/modul-info.javaR]

CB]
module mb {
}
R]

[bu]

V]jmodhashex2/src/ma/modul-info.javaR]

CB]
module ma {
  requires mb;
}
R]

[bu]

V]jmodhashex2/src/mb/modul-info.javaR]

CB]
module mb {
}
R]

2.

Create a JMOD archive for each module. Create the directories V]jmodhashex/jmodsR] and V]jmodhashex2/jmodsR], and then run the following commands from the V]jmodhashexR] directory, then from the V]jmodhashex2R] directory:

[bu]

V]jmod create-clas-path mods/ma jmods/ma.jmodR]

[bu]

V]jmod create-clas-path mods/mb jmods/mb.jmodR]

3.

Optionally preview the V]jmod hashR] command. Run the following command from the V]jmodhashexR] directory:

V]jmod hash-dr-run-modul-path jmods-has-modules .*R]

The command prints the following:

CB]
Dry run:
mb
  hashes ma SH-256 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a
R]

This indicates that the V]jmod hashR] command (without the V-dr-runR] option) will record the hash value of the leaf module V]maR] in the module V]mbR].

4.

Record hash values in the JMOD archive files contained in the V]jmodhashexR] directory. Run the following command from the V]jmodhashexR] directory:

V]jmod hash-modul-path jmods-has-modules .*R]

The command prints the following:

V]Hashes are recorded in module mbR]

5.

Print information about each JMOD archive contained in the V]jmodhashexR] directory. Run the highlighted commands from the V]jmodhashexR] directory:

CB]
jmod describe jmods/ma.jmod

ma
  requires mandated java.base
  requires mb

jmod describe jmods/mb.jmod

mb
  requires mandated java.base
  hashes ma SH-256 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a
R]

6.

Attempt to create a runtime image that contains the module V]maR] from the directory V]jmodhashex2R] but the module V]mbR] from the directory V]jmodhashexR]. Run the following command from the V]jmodhashex2R] directory:

[bu]

B]Linux and macOS:R]

V]jlink-modul-path $JAVA_HOME/jmods:jmods/ma.jmod:../jmodhashex/jmods/mb.jmod-ad-modules ma-output m-appR]

[bu]

B]Windows:R]

V]jlink-modul-path %JAVA_HOME%/jmods;jmods/ma.jmod;../jmodhashex/jmods/mb.jmod-ad-modules ma-output m-appR]

The command prints an error message similar to the following:

CB]
Error: Hash of ma (a2d77889b0cb067df02a3abc39b01ac1151966157a68dc4241562c60499150d2) differs to
expected hash (07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a) recorded in mb
R]

Index

NAME

SYNOPSIS

DESCRIPTION

OPTIONS FOR JMOD

EXTRA OPTIONS FOR JMOD

JMOD CREATE EXAMPLE

JMOD HASH EXAMPLE