jdk

1
.\" Copyright (c) 2017, 2023, Oracle and/or its affiliates. All rights reserved.
2
.\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
3
.\"
4
.\" This code is free software; you can redistribute it and/or modify it
5
.\" under the terms of the GNU General Public License version 2 only, as
6
.\" published by the Free Software Foundation.
7
.\"
8
.\" This code is distributed in the hope that it will be useful, but WITHOUT
9
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
10
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
11
.\" version 2 for more details (a copy is included in the LICENSE file that
12
.\" accompanied this code).
13
.\"
14
.\" You should have received a copy of the GNU General Public License version
15
.\" 2 along with this work; if not, write to the Free Software Foundation,
16
.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
17
.\"
18
.\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
19
.\" or visit www.oracle.com if you need additional information or have any
20
.\" questions.
21
.\"
22
.\" Automatically generated by Pandoc 2.19.2
23
.\"
24
.\" Define V font for inline verbatim, using C font in formats
25
.\" that render this, and otherwise B font.
26
.ie "\f[CB]x\f[R]"x" \{\
27
. ftr V B
28
. ftr VI BI
29
. ftr VB B
30
. ftr VBI BI
31
.\}
32
.el \{\
33
. ftr V CR
34
. ftr VI CI
35
. ftr VB CB
36
. ftr VBI CBI
37
.\}
38
.TH "JMOD" "1" "2025" "JDK 24-ea" "JDK Commands"
39
.hy
40
.SH NAME
41
.PP
42
jmod - create JMOD files and list the content of existing JMOD files
43
.SH SYNOPSIS
44
.PP
45
\f[V]jmod\f[R]
46
(\f[V]create\f[R]|\f[V]extract\f[R]|\f[V]list\f[R]|\f[V]describe\f[R]|\f[V]hash\f[R])
47
[\f[I]options\f[R]] \f[I]jmod-file\f[R]
48
.PP
49
Includes the following:
50
.PP
51
\f[B]Main operation modes\f[R]
52
.TP
53
\f[V]create\f[R]
54
Creates a new JMOD archive file.
55
.TP
56
\f[V]extract\f[R]
57
Extracts all the files from the JMOD archive file.
58
.TP
59
\f[V]list\f[R]
60
Prints the names of all the entries.
61
.TP
62
\f[V]describe\f[R]
63
Prints the module details.
64
.TP
65
\f[V]hash\f[R]
66
Determines leaf modules and records the hashes of the dependencies that
67
directly and indirectly require them.
68
.PP
69
\f[B]Options\f[R]
70
.TP
71
\f[I]options\f[R]
72
See \f[B]Options for jmod\f[R].
73
.PP
74
\f[B]Required\f[R]
75
.TP
76
\f[I]jmod-file\f[R]
77
Specifies the name of the JMOD file to create or from which to retrieve
78
information.
79
.SH DESCRIPTION
80
.PP
81
\f[B]Note:\f[R] For most development tasks, including deploying modules
82
on the module path or publishing them to a Maven repository, continue to
83
package modules in modular JAR files.
84
The \f[V]jmod\f[R] tool is intended for modules that have native
85
libraries or other configuration files or for modules that you intend to
86
link, with the \f[B]jlink\f[R] tool, to a runtime image.
87
.PP
88
The JMOD file format lets you aggregate files other than
89
\f[V].class\f[R] files, metadata, and resources.
90
This format is transportable but not executable, which means that you
91
can use it during compile time or link time but not at run time.
92
.PP
93
Many \f[V]jmod\f[R] options involve specifying a path whose contents are
94
copied into the resulting JMOD files.
95
These options copy all the contents of the specified path, including
96
subdirectories and their contents, but exclude files whose names match
97
the pattern specified by the \f[V]--exclude\f[R] option.
98
.PP
99
With the \f[V]--hash-modules\f[R] option or the \f[V]jmod hash\f[R]
100
command, you can, in each module\[aq]s descriptor, record hashes of the
101
content of the modules that are allowed to depend upon it, thus
102
\[dq]tying\[dq] together these modules.
103
This enables a package to be exported to one or more specifically-named
104
modules and to no others through qualified exports.
105
The runtime verifies if the recorded hash of a module matches the one
106
resolved at run time; if not, the runtime returns an error.
107
.SH OPTIONS FOR JMOD
108
.TP
109
\f[V]--class-path\f[R] \f[I]path\f[R]
110
Specifies the location of application JAR files or a directory
111
containing classes to copy into the resulting JMOD file.
112
.TP
113
\f[V]--cmds\f[R] \f[I]path\f[R]
114
Specifies the location of native commands to copy into the resulting
115
JMOD file.
116
.TP
117
\f[V]--compress\f[R] \f[I]compress\f[R]
118
Specifies the compression to use in creating the JMOD file.
119
The accepted values are \f[V]zip-[0-9]\f[R], where \f[V]zip-0\f[R]
120
provides no compression, and \f[V]zip-9\f[R] provides the best
121
compression.
122
Default is \f[V]zip-6\f[R].
123
.TP
124
\f[V]--config\f[R] \f[I]path\f[R]
125
Specifies the location of user-editable configuration files to copy into
126
the resulting JMOD file.
127
.TP
128
\f[V]--date\f[R]\f[I]TIMESTAMP\f[R]
129
The timestamp in ISO-8601 extended offset date-time with optional
130
time-zone format, to use for the timestamp of the entries, e.g.
131
\[dq]2022-02-12T12:30:00-05:00\[dq].
132
.TP
133
\f[V]--dir\f[R] \f[I]path\f[R]
134
Specifies the location where \f[V]jmod\f[R] puts extracted files from
135
the specified JMOD archive.
136
.TP
137
\f[V]--dry-run\f[R]
138
Performs a dry run of hash mode.
139
It identifies leaf modules and their required modules without recording
140
any hash values.
141
.TP
142
\f[V]--exclude\f[R] \f[I]pattern-list\f[R]
143
Excludes files matching the supplied comma-separated pattern list, each
144
element using one the following forms:
145
.RS
146
.IP \[bu] 2
147
\f[I]glob-pattern\f[R]
148
.IP \[bu] 2
149
\f[V]glob:\f[R]\f[I]glob-pattern\f[R]
150
.IP \[bu] 2
151
\f[V]regex:\f[R]\f[I]regex-pattern\f[R]
152
.PP
153
See the \f[B]\f[VB]FileSystem.getPathMatcher\f[B]\f[R] method for the
154
syntax of \f[I]glob-pattern\f[R].
155
See the \f[B]\f[VB]Pattern\f[B]\f[R] class for the syntax of
156
\f[I]regex-pattern\f[R], which represents a regular expression.
157
.RE
158
.TP
159
\f[V]--hash-modules\f[R] \f[I]regex-pattern\f[R]
160
Determines the leaf modules and records the hashes of the dependencies
161
directly and indirectly requiring them, based on the module graph of the
162
modules matching the given \f[I]regex-pattern\f[R].
163
The hashes are recorded in the JMOD archive file being created, or a
164
JMOD archive or modular JAR on the module path specified by the
165
\f[V]jmod hash\f[R] command.
166
.TP
167
\f[V]--header-files\f[R] \f[I]path\f[R]
168
Specifies the location of header files to copy into the resulting JMOD
169
file.
170
.TP
171
\f[V]--help\f[R] or \f[V]-h\f[R]
172
Prints a usage message.
173
.TP
174
\f[V]--help-extra\f[R]
175
Prints help for extra options.
176
.TP
177
\f[V]--legal-notices\f[R] \f[I]path\f[R]
178
Specifies the location of legal notices to copy into the resulting JMOD
179
file.
180
.TP
181
\f[V]--libs\f[R] \f[I]path\f[R]
182
Specifies location of native libraries to copy into the resulting JMOD
183
file.
184
.TP
185
\f[V]--main-class\f[R] \f[I]class-name\f[R]
186
Specifies main class to record in the module-info.class file.
187
.TP
188
\f[V]--man-pages\f[R] \f[I]path\f[R]
189
Specifies the location of man pages to copy into the resulting JMOD
190
file.
191
.TP
192
\f[V]--module-version\f[R] \f[I]module-version\f[R]
193
Specifies the module version to record in the module-info.class file.
194
.TP
195
\f[V]--module-path\f[R] \f[I]path\f[R] or \f[V]-p\f[R] \f[I]path\f[R]
196
Specifies the module path.
197
This option is required if you also specify \f[V]--hash-modules\f[R].
198
.TP
199
\f[V]--target-platform\f[R] \f[I]platform\f[R]
200
Specifies the target platform.
201
.TP
202
\f[V]--version\f[R]
203
Prints version information of the \f[V]jmod\f[R] tool.
204
.TP
205
\f[V]\[at]\f[R]\f[I]filename\f[R]
206
Reads options from the specified file.
207
.RS
208
.PP
209
An options file is a text file that contains the options and values that
210
you would ordinarily enter in a command prompt.
211
Options may appear on one line or on several lines.
212
You may not specify environment variables for path names.
213
You may comment out lines by prefixinga hash symbol (\f[V]#\f[R]) to the
214
beginning of the line.
215
.PP
216
The following is an example of an options file for the \f[V]jmod\f[R]
217
command:
218
.IP
219
.nf
220
\f[CB]
221
#Wed Dec 07 00:40:19 EST 2016
222
create --class-path mods/com.greetings --module-path mlib
223
  --cmds commands --config configfiles --header-files src/h
224
  --libs lib --main-class com.greetings.Main
225
  --man-pages man --module-version 1.0
226
  --os-arch \[dq]x86_x64\[dq] --os-name \[dq]macOS\[dq]
227
  --os-version \[dq]10.10.5\[dq] greetingsmod
228
\f[R]
229
.fi
230
.RE
231
.SH EXTRA OPTIONS FOR JMOD
232
.PP
233
In addition to the options described in \f[B]Options for jmod\f[R], the
234
following are extra options that can be used with the command.
235
.TP
236
\f[V]--do-not-resolve-by-default\f[R]
237
Exclude from the default root set of modules
238
.TP
239
\f[V]--warn-if-resolved\f[R]
240
Hint for a tool to issue a warning if the module is resolved.
241
One of deprecated, deprecated-for-removal, or incubating.
242
.SH JMOD CREATE EXAMPLE
243
.PP
244
The following is an example of creating a JMOD file:
245
.IP
246
.nf
247
\f[CB]
248
jmod create --class-path mods/com.greetings --cmds commands
249
  --config configfiles --header-files src/h --libs lib
250
  --main-class com.greetings.Main --man-pages man --module-version 1.0
251
  --os-arch \[dq]x86_x64\[dq] --os-name \[dq]macOS\[dq]
252
  --os-version \[dq]10.10.5\[dq] greetingsmod
253
\f[R]
254
.fi
255
.PP
256
Create a JMOD file specifying the date for the entries as
257
\f[V]2022 March 15 00:00:00\f[R]:
258
.IP
259
.nf
260
\f[CB]
261
jmod create --class-path build/foo/classes --date 2022-03-15T00:00:00Z
262
   jmods/foo1.jmod
263
\f[R]
264
.fi
265
.SH JMOD HASH EXAMPLE
266
.PP
267
The following example demonstrates what happens when you try to link a
268
leaf module (in this example, \f[V]ma\f[R]) with a required module
269
(\f[V]mb\f[R]), and the hash value recorded in the required module
270
doesn\[aq]t match that of the leaf module.
271
.IP "1." 3
272
Create and compile the following \f[V].java\f[R] files:
273
.RS 4
274
.IP \[bu] 2
275
\f[V]jmodhashex/src/ma/module-info.java\f[R]
276
.RS 2
277
.IP
278
.nf
279
\f[CB]
280
module ma {
281
  requires mb;
282
}
283
\f[R]
284
.fi
285
.RE
286
.IP \[bu] 2
287
\f[V]jmodhashex/src/mb/module-info.java\f[R]
288
.RS 2
289
.IP
290
.nf
291
\f[CB]
292
module mb {
293
}
294
\f[R]
295
.fi
296
.RE
297
.IP \[bu] 2
298
\f[V]jmodhashex2/src/ma/module-info.java\f[R]
299
.RS 2
300
.IP
301
.nf
302
\f[CB]
303
module ma {
304
  requires mb;
305
}
306
\f[R]
307
.fi
308
.RE
309
.IP \[bu] 2
310
\f[V]jmodhashex2/src/mb/module-info.java\f[R]
311
.RS 2
312
.IP
313
.nf
314
\f[CB]
315
module mb {
316
}
317
\f[R]
318
.fi
319
.RE
320
.RE
321
.IP "2." 3
322
Create a JMOD archive for each module.
323
Create the directories \f[V]jmodhashex/jmods\f[R] and
324
\f[V]jmodhashex2/jmods\f[R], and then run the following commands from
325
the \f[V]jmodhashex\f[R] directory, then from the \f[V]jmodhashex2\f[R]
326
directory:
327
.RS 4
328
.IP \[bu] 2
329
\f[V]jmod create --class-path mods/ma jmods/ma.jmod\f[R]
330
.IP \[bu] 2
331
\f[V]jmod create --class-path mods/mb jmods/mb.jmod\f[R]
332
.RE
333
.IP "3." 3
334
Optionally preview the \f[V]jmod hash\f[R] command.
335
Run the following command from the \f[V]jmodhashex\f[R] directory:
336
.RS 4
337
.PP
338
\f[V]jmod hash --dry-run -module-path jmods --hash-modules .*\f[R]
339
.PP
340
The command prints the following:
341
.IP
342
.nf
343
\f[CB]
344
Dry run:
345
mb
346
  hashes ma SHA-256 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a
347
\f[R]
348
.fi
349
.PP
350
This indicates that the \f[V]jmod hash\f[R] command (without the
351
\f[V]--dry-run\f[R] option) will record the hash value of the leaf
352
module \f[V]ma\f[R] in the module \f[V]mb\f[R].
353
.RE
354
.IP "4." 3
355
Record hash values in the JMOD archive files contained in the
356
\f[V]jmodhashex\f[R] directory.
357
Run the following command from the \f[V]jmodhashex\f[R] directory:
358
.RS 4
359
.RS
360
.PP
361
\f[V]jmod hash --module-path jmods --hash-modules .*\f[R]
362
.RE
363
.PP
364
The command prints the following:
365
.RS
366
.PP
367
\f[V]Hashes are recorded in module mb\f[R]
368
.RE
369
.RE
370
.IP "5." 3
371
Print information about each JMOD archive contained in the
372
\f[V]jmodhashex\f[R] directory.
373
Run the highlighted commands from the \f[V]jmodhashex\f[R] directory:
374
.RS 4
375
.IP
376
.nf
377
\f[CB]
378
jmod describe jmods/ma.jmod
379

380
ma
381
  requires mandated java.base
382
  requires mb
383

384
jmod describe jmods/mb.jmod
385

386
mb
387
  requires mandated java.base
388
  hashes ma SHA-256 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a
389
\f[R]
390
.fi
391
.RE
392
.IP "6." 3
393
Attempt to create a runtime image that contains the module \f[V]ma\f[R]
394
from the directory \f[V]jmodhashex2\f[R] but the module \f[V]mb\f[R]
395
from the directory \f[V]jmodhashex\f[R].
396
Run the following command from the \f[V]jmodhashex2\f[R] directory:
397
.RS 4
398
.IP \[bu] 2
399
\f[B]Linux and macOS:\f[R]
400
.RS 2
401
.RS
402
.PP
403
\f[V]jlink --module-path $JAVA_HOME/jmods:jmods/ma.jmod:../jmodhashex/jmods/mb.jmod --add-modules ma --output ma-app\f[R]
404
.RE
405
.RE
406
.IP \[bu] 2
407
\f[B]Windows:\f[R]
408
.RS 2
409
.RS
410
.PP
411
\f[V]jlink --module-path %JAVA_HOME%/jmods;jmods/ma.jmod;../jmodhashex/jmods/mb.jmod --add-modules ma --output ma-app\f[R]
412
.RE
413
.RE
414
.PP
415
The command prints an error message similar to the following:
416
.IP
417
.nf
418
\f[CB]
419
Error: Hash of ma (a2d77889b0cb067df02a3abc39b01ac1151966157a68dc4241562c60499150d2) differs to
420
expected hash (07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a) recorded in mb
421
\f[R]
422
.fi
423
.RE
424