1JMOD(1)                          JDK Commands                          JMOD(1)
2
3
4

NAME

6       jmod - create JMOD files and list the content of existing JMOD files
7

SYNOPSIS

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

DESCRIPTION

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

OPTIONS FOR JMOD

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       --dir path
80              Specifies the location where jmod puts extracted files from  the
81              specified JMOD archive.
82
83       --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
87       --exclude pattern-list
88              Excludes files matching  the  supplied  comma-separated  pattern
89              list, each element using one the following forms:
90
91glob-pattern
92
93glob:glob-pattern
94
95regex:regex-pattern
96
97              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
101       --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
109       --header-files path
110              Specifies the location of header files to copy into the  result‐
111              ing JMOD file.
112
113       --help or -h
114              Prints a usage message.
115
116       --help-extra
117              Prints help for extra options.
118
119       --legal-notices path
120              Specifies the location of legal notices to copy into the result‐
121              ing JMOD file.
122
123       --libs path
124              Specifies location of native libraries to copy into the  result‐
125              ing JMOD file.
126
127       --main-class class-name
128              Specifies main class to record in the module-info.class file.
129
130       --man-pages path
131              Specifies  the  location of man pages to copy into the resulting
132              JMOD file.
133
134       --module-version module-version
135              Specifies the module version to record in the  module-info.class
136              file.
137
138       --module-path path or -p path
139              Specifies  the module path.  This option is required if you also
140              specify --hash-modules.
141
142       --target-platform platform
143              Specifies the target platform.
144
145       --version
146              Prints version information of the jmod tool.
147
148       @filename
149              Reads options from the specified file.
150
151              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
158              The following is an example of an options file for the jmod com‐
159              mand:
160
161                     #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

EXTRA OPTIONS FOR JMOD

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
173       --do-not-resolve-by-default
174              Exclude from the default root set of modules
175
176       --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

JMOD CREATE EXAMPLE

181       The following is an example of creating a JMOD file:
182
183              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

JMOD HASH EXAMPLE

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
195       1. Create and compile the following .java files:
196
197jmodhashex/src/ma/module-info.java
198
199                    module ma {
200                      requires mb;
201                    }
202
203jmodhashex/src/mb/module-info.java
204
205                    module mb {
206                    }
207
208jmodhashex2/src/ma/module-info.java
209
210                    module ma {
211                      requires mb;
212                    }
213
214jmodhashex2/src/mb/module-info.java
215
216                    module mb {
217                    }
218
219       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
224jmod create --class-path mods/ma jmods/ma.jmod
225
226jmod create --class-path mods/mb jmods/mb.jmod
227
228       3. Optionally preview the jmod hash command.  Run the following command
229          from the jmodhashex directory:
230
231           jmod hash --dry-run -module-path jmods --hash-modules .*
232
233           The command prints the following:
234
235                  Dry run:
236                  mb
237                    hashes ma SHA-256 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a
238
239           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
243       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
247                  jmod hash --module-path jmods --hash-modules .*
248
249           The command prints the following:
250
251                  Hashes are recorded in module mb
252
253       5. Print  information  about  each  JMOD archive contained in the jmod‐
254          hashex directory.  Run the highlighted commands from the  jmodhashex
255          directory:
256
257                  jmod describe jmods/ma.jmod
258
259                  ma
260                    requires mandated java.base
261                    requires mb
262
263                  jmod describe jmods/mb.jmod
264
265                  mb
266                    requires mandated java.base
267                    hashes ma SHA-256 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a
268
269       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
273Linux and OS X:
274
275                    jlink --module-path $JA‐
276                    VA_HOME/jmods:jmods/ma.jmod:../jmod‐
277                    hashex/jmods/mb.jmod --add-modules ma --output ma-app
278
279Windows:
280
281                    jlink --module-path %JA‐
282                    VA_HOME%/jmods;jmods/ma.jmod;../jmod‐
283                    hashex/jmods/mb.jmod --add-modules ma --output ma-app
284
285           The command prints an error message similar to the following:
286
287                  Error: Hash of ma (a2d77889b0cb067df02a3abc39b01ac1151966157a68dc4241562c60499150d2) differs to
288                  expected hash (07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a) recorded in mb
289
290
291
292JDK 17                               2021                              JMOD(1)
Impressum