440 lines
12 KiB
Groff
440 lines
12 KiB
Groff
.\" Copyright (c) 1994, 2019, Oracle and/or its affiliates. All rights reserved.
|
|
.\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
|
.\"
|
|
.\" This code is free software; you can redistribute it and/or modify it
|
|
.\" under the terms of the GNU General Public License version 2 only, as
|
|
.\" published by the Free Software Foundation.
|
|
.\"
|
|
.\" This code is distributed in the hope that it will be useful, but WITHOUT
|
|
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
.\" version 2 for more details (a copy is included in the LICENSE file that
|
|
.\" accompanied this code).
|
|
.\"
|
|
.\" You should have received a copy of the GNU General Public License version
|
|
.\" 2 along with this work; if not, write to the Free Software Foundation,
|
|
.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
|
.\"
|
|
.\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
|
.\" or visit www.oracle.com if you need additional information or have any
|
|
.\" questions.
|
|
.\"
|
|
.\" Automatically generated by Pandoc 2.3.1
|
|
.\"
|
|
.TH "JMOD" "1" "2020" "JDK 14" "JDK Commands"
|
|
.hy
|
|
.SH NAME
|
|
.PP
|
|
jmod \- create JMOD files and list the content of existing JMOD files
|
|
.SH SYNOPSIS
|
|
.PP
|
|
\f[CB]jmod\f[R]
|
|
(\f[CB]create\f[R]|\f[CB]extract\f[R]|\f[CB]list\f[R]|\f[CB]describe\f[R]|\f[CB]hash\f[R])
|
|
[\f[I]options\f[R]] \f[I]jmod\-file\f[R]
|
|
.PP
|
|
Includes the following:
|
|
.PP
|
|
\f[B]Main operation modes\f[R]
|
|
.TP
|
|
.B \f[CB]create\f[R]
|
|
Creates a new JMOD archive file.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]extract\f[R]
|
|
Extracts all the files from the JMOD archive file.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]list\f[R]
|
|
Prints the names of all the entries.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]describe\f[R]
|
|
Prints the module details.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]hash\f[R]
|
|
Determines leaf modules and records the hashes of the dependencies that
|
|
directly and indirectly require them.
|
|
.RS
|
|
.RE
|
|
.PP
|
|
\f[B]Options\f[R]
|
|
.TP
|
|
.B \f[I]options\f[R]
|
|
See \f[B]Options for jmod\f[R].
|
|
.RS
|
|
.RE
|
|
.PP
|
|
\f[B]Required\f[R]
|
|
.TP
|
|
.B \f[I]jmod\-file\f[R]
|
|
Specifies the name of the JMOD file to create or from which to retrieve
|
|
information.
|
|
.RS
|
|
.RE
|
|
.SH DESCRIPTION
|
|
.PP
|
|
\f[B]Note:\f[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 \f[CB]jmod\f[R] tool is intended for modules that have native
|
|
libraries or other configuration files or for modules that you intend to
|
|
link, with the \f[B]jlink\f[R] tool, to a runtime image.
|
|
.PP
|
|
The JMOD file format lets you aggregate files other than
|
|
\f[CB]\&.class\f[R] 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.
|
|
.PP
|
|
Many \f[CB]jmod\f[R] 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 \f[CB]\-\-exclude\f[R] option.
|
|
.PP
|
|
With the \f[CB]\-\-hash\-modules\f[R] option or the \f[CB]jmod\ hash\f[R]
|
|
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 "tying"
|
|
together these modules.
|
|
This enables a package to be exported to one or more specifically\-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.
|
|
.SH OPTIONS FOR JMOD
|
|
.TP
|
|
.B \f[CB]\-\-class\-path\f[R] \f[I]path\f[R]
|
|
Specifies the location of application JAR files or a directory
|
|
containing classes to copy into the resulting JMOD file.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-cmds\f[R] \f[I]path\f[R]
|
|
Specifies the location of native commands to copy into the resulting
|
|
JMOD file.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-config\f[R] \f[I]path\f[R]
|
|
Specifies the location of user\-editable configuration files to copy
|
|
into the resulting JMOD file.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-dir\f[R] \f[I]path\f[R]
|
|
Specifies the location where \f[CB]jmod\f[R] puts extracted files from the
|
|
specified JMOD archive.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-dry\-run\f[R]
|
|
Performs a dry run of hash mode.
|
|
It identifies leaf modules and their required modules without recording
|
|
any hash values.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-exclude\f[R] \f[I]pattern\-list\f[R]
|
|
Excludes files matching the supplied comma\-separated pattern list, each
|
|
element using one the following forms:
|
|
.RS
|
|
.IP \[bu] 2
|
|
\f[I]glob\-pattern\f[R]
|
|
.IP \[bu] 2
|
|
\f[CB]glob:\f[R]\f[I]glob\-pattern\f[R]
|
|
.IP \[bu] 2
|
|
\f[CB]regex:\f[R]\f[I]regex\-pattern\f[R]
|
|
.PP
|
|
See the \f[B]\f[BC]FileSystem.getPathMatcher\f[B]\f[R] method for the
|
|
syntax of \f[I]glob\-pattern\f[R].
|
|
See the \f[B]\f[BC]Pattern\f[B]\f[R] class for the syntax of
|
|
\f[I]regex\-pattern\f[R], which represents a regular expression.
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-hash\-modules\f[R] \f[I]regex\-pattern\f[R]
|
|
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 \f[I]regex\-pattern\f[R].
|
|
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
|
|
\f[CB]jmod\ hash\f[R] command.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-header\-files\f[R] \f[I]path\f[R]
|
|
Specifies the location of header files to copy into the resulting JMOD
|
|
file.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-help\f[R] or \f[CB]\-h\f[R]
|
|
Prints a usage message.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-help\-extra\f[R]
|
|
Prints help for extra options.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-legal\-notices\f[R] \f[I]path\f[R]
|
|
Specifies the location of legal notices to copy into the resulting JMOD
|
|
file.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-libs\f[R] \f[I]path\f[R]
|
|
Specifies location of native libraries to copy into the resulting JMOD
|
|
file.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-main\-class\f[R] \f[I]class\-name\f[R]
|
|
Specifies main class to record in the module\-info.class file.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-man\-pages\f[R] \f[I]path\f[R]
|
|
Specifies the location of man pages to copy into the resulting JMOD
|
|
file.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-module\-version\f[R] \f[I]module\-version\f[R]
|
|
Specifies the module version to record in the module\-info.class file.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-module\-path\f[R] \f[I]path\f[R] or \f[CB]\-p\f[R] \f[I]path\f[R]
|
|
Specifies the module path.
|
|
This option is required if you also specify \f[CB]\-\-hash\-modules\f[R].
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-target\-platform\f[R] \f[I]platform\f[R]
|
|
Specifies the target platform.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-version\f[R]
|
|
Prints version information of the \f[CB]jmod\f[R] tool.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\@\f[R]\f[I]filename\f[R]
|
|
Reads options from the specified file.
|
|
.RS
|
|
.PP
|
|
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 (\f[CB]#\f[R]) to the
|
|
beginning of the line.
|
|
.PP
|
|
The following is an example of an options file for the \f[CB]jmod\f[R]
|
|
command:
|
|
.IP
|
|
.nf
|
|
\f[CB]
|
|
#Wed\ Dec\ 07\ 00:40:19\ EST\ 2016
|
|
create\ \-\-class\-path\ mods/com.greetings\ \-\-module\-path\ mlib
|
|
\ \ \-\-cmds\ commands\ \-\-config\ configfiles\ \-\-header\-files\ src/h
|
|
\ \ \-\-libs\ lib\ \-\-main\-class\ com.greetings.Main
|
|
\ \ \-\-man\-pages\ man\ \-\-module\-version\ 1.0
|
|
\ \ \-\-os\-arch\ "x86_x64"\ \-\-os\-name\ "Mac\ OS\ X"
|
|
\ \ \-\-os\-version\ "10.10.5"\ greetingsmod
|
|
\f[R]
|
|
.fi
|
|
.RE
|
|
.SH EXTRA OPTIONS FOR JMOD
|
|
.PP
|
|
In addition to the options described in \f[B]Options for jmod\f[R], the
|
|
following are extra options that can be used with the command.
|
|
.TP
|
|
.B \f[CB]\-\-do\-not\-resolve\-by\-default\f[R]
|
|
Exclude from the default root set of modules
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-warn\-if\-resolved\f[R]
|
|
Hint for a tool to issue a warning if the module is resolved.
|
|
One of deprecated, deprecated\-for\-removal, or incubating.
|
|
.RS
|
|
.RE
|
|
.SH JMOD CREATE EXAMPLE
|
|
.PP
|
|
The following is an example of creating a JMOD file:
|
|
.IP
|
|
.nf
|
|
\f[CB]
|
|
jmod\ create\ \-\-class\-path\ mods/com.greetings\ \-\-cmds\ commands
|
|
\ \ \-\-config\ configfiles\ \-\-header\-files\ src/h\ \-\-libs\ lib
|
|
\ \ \-\-main\-class\ com.greetings.Main\ \-\-man\-pages\ man\ \-\-module\-version\ 1.0
|
|
\ \ \-\-os\-arch\ "x86_x64"\ \-\-os\-name\ "Mac\ OS\ X"
|
|
\ \ \-\-os\-version\ "10.10.5"\ greetingsmod
|
|
\f[R]
|
|
.fi
|
|
.SH JMOD HASH EXAMPLE
|
|
.PP
|
|
The following example demonstrates what happens when you try to link a
|
|
leaf module (in this example, \f[CB]ma\f[R]) with a required module
|
|
(\f[CB]mb\f[R]), and the hash value recorded in the required module
|
|
doesn\[aq]t match that of the leaf module.
|
|
.IP "1." 3
|
|
Create and compile the following \f[CB]\&.java\f[R] files:
|
|
.RS 4
|
|
.IP \[bu] 2
|
|
\f[CB]jmodhashex/src/ma/module\-info.java\f[R]
|
|
.RS 2
|
|
.IP
|
|
.nf
|
|
\f[CB]
|
|
module\ ma\ {
|
|
\ \ requires\ mb;
|
|
}
|
|
\f[R]
|
|
.fi
|
|
.RE
|
|
.IP \[bu] 2
|
|
\f[CB]jmodhashex/src/mb/module\-info.java\f[R]
|
|
.RS 2
|
|
.IP
|
|
.nf
|
|
\f[CB]
|
|
module\ mb\ {
|
|
}
|
|
\f[R]
|
|
.fi
|
|
.RE
|
|
.IP \[bu] 2
|
|
\f[CB]jmodhashex2/src/ma/module\-info.java\f[R]
|
|
.RS 2
|
|
.IP
|
|
.nf
|
|
\f[CB]
|
|
module\ ma\ {
|
|
\ \ requires\ mb;
|
|
}
|
|
\f[R]
|
|
.fi
|
|
.RE
|
|
.IP \[bu] 2
|
|
\f[CB]jmodhashex2/src/mb/module\-info.java\f[R]
|
|
.RS 2
|
|
.IP
|
|
.nf
|
|
\f[CB]
|
|
module\ mb\ {
|
|
}
|
|
\f[R]
|
|
.fi
|
|
.RE
|
|
.RE
|
|
.IP "2." 3
|
|
Create a JMOD archive for each module.
|
|
Create the directories \f[CB]jmodhashex/jmods\f[R] and
|
|
\f[CB]jmodhashex2/jmods\f[R], and then run the following commands from the
|
|
\f[CB]jmodhashex\f[R] directory, then from the \f[CB]jmodhashex2\f[R]
|
|
directory:
|
|
.RS 4
|
|
.IP \[bu] 2
|
|
\f[CB]jmod\ create\ \-\-class\-path\ mods/ma\ jmods/ma.jmod\f[R]
|
|
.IP \[bu] 2
|
|
\f[CB]jmod\ create\ \-\-class\-path\ mods/mb\ jmods/mb.jmod\f[R]
|
|
.RE
|
|
.IP "3." 3
|
|
Optionally preview the \f[CB]jmod\ hash\f[R] command.
|
|
Run the following command from the \f[CB]jmodhashex\f[R] directory:
|
|
.RS 4
|
|
.PP
|
|
\f[CB]jmod\ hash\ \-\-dry\-run\ \-module\-path\ jmods\ \-\-hash\-modules\ .*\f[R]
|
|
.PP
|
|
The command prints the following:
|
|
.IP
|
|
.nf
|
|
\f[CB]
|
|
Dry\ run:
|
|
mb
|
|
\ \ hashes\ ma\ SHA\-256\ 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
This indicates that the \f[CB]jmod\ hash\f[R] command (without the
|
|
\f[CB]\-\-dry\-run\f[R] option) will record the hash value of the leaf
|
|
module \f[CB]ma\f[R] in the module \f[CB]mb\f[R].
|
|
.RE
|
|
.IP "4." 3
|
|
Record hash values in the JMOD archive files contained in the
|
|
\f[CB]jmodhashex\f[R] directory.
|
|
Run the following command from the \f[CB]jmodhashex\f[R] directory:
|
|
.RS 4
|
|
.RS
|
|
.PP
|
|
\f[CB]jmod\ hash\ \-\-module\-path\ jmods\ \-\-hash\-modules\ .*\f[R]
|
|
.RE
|
|
.PP
|
|
The command prints the following:
|
|
.RS
|
|
.PP
|
|
\f[CB]Hashes\ are\ recorded\ in\ module\ mb\f[R]
|
|
.RE
|
|
.RE
|
|
.IP "5." 3
|
|
Print information about each JMOD archive contained in the
|
|
\f[CB]jmodhashex\f[R] directory.
|
|
Run the highlighted commands from the \f[CB]jmodhashex\f[R] directory:
|
|
.RS 4
|
|
.IP
|
|
.nf
|
|
\f[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\ SHA\-256\ 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a
|
|
\f[R]
|
|
.fi
|
|
.RE
|
|
.IP "6." 3
|
|
Attempt to create a runtime image that contains the module \f[CB]ma\f[R]
|
|
from the directory \f[CB]jmodhashex2\f[R] but the module \f[CB]mb\f[R] from
|
|
the directory \f[CB]jmodhashex\f[R].
|
|
Run the following command from the \f[CB]jmodhashex2\f[R] directory:
|
|
.RS 4
|
|
.IP \[bu] 2
|
|
\f[B]Oracle Solaris, Linux, and OS X:\f[R]
|
|
.RS 2
|
|
.RS
|
|
.PP
|
|
\f[CB]jlink\ \-\-module\-path\ $JAVA_HOME/jmods:jmods/ma.jmod:../jmodhashex/jmods/mb.jmod\ \-\-add\-modules\ ma\ \-\-output\ ma\-app\f[R]
|
|
.RE
|
|
.RE
|
|
.IP \[bu] 2
|
|
\f[B]Windows:\f[R]
|
|
.RS 2
|
|
.RS
|
|
.PP
|
|
\f[CB]jlink\ \-\-module\-path\ %JAVA_HOME%/jmods;jmods/ma.jmod;../jmodhashex/jmods/mb.jmod\ \-\-add\-modules\ ma\ \-\-output\ ma\-app\f[R]
|
|
.RE
|
|
.RE
|
|
.PP
|
|
The command prints an error message similar to the following:
|
|
.IP
|
|
.nf
|
|
\f[CB]
|
|
Error:\ Hash\ of\ ma\ (a2d77889b0cb067df02a3abc39b01ac1151966157a68dc4241562c60499150d2)\ differs\ to
|
|
expected\ hash\ (07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a)\ recorded\ in\ mb
|
|
\f[R]
|
|
.fi
|
|
.RE
|