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 --config path
76 Specifies the location of user-editable configuration files to
77 copy into the resulting JMOD file.
78
79 --dateTIMESTAMP
80 The timestamp in ISO-8601 extended offset date-time with option‐
81 al time-zone format, to use for the timestamp of the entries,
82 e.g. "2022-02-12T12:30:00-05:00".
83
84 --dir path
85 Specifies the location where jmod puts extracted files from the
86 specified JMOD archive.
87
88 --dry-run
89 Performs a dry run of hash mode. It identifies leaf modules and
90 their required modules without recording any hash values.
91
92 --exclude pattern-list
93 Excludes files matching the supplied comma-separated pattern
94 list, each element using one the following forms:
95
96 • glob-pattern
97
98 • glob:glob-pattern
99
100 • regex:regex-pattern
101
102 See the FileSystem.getPathMatcher method for the syntax of
103 glob-pattern. See the Pattern class for the syntax of
104 regex-pattern, which represents a regular expression.
105
106 --hash-modules regex-pattern
107 Determines the leaf modules and records the hashes of the depen‐
108 dencies directly and indirectly requiring them, based on the
109 module graph of the modules matching the given regex-pattern.
110 The hashes are recorded in the JMOD archive file being created,
111 or a JMOD archive or modular JAR on the module path specified by
112 the jmod hash command.
113
114 --header-files path
115 Specifies the location of header files to copy into the result‐
116 ing JMOD file.
117
118 --help or -h
119 Prints a usage message.
120
121 --help-extra
122 Prints help for extra options.
123
124 --legal-notices path
125 Specifies the location of legal notices to copy into the result‐
126 ing JMOD file.
127
128 --libs path
129 Specifies location of native libraries to copy into the result‐
130 ing JMOD file.
131
132 --main-class class-name
133 Specifies main class to record in the module-info.class file.
134
135 --man-pages path
136 Specifies the location of man pages to copy into the resulting
137 JMOD file.
138
139 --module-version module-version
140 Specifies the module version to record in the module-info.class
141 file.
142
143 --module-path path or -p path
144 Specifies the module path. This option is required if you also
145 specify --hash-modules.
146
147 --target-platform platform
148 Specifies the target platform.
149
150 --version
151 Prints version information of the jmod tool.
152
153 @filename
154 Reads options from the specified file.
155
156 An options file is a text file that contains the options and
157 values that you would ordinarily enter in a command prompt. Op‐
158 tions may appear on one line or on several lines. You may not
159 specify environment variables for path names. You may comment
160 out lines by prefixinga hash symbol (#) to the beginning of the
161 line.
162
163 The following is an example of an options file for the jmod com‐
164 mand:
165
166 #Wed Dec 07 00:40:19 EST 2016
167 create --class-path mods/com.greetings --module-path mlib
168 --cmds commands --config configfiles --header-files src/h
169 --libs lib --main-class com.greetings.Main
170 --man-pages man --module-version 1.0
171 --os-arch "x86_x64" --os-name "Mac OS X"
172 --os-version "10.10.5" greetingsmod
173
175 In addition to the options described in Options for jmod, the following
176 are extra options that can be used with the command.
177
178 --do-not-resolve-by-default
179 Exclude from the default root set of modules
180
181 --warn-if-resolved
182 Hint for a tool to issue a warning if the module is resolved.
183 One of deprecated, deprecated-for-removal, or incubating.
184
186 The following is an example of creating a JMOD file:
187
188 jmod create --class-path mods/com.greetings --cmds commands
189 --config configfiles --header-files src/h --libs lib
190 --main-class com.greetings.Main --man-pages man --module-version 1.0
191 --os-arch "x86_x64" --os-name "Mac OS X"
192 --os-version "10.10.5" greetingsmod
193
194 Create a JMOD file specifying the date for the entries as
195 2022 March 15 00:00:00:
196
197 jmod create --class-path build/foo/classes --date 2022-03-15T00:00:00Z
198 jmods/foo1.jmod
199
201 The following example demonstrates what happens when you try to link a
202 leaf module (in this example, ma) with a required module (mb), and the
203 hash value recorded in the required module doesn't match that of the
204 leaf module.
205
206 1. Create and compile the following .java files:
207
208 • jmodhashex/src/ma/module-info.java
209
210 module ma {
211 requires mb;
212 }
213
214 • jmodhashex/src/mb/module-info.java
215
216 module mb {
217 }
218
219 • jmodhashex2/src/ma/module-info.java
220
221 module ma {
222 requires mb;
223 }
224
225 • jmodhashex2/src/mb/module-info.java
226
227 module mb {
228 }
229
230 2. Create a JMOD archive for each module. Create the directories jmod‐
231 hashex/jmods and jmodhashex2/jmods, and then run the following com‐
232 mands from the jmodhashex directory, then from the jmodhashex2 di‐
233 rectory:
234
235 • jmod create --class-path mods/ma jmods/ma.jmod
236
237 • jmod create --class-path mods/mb jmods/mb.jmod
238
239 3. Optionally preview the jmod hash command. Run the following command
240 from the jmodhashex directory:
241
242 jmod hash --dry-run -module-path jmods --hash-modules .*
243
244 The command prints the following:
245
246 Dry run:
247 mb
248 hashes ma SHA-256 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a
249
250 This indicates that the jmod hash command (without the --dry-run
251 option) will record the hash value of the leaf module ma in the
252 module mb.
253
254 4. Record hash values in the JMOD archive files contained in the jmod‐
255 hashex directory. Run the following command from the jmodhashex di‐
256 rectory:
257
258 jmod hash --module-path jmods --hash-modules .*
259
260 The command prints the following:
261
262 Hashes are recorded in module mb
263
264 5. Print information about each JMOD archive contained in the jmod‐
265 hashex directory. Run the highlighted commands from the jmodhashex
266 directory:
267
268 jmod describe jmods/ma.jmod
269
270 ma
271 requires mandated java.base
272 requires mb
273
274 jmod describe jmods/mb.jmod
275
276 mb
277 requires mandated java.base
278 hashes ma SHA-256 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a
279
280 6. Attempt to create a runtime image that contains the module ma from
281 the directory jmodhashex2 but the module mb from the directory jmod‐
282 hashex. Run the following command from the jmodhashex2 directory:
283
284 • Linux and OS X:
285
286 jlink --module-path $JA‐
287 VA_HOME/jmods:jmods/ma.jmod:../jmod‐
288 hashex/jmods/mb.jmod --add-modules ma --output ma-app
289
290 • Windows:
291
292 jlink --module-path %JA‐
293 VA_HOME%/jmods;jmods/ma.jmod;../jmod‐
294 hashex/jmods/mb.jmod --add-modules ma --output ma-app
295
296 The command prints an error message similar to the following:
297
298 Error: Hash of ma (a2d77889b0cb067df02a3abc39b01ac1151966157a68dc4241562c60499150d2) differs to
299 expected hash (07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a) recorded in mb
300
301
302
303JDK 19 2022 JMOD(1)