1JMOD(1) JDK Commands JMOD(1)
2
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 Includes the following:
12 Main operation modes
14 create Creates a new JMOD archive file.
16 extract
18 Extracts all the files from the JMOD archive file.
19 list Prints the names of all the entries.
21 describe
23 Prints the module details.
24 hash Determines leaf modules and records the hashes of the dependen‐
26 cies that directly and indirectly require them.
27 Options
29 options
31 See Options for jmod.
32 Required
34 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 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 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 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 --cmds path
72 Specifies the location of native commands to copy into the re‐
73 sulting JMOD file.
74 --config path
76 Specifies the location of user-editable configuration files to
77 copy into the resulting JMOD file.
78 --dir path
80 Specifies the location where jmod puts extracted files from the
81 specified JMOD archive.
82 --dry-run
84 Performs a dry run of hash mode. It identifies leaf modules and
85 their required modules without recording any hash values.
86 --exclude pattern-list
88 Excludes files matching the supplied comma-separated pattern
89 list, each element using one the following forms:
90 • glob-pattern
92 • glob:glob-pattern
94 • regex:regex-pattern
96 See the FileSystem.getPathMatcher method for the syntax of
98 glob-pattern. See the Pattern class for the syntax of
99 regex-pattern, which represents a regular expression.
100 --hash-modules regex-pattern
102 Determines the leaf modules and records the hashes of the depen‐
103 dencies directly and indirectly requiring them, based on the
104 module graph of the modules matching the given regex-pattern.
105 The hashes are recorded in the JMOD archive file being created,
106 or a JMOD archive or modular JAR on the module path specified by
107 the jmod hash command.
108 --header-files path
110 Specifies the location of header files to copy into the result‐
111 ing JMOD file.
112 --help or -h
114 Prints a usage message.
115 --help-extra
117 Prints help for extra options.
118 --legal-notices path
120 Specifies the location of legal notices to copy into the result‐
121 ing JMOD file.
122 --libs path
124 Specifies location of native libraries to copy into the result‐
125 ing JMOD file.
126 --main-class class-name
128 Specifies main class to record in the module-info.class file.
129 --man-pages path
131 Specifies the location of man pages to copy into the resulting
132 JMOD file.
133 --module-version module-version
135 Specifies the module version to record in the module-info.class
136 file.
137 --module-path path or -p path
139 Specifies the module path. This option is required if you also
140 specify --hash-modules.
141 --target-platform platform
143 Specifies the target platform.
144 --version
146 Prints version information of the jmod tool.
147 @filename
149 Reads options from the specified file.
150 An options file is a text file that contains the options and
152 values that you would ordinarily enter in a command prompt. Op‐
153 tions may appear on one line or on several lines. You may not
154 specify environment variables for path names. You may comment
155 out lines by prefixinga hash symbol (#) to the beginning of the
156 line.
157 The following is an example of an options file for the jmod com‐
159 mand:
160 #Wed Dec 07 00:40:19 EST 2016
162 create --class-path mods/com.greetings --module-path mlib
163 --cmds commands --config configfiles --header-files src/h
164 --libs lib --main-class com.greetings.Main
165 --man-pages man --module-version 1.0
166 --os-arch "x86_x64" --os-name "Mac OS X"
167 --os-version "10.10.5" greetingsmod
168
170 In addition to the options described in Options for jmod, the following
171 are extra options that can be used with the command.
172 --do-not-resolve-by-default
174 Exclude from the default root set of modules
175 --warn-if-resolved
177 Hint for a tool to issue a warning if the module is resolved.
178 One of deprecated, deprecated-for-removal, or incubating.
179
181 The following is an example of creating a JMOD file:
182 jmod create --class-path mods/com.greetings --cmds commands
184 --config configfiles --header-files src/h --libs lib
185 --main-class com.greetings.Main --man-pages man --module-version 1.0
186 --os-arch "x86_x64" --os-name "Mac OS X"
187 --os-version "10.10.5" greetingsmod
188
190 The following example demonstrates what happens when you try to link a
191 leaf module (in this example, ma) with a required module (mb), and the
192 hash value recorded in the required module doesn't match that of the
193 leaf module.
194 1. Create and compile the following .java files:
196 • jmodhashex/src/ma/module-info.java
198 module ma {
200 requires mb;
201 }
202 • jmodhashex/src/mb/module-info.java
204 module mb {
206 }
207 • jmodhashex2/src/ma/module-info.java
209 module ma {
211 requires mb;
212 }
213 • jmodhashex2/src/mb/module-info.java
215 module mb {
217 }
218 2. Create a JMOD archive for each module. Create the directories jmod‐
220 hashex/jmods and jmodhashex2/jmods, and then run the following com‐
221 mands from the jmodhashex directory, then from the jmodhashex2 di‐
222 rectory:
223 • jmod create --class-path mods/ma jmods/ma.jmod
225 • jmod create --class-path mods/mb jmods/mb.jmod
227 3. Optionally preview the jmod hash command. Run the following command
229 from the jmodhashex directory:
230 jmod hash --dry-run -module-path jmods --hash-modules .*
232 The command prints the following:
234 Dry run:
236 mb
237 hashes ma SHA-256 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a
238 This indicates that the jmod hash command (without the --dry-run
240 option) will record the hash value of the leaf module ma in the
241 module mb.
242 4. Record hash values in the JMOD archive files contained in the jmod‐
244 hashex directory. Run the following command from the jmodhashex di‐
245 rectory:
246 jmod hash --module-path jmods --hash-modules .*
248 The command prints the following:
250 Hashes are recorded in module mb
252 5. Print information about each JMOD archive contained in the jmod‐
254 hashex directory. Run the highlighted commands from the jmodhashex
255 directory:
256 jmod describe jmods/ma.jmod
258 ma
260 requires mandated java.base
261 requires mb
262 jmod describe jmods/mb.jmod
264 mb
266 requires mandated java.base
267 hashes ma SHA-256 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a
268 6. Attempt to create a runtime image that contains the module ma from
270 the directory jmodhashex2 but the module mb from the directory jmod‐
271 hashex. Run the following command from the jmodhashex2 directory:
272 • Linux and OS X:
274 jlink --module-path $JA‐
276 VA_HOME/jmods:jmods/ma.jmod:../jmod‐
277 hashex/jmods/mb.jmod --add-modules ma --output ma-app
278 • Windows:
280 jlink --module-path %JA‐
282 VA_HOME%/jmods;jmods/ma.jmod;../jmod‐
283 hashex/jmods/mb.jmod --add-modules ma --output ma-app
284 The command prints an error message similar to the following:
286 Error: Hash of ma (a2d77889b0cb067df02a3abc39b01ac1151966157a68dc4241562c60499150d2) differs to
288 expected hash (07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a) recorded in mb
289JDK 17 2021 JMOD(1)