1JMOD(1) JDK Commands JMOD(1)
2
3
4
6 jmod - create JMOD files and list the content of existing JMOD files
7
9 jmod (create|extract|list|describe|hash) [options] jmod-file
10
11 Includes the following:
12
13 Main operation modes
14
15 create Creates a new JMOD archive file.
16
17 extract
18 Extracts all the files from the JMOD archive file.
19
20 list Prints the names of all the entries.
21
22 describe
23 Prints the module details.
24
25 hash Determines leaf modules and records the hashes of the dependen‐
26 cies that directly and indirectly require them.
27
28 Options
29
30 options
31 See Options for jmod.
32
33 Required
34
35 jmod-file
36 Specifies the name of the JMOD file to create or from which to
37 retrieve information.
38
40 Note: For most development tasks, including deploying modules on the
41 module path or publishing them to a Maven repository, continue to pack‐
42 age modules in modular JAR files. The jmod tool is intended for mod‐
43 ules that have native libraries or other configuration files or for
44 modules that you intend to link, with the jlink tool, to a runtime im‐
45 age.
46
47 The JMOD file format lets you aggregate files other than .class files,
48 metadata, and resources. This format is transportable but not exe‐
49 cutable, which means that you can use it during compile time or link
50 time but not at run time.
51
52 Many jmod options involve specifying a path whose contents are copied
53 into the resulting JMOD files. These options copy all the contents of
54 the specified path, including subdirectories and their contents, but
55 exclude files whose names match the pattern specified by the --exclude
56 option.
57
58 With the --hash-modules option or the jmod hash command, you can, in
59 each module's descriptor, record hashes of the content of the modules
60 that are allowed to depend upon it, thus "tying" together these mod‐
61 ules. This enables a package to be exported to one or more specifical‐
62 ly-named modules and to no others through qualified exports. The run‐
63 time verifies if the recorded hash of a module matches the one resolved
64 at run time; if not, the runtime returns an error.
65
67 --class-path path
68 Specifies the location of application JAR files or a directory
69 containing classes to copy into the resulting JMOD file.
70
71 --cmds path
72 Specifies the location of native commands to copy into the re‐
73 sulting JMOD file.
74
75 --compress compress
76 Specifies the compression to use in creating the JMOD file. The
77 accepted values are zip-[0-9], where zip-0 provides no compres‐
78 sion, and zip-9 provides the best compression. Default is
79 zip-6.
80
81 --config path
82 Specifies the location of user-editable configuration files to
83 copy into the resulting JMOD file.
84
85 --dateTIMESTAMP
86 The timestamp in ISO-8601 extended offset date-time with option‐
87 al time-zone format, to use for the timestamp of the entries,
88 e.g. "2022-02-12T12:30:00-05:00".
89
90 --dir path
91 Specifies the location where jmod puts extracted files from the
92 specified JMOD archive.
93
94 --dry-run
95 Performs a dry run of hash mode. It identifies leaf modules and
96 their required modules without recording any hash values.
97
98 --exclude pattern-list
99 Excludes files matching the supplied comma-separated pattern
100 list, each element using one the following forms:
101
102 • glob-pattern
103
104 • glob:glob-pattern
105
106 • regex:regex-pattern
107
108 See the FileSystem.getPathMatcher method for the syntax of glob-
109 pattern. See the Pattern class for the syntax of regex-pattern,
110 which represents a regular expression.
111
112 --hash-modules regex-pattern
113 Determines the leaf modules and records the hashes of the depen‐
114 dencies directly and indirectly requiring them, based on the
115 module graph of the modules matching the given regex-pattern.
116 The hashes are recorded in the JMOD archive file being created,
117 or a JMOD archive or modular JAR on the module path specified by
118 the jmod hash command.
119
120 --header-files path
121 Specifies the location of header files to copy into the result‐
122 ing JMOD file.
123
124 --help or -h
125 Prints a usage message.
126
127 --help-extra
128 Prints help for extra options.
129
130 --legal-notices path
131 Specifies the location of legal notices to copy into the result‐
132 ing JMOD file.
133
134 --libs path
135 Specifies location of native libraries to copy into the result‐
136 ing JMOD file.
137
138 --main-class class-name
139 Specifies main class to record in the module-info.class file.
140
141 --man-pages path
142 Specifies the location of man pages to copy into the resulting
143 JMOD file.
144
145 --module-version module-version
146 Specifies the module version to record in the module-info.class
147 file.
148
149 --module-path path or -p path
150 Specifies the module path. This option is required if you also
151 specify --hash-modules.
152
153 --target-platform platform
154 Specifies the target platform.
155
156 --version
157 Prints version information of the jmod tool.
158
159 @filename
160 Reads options from the specified file.
161
162 An options file is a text file that contains the options and
163 values that you would ordinarily enter in a command prompt. Op‐
164 tions may appear on one line or on several lines. You may not
165 specify environment variables for path names. You may comment
166 out lines by prefixinga hash symbol (#) to the beginning of the
167 line.
168
169 The following is an example of an options file for the jmod com‐
170 mand:
171
172 #Wed Dec 07 00:40:19 EST 2016
173 create --class-path mods/com.greetings --module-path mlib
174 --cmds commands --config configfiles --header-files src/h
175 --libs lib --main-class com.greetings.Main
176 --man-pages man --module-version 1.0
177 --os-arch "x86_x64" --os-name "macOS"
178 --os-version "10.10.5" greetingsmod
179
181 In addition to the options described in Options for jmod, the following
182 are extra options that can be used with the command.
183
184 --do-not-resolve-by-default
185 Exclude from the default root set of modules
186
187 --warn-if-resolved
188 Hint for a tool to issue a warning if the module is resolved.
189 One of deprecated, deprecated-for-removal, or incubating.
190
192 The following is an example of creating a JMOD file:
193
194 jmod create --class-path mods/com.greetings --cmds commands
195 --config configfiles --header-files src/h --libs lib
196 --main-class com.greetings.Main --man-pages man --module-version 1.0
197 --os-arch "x86_x64" --os-name "macOS"
198 --os-version "10.10.5" greetingsmod
199
200 Create a JMOD file specifying the date for the entries as 2022 March 15
201 00:00:00:
202
203 jmod create --class-path build/foo/classes --date 2022-03-15T00:00:00Z
204 jmods/foo1.jmod
205
207 The following example demonstrates what happens when you try to link a
208 leaf module (in this example, ma) with a required module (mb), and the
209 hash value recorded in the required module doesn't match that of the
210 leaf module.
211
212 1. Create and compile the following .java files:
213
214 • jmodhashex/src/ma/module-info.java
215
216 module ma {
217 requires mb;
218 }
219
220 • jmodhashex/src/mb/module-info.java
221
222 module mb {
223 }
224
225 • jmodhashex2/src/ma/module-info.java
226
227 module ma {
228 requires mb;
229 }
230
231 • jmodhashex2/src/mb/module-info.java
232
233 module mb {
234 }
235
236 2. Create a JMOD archive for each module. Create the directories jmod‐
237 hashex/jmods and jmodhashex2/jmods, and then run the following com‐
238 mands from the jmodhashex directory, then from the jmodhashex2 di‐
239 rectory:
240
241 • jmod create --class-path mods/ma jmods/ma.jmod
242
243 • jmod create --class-path mods/mb jmods/mb.jmod
244
245 3. Optionally preview the jmod hash command. Run the following command
246 from the jmodhashex directory:
247
248 jmod hash --dry-run -module-path jmods --hash-modules .*
249
250 The command prints the following:
251
252 Dry run:
253 mb
254 hashes ma SHA-256 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a
255
256 This indicates that the jmod hash command (without the --dry-run
257 option) will record the hash value of the leaf module ma in the
258 module mb.
259
260 4. Record hash values in the JMOD archive files contained in the jmod‐
261 hashex directory. Run the following command from the jmodhashex di‐
262 rectory:
263
264 jmod hash --module-path jmods --hash-modules .*
265
266 The command prints the following:
267
268 Hashes are recorded in module mb
269
270 5. Print information about each JMOD archive contained in the jmod‐
271 hashex directory. Run the highlighted commands from the jmodhashex
272 directory:
273
274 jmod describe jmods/ma.jmod
275
276 ma
277 requires mandated java.base
278 requires mb
279
280 jmod describe jmods/mb.jmod
281
282 mb
283 requires mandated java.base
284 hashes ma SHA-256 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a
285
286 6. Attempt to create a runtime image that contains the module ma from
287 the directory jmodhashex2 but the module mb from the directory jmod‐
288 hashex. Run the following command from the jmodhashex2 directory:
289
290 • Linux and macOS:
291
292 jlink --module-path $JA‐
293 VA_HOME/jmods:jmods/ma.jmod:../jmodhashex/jmods/mb.jmod
294 --add-modules ma --output ma-app
295
296 • Windows:
297
298 jlink --module-path %JA‐
299 VA_HOME%/jmods;jmods/ma.jmod;../jmodhashex/jmods/mb.jmod
300 --add-modules ma --output ma-app
301
302 The command prints an error message similar to the following:
303
304 Error: Hash of ma (a2d77889b0cb067df02a3abc39b01ac1151966157a68dc4241562c60499150d2) differs to
305 expected hash (07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a) recorded in mb
306
307
308
309JDK 21 2023 JMOD(1)