1 .\" Copyright (c) 1994, 2019, 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.3.1 23 .\" 24 .TH "JMOD" "1" "2018" "JDK 13" "JDK Commands" 25 .hy 26 .SH NAME 27 .PP 28 jmod \- create JMOD files and list the content of existing JMOD files 29 .SH SYNOPSIS 30 .PP 31 \f[CB]jmod\f[R] 32 (\f[CB]create\f[R]|\f[CB]extract\f[R]|\f[CB]list\f[R]|\f[CB]describe\f[R]|\f[CB]hash\f[R]) 33 [\f[I]options\f[R]] \f[I]jmod\-file\f[R] 34 .PP 35 Includes the following: 36 .PP 37 \f[B]Main operation modes\f[R] 38 .TP 39 .B \f[CB]create\f[R] 40 Creates a new JMOD archive file. 41 .RS 42 .RE 43 .TP 44 .B \f[CB]extract\f[R] 45 Extracts all the files from the JMOD archive file. 46 .RS 47 .RE 48 .TP 49 .B \f[CB]list\f[R] 50 Prints the names of all the entries. 51 .RS 52 .RE 53 .TP 54 .B \f[CB]describe\f[R] 55 Prints the module details. 56 .RS 57 .RE 58 .TP 59 .B \f[CB]hash\f[R] 60 Determines leaf modules and records the hashes of the dependencies that 61 directly and indirectly require them. 62 .RS 63 .RE 64 .PP 65 \f[B]Options\f[R] 66 .TP 67 .B \f[I]options\f[R] 68 See \f[B]Options for jmod\f[R]. 69 .RS 70 .RE 71 .PP 72 \f[B]Required\f[R] 73 .TP 74 .B \f[I]jmod\-file\f[R] 75 Specifies the name of the JMOD file to create or from which to retrieve 76 information. 77 .RS 78 .RE 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[CB]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[CB]\&.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[CB]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[CB]\-\-exclude\f[R] option. 98 .PP 99 With the \f[CB]\-\-hash\-modules\f[R] option or the \f[CB]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 "tying" 102 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 .B \f[CB]\-\-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 .RS 113 .RE 114 .TP 115 .B \f[CB]\-\-cmds\f[R] \f[I]path\f[R] 116 Specifies the location of native commands to copy into the resulting 117 JMOD file. 118 .RS 119 .RE 120 .TP 121 .B \f[CB]\-\-config\f[R] \f[I]path\f[R] 122 Specifies the location of user\-editable configuration files to copy 123 into the resulting JMOD file. 124 .RS 125 .RE 126 .TP 127 .B \f[CB]\-\-dir\f[R] \f[I]path\f[R] 128 Specifies the location where \f[CB]jmod\f[R] puts extracted files from the 129 specified JMOD archive. 130 .RS 131 .RE 132 .TP 133 .B \f[CB]\-\-dry\-run\f[R] 134 Performs a dry run of hash mode. 135 It identifies leaf modules and their required modules without recording 136 any hash values. 137 .RS 138 .RE 139 .TP 140 .B \f[CB]\-\-exclude\f[R] \f[I]pattern\-list\f[R] 141 Excludes files matching the supplied comma\-separated pattern list, each 142 element using one the following forms: 143 .RS 144 .IP \[bu] 2 145 \f[I]glob\-pattern\f[R] 146 .IP \[bu] 2 147 \f[CB]glob:\f[R]\f[I]glob\-pattern\f[R] 148 .IP \[bu] 2 149 \f[CB]regex:\f[R]\f[I]regex\-pattern\f[R] 150 .PP 151 See the \f[B]\f[BC]FileSystem.getPathMatcher\f[B]\f[R] 152 [https://docs.oracle.com/javase/10/docs/api/java/nio/file/FileSystem.html#getPathMatcher\-java.lang.String\-] 153 method for the syntax of \f[I]glob\-pattern\f[R]. 154 See the \f[B]\f[BC]Pattern\f[B]\f[R] 155 [https://docs.oracle.com/javase/10/docs/api/java/util/regex/Pattern.html] 156 class for the syntax of \f[I]regex\-pattern\f[R], which represents a 157 regular expression. 158 .RE 159 .TP 160 .B \f[CB]\-\-hash\-modules\f[R] \f[I]regex\-pattern\f[R] 161 Determines the leaf modules and records the hashes of the dependencies 162 directly and indirectly requiring them, based on the module graph of the 163 modules matching the given \f[I]regex\-pattern\f[R]. 164 The hashes are recorded in the JMOD archive file being created, or a 165 JMOD archive or modular JAR on the module path specified by the 166 \f[CB]jmod\ hash\f[R] command. 167 .RS 168 .RE 169 .TP 170 .B \f[CB]\-\-header\-files\f[R] \f[I]path\f[R] 171 Specifies the location of header files to copy into the resulting JMOD 172 file. 173 .RS 174 .RE 175 .TP 176 .B \f[CB]\-\-help\f[R] or \f[CB]\-h\f[R] 177 Prints a usage message. 178 .RS 179 .RE 180 .TP 181 .B \f[CB]\-\-help\-extra\f[R] 182 Prints help for extra options. 183 .RS 184 .RE 185 .TP 186 .B \f[CB]\-\-legal\-notices\f[R] \f[I]path\f[R] 187 Specifies the location of legal notices to copy into the resulting JMOD 188 file. 189 .RS 190 .RE 191 .TP 192 .B \f[CB]\-\-libs\f[R] \f[I]path\f[R] 193 Specifies location of native libraries to copy into the resulting JMOD 194 file. 195 .RS 196 .RE 197 .TP 198 .B \f[CB]\-\-main\-class\f[R] \f[I]class\-name\f[R] 199 Specifies main class to record in the module\-info.class file. 200 .RS 201 .RE 202 .TP 203 .B \f[CB]\-\-man\-pages\f[R] \f[I]path\f[R] 204 Specifies the location of man pages to copy into the resulting JMOD 205 file. 206 .RS 207 .RE 208 .TP 209 .B \f[CB]\-\-module\-version\f[R] \f[I]module\-version\f[R] 210 Specifies the module version to record in the module\-info.class file. 211 .RS 212 .RE 213 .TP 214 .B \f[CB]\-\-module\-path\f[R] \f[I]path\f[R] or \f[CB]\-p\f[R] \f[I]path\f[R] 215 Specifies the module path. 216 This option is required if you also specify \f[CB]\-\-hash\-modules\f[R]. 217 .RS 218 .RE 219 .TP 220 .B \f[CB]\-\-target\-platform\f[R] \f[I]platform\f[R] 221 Specifies the target platform. 222 .RS 223 .RE 224 .TP 225 .B \f[CB]\-\-version\f[R] 226 Prints version information of the \f[CB]jmod\f[R] tool. 227 .RS 228 .RE 229 .TP 230 .B \f[CB]\@\f[R]\f[I]filename\f[R] 231 Reads options from the specified file. 232 .RS 233 .PP 234 An options file is a text file that contains the options and values that 235 you would ordinarily enter in a command prompt. 236 Options may appear on one line or on several lines. 237 You may not specify environment variables for path names. 238 You may comment out lines by prefixinga hash symbol (\f[CB]#\f[R]) to the 239 beginning of the line. 240 .PP 241 The following is an example of an options file for the \f[CB]jmod\f[R] 242 command: 243 .IP 244 .nf 245 \f[CB] 246 #Wed\ Dec\ 07\ 00:40:19\ EST\ 2016 247 create\ \-\-class\-path\ mods/com.greetings\ \-\-module\-path\ mlib 248 \ \ \-\-cmds\ commands\ \-\-config\ configfiles\ \-\-header\-files\ src/h 249 \ \ \-\-libs\ lib\ \-\-main\-class\ com.greetings.Main 250 \ \ \-\-man\-pages\ man\ \-\-module\-version\ 1.0 251 \ \ \-\-os\-arch\ "x86_x64"\ \-\-os\-name\ "Mac\ OS\ X" 252 \ \ \-\-os\-version\ "10.10.5"\ greetingsmod 253 \f[R] 254 .fi 255 .RE 256 .SH EXTRA OPTIONS FOR JMOD 257 .PP 258 In addition to the options described in \f[B]Options for jmod\f[R], the 259 following are extra options that can be used with the command. 260 .TP 261 .B \f[CB]\-\-do\-not\-resolve\-by\-default\f[R] 262 Exclude from the default root set of modules 263 .RS 264 .RE 265 .TP 266 .B \f[CB]\-\-warn\-if\-resolved\f[R] 267 Hint for a tool to issue a warning if the module is resolved. 268 One of deprecated, deprecated\-for\-removal, or incubating. 269 .RS 270 .RE 271 .SH JMOD CREATE EXAMPLE 272 .PP 273 The following is an example of creating a JMOD file: 274 .IP 275 .nf 276 \f[CB] 277 jmod\ create\ \-\-class\-path\ mods/com.greetings\ \-\-cmds\ commands 278 \ \ \-\-config\ configfiles\ \-\-header\-files\ src/h\ \-\-libs\ lib 279 \ \ \-\-main\-class\ com.greetings.Main\ \-\-man\-pages\ man\ \-\-module\-version\ 1.0 280 \ \ \-\-os\-arch\ "x86_x64"\ \-\-os\-name\ "Mac\ OS\ X" 281 \ \ \-\-os\-version\ "10.10.5"\ greetingsmod 282 \f[R] 283 .fi 284 .SH JMOD HASH EXAMPLE 285 .PP 286 The following example demonstrates what happens when you try to link a 287 leaf module (in this example, \f[CB]ma\f[R]) with a required module 288 (\f[CB]mb\f[R]), and the hash value recorded in the required module 289 doesn\[aq]t match that of the leaf module. 290 .IP "1." 3 291 Create and compile the following \f[CB]\&.java\f[R] files: 292 .RS 4 293 .IP \[bu] 2 294 \f[CB]jmodhashex/src/ma/module\-info.java\f[R] 295 .RS 2 296 .IP 297 .nf 298 \f[CB] 299 module\ ma\ { 300 \ \ requires\ mb; 301 } 302 \f[R] 303 .fi 304 .RE 305 .IP \[bu] 2 306 \f[CB]jmodhashex/src/mb/module\-info.java\f[R] 307 .RS 2 308 .IP 309 .nf 310 \f[CB] 311 module\ mb\ { 312 } 313 \f[R] 314 .fi 315 .RE 316 .IP \[bu] 2 317 \f[CB]jmodhashex2/src/ma/module\-info.java\f[R] 318 .RS 2 319 .IP 320 .nf 321 \f[CB] 322 module\ ma\ { 323 \ \ requires\ mb; 324 } 325 \f[R] 326 .fi 327 .RE 328 .IP \[bu] 2 329 \f[CB]jmodhashex2/src/mb/module\-info.java\f[R] 330 .RS 2 331 .IP 332 .nf 333 \f[CB] 334 module\ mb\ { 335 } 336 \f[R] 337 .fi 338 .RE 339 .RE 340 .IP "2." 3 341 Create a JMOD archive for each module. 342 Create the directories \f[CB]jmodhashex/jmods\f[R] and 343 \f[CB]jmodhashex2/jmods\f[R], and then run the following commands from the 344 \f[CB]jmodhashex\f[R] directory, then from the \f[CB]jmodhashex2\f[R] 345 directory: 346 .RS 4 347 .IP \[bu] 2 348 \f[CB]jmod\ create\ \-\-class\-path\ mods/ma\ jmods/ma.jmod\f[R] 349 .IP \[bu] 2 350 \f[CB]jmod\ create\ \-\-class\-path\ mods/mb\ jmods/mb.jmod\f[R] 351 .RE 352 .IP "3." 3 353 Optionally preview the \f[CB]jmod\ hash\f[R] command. 354 Run the following command from the \f[CB]jmodhashex\f[R] directory: 355 .RS 4 356 .PP 357 \f[CB]jmod\ hash\ \-\-dry\-run\ \-module\-path\ jmods\ \-\-hash\-modules\ .*\f[R] 358 .PP 359 The command prints the following: 360 .IP 361 .nf 362 \f[CB] 363 Dry\ run: 364 mb 365 \ \ hashes\ ma\ SHA\-256\ 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a 366 \f[R] 367 .fi 368 .PP 369 This indicates that the \f[CB]jmod\ hash\f[R] command (without the 370 \f[CB]\-\-dry\-run\f[R] option) will record the hash value of the leaf 371 module \f[CB]ma\f[R] in the module \f[CB]mb\f[R]. 372 .RE 373 .IP "4." 3 374 Record hash values in the JMOD archive files contained in the 375 \f[CB]jmodhashex\f[R] directory. 376 Run the following command from the \f[CB]jmodhashex\f[R] directory: 377 .RS 4 378 .RS 379 .PP 380 \f[CB]jmod\ hash\ \-\-module\-path\ jmods\ \-\-hash\-modules\ .*\f[R] 381 .RE 382 .PP 383 The command prints the following: 384 .RS 385 .PP 386 \f[CB]Hashes\ are\ recorded\ in\ module\ mb\f[R] 387 .RE 388 .RE 389 .IP "5." 3 390 Print information about each JMOD archive contained in the 391 \f[CB]jmodhashex\f[R] directory. 392 Run the highlighted commands from the \f[CB]jmodhashex\f[R] directory: 393 .RS 4 394 .IP 395 .nf 396 \f[CB] 397 jmod\ describe\ jmods/ma.jmod 398 399 ma 400 \ \ requires\ mandated\ java.base 401 \ \ requires\ mb 402 403 jmod\ describe\ jmods/mb.jmod 404 405 mb 406 \ \ requires\ mandated\ java.base 407 \ \ hashes\ ma\ SHA\-256\ 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a 408 \f[R] 409 .fi 410 .RE 411 .IP "6." 3 412 Attempt to create a runtime image that contains the module \f[CB]ma\f[R] 413 from the directory \f[CB]jmodhashex2\f[R] but the module \f[CB]mb\f[R] from 414 the directory \f[CB]jmodhashex\f[R]. 415 Run the following command from the \f[CB]jmodhashex2\f[R] directory: 416 .RS 4 417 .IP \[bu] 2 418 \f[B]Oracle Solaris, Linux, and OS X:\f[R] 419 .RS 2 420 .RS 421 .PP 422 \f[CB]jlink\ \-\-module\-path\ $JAVA_HOME/jmods:jmods/ma.jmod:../jmodhashex/jmods/mb.jmod\ \-\-add\-modules\ ma\ \-\-output\ ma\-app\f[R] 423 .RE 424 .RE 425 .IP \[bu] 2 426 \f[B]Windows:\f[R] 427 .RS 2 428 .RS 429 .PP 430 \f[CB]jlink\ \-\-module\-path\ %JAVA_HOME%/jmods;jmods/ma.jmod;../jmodhashex/jmods/mb.jmod\ \-\-add\-modules\ ma\ \-\-output\ ma\-app\f[R] 431 .RE 432 .RE 433 .PP 434 The command prints an error message similar to the following: 435 .IP 436 .nf 437 \f[CB] 438 Error:\ Hash\ of\ ma\ (a2d77889b0cb067df02a3abc39b01ac1151966157a68dc4241562c60499150d2)\ differs\ to 439 expected\ hash\ (07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a)\ recorded\ in\ mb 440 \f[R] 441 .fi 442 .RE