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] method for the 152 syntax of \f[I]glob\-pattern\f[R]. 153 See the \f[B]\f[BC]Pattern\f[B]\f[R] class for the syntax of 154 \f[I]regex\-pattern\f[R], which represents a regular expression. 155 .RE 156 .TP 157 .B \f[CB]\-\-hash\-modules\f[R] \f[I]regex\-pattern\f[R] 158 Determines the leaf modules and records the hashes of the dependencies 159 directly and indirectly requiring them, based on the module graph of the 160 modules matching the given \f[I]regex\-pattern\f[R]. 161 The hashes are recorded in the JMOD archive file being created, or a 162 JMOD archive or modular JAR on the module path specified by the 163 \f[CB]jmod\ hash\f[R] command. 164 .RS 165 .RE 166 .TP 167 .B \f[CB]\-\-header\-files\f[R] \f[I]path\f[R] 168 Specifies the location of header files to copy into the resulting JMOD 169 file. 170 .RS 171 .RE 172 .TP 173 .B \f[CB]\-\-help\f[R] or \f[CB]\-h\f[R] 174 Prints a usage message. 175 .RS 176 .RE 177 .TP 178 .B \f[CB]\-\-help\-extra\f[R] 179 Prints help for extra options. 180 .RS 181 .RE 182 .TP 183 .B \f[CB]\-\-legal\-notices\f[R] \f[I]path\f[R] 184 Specifies the location of legal notices to copy into the resulting JMOD 185 file. 186 .RS 187 .RE 188 .TP 189 .B \f[CB]\-\-libs\f[R] \f[I]path\f[R] 190 Specifies location of native libraries to copy into the resulting JMOD 191 file. 192 .RS 193 .RE 194 .TP 195 .B \f[CB]\-\-main\-class\f[R] \f[I]class\-name\f[R] 196 Specifies main class to record in the module\-info.class file. 197 .RS 198 .RE 199 .TP 200 .B \f[CB]\-\-man\-pages\f[R] \f[I]path\f[R] 201 Specifies the location of man pages to copy into the resulting JMOD 202 file. 203 .RS 204 .RE 205 .TP 206 .B \f[CB]\-\-module\-version\f[R] \f[I]module\-version\f[R] 207 Specifies the module version to record in the module\-info.class file. 208 .RS 209 .RE 210 .TP 211 .B \f[CB]\-\-module\-path\f[R] \f[I]path\f[R] or \f[CB]\-p\f[R] \f[I]path\f[R] 212 Specifies the module path. 213 This option is required if you also specify \f[CB]\-\-hash\-modules\f[R]. 214 .RS 215 .RE 216 .TP 217 .B \f[CB]\-\-target\-platform\f[R] \f[I]platform\f[R] 218 Specifies the target platform. 219 .RS 220 .RE 221 .TP 222 .B \f[CB]\-\-version\f[R] 223 Prints version information of the \f[CB]jmod\f[R] tool. 224 .RS 225 .RE 226 .TP 227 .B \f[CB]\@\f[R]\f[I]filename\f[R] 228 Reads options from the specified file. 229 .RS 230 .PP 231 An options file is a text file that contains the options and values that 232 you would ordinarily enter in a command prompt. 233 Options may appear on one line or on several lines. 234 You may not specify environment variables for path names. 235 You may comment out lines by prefixinga hash symbol (\f[CB]#\f[R]) to the 236 beginning of the line. 237 .PP 238 The following is an example of an options file for the \f[CB]jmod\f[R] 239 command: 240 .IP 241 .nf 242 \f[CB] 243 #Wed\ Dec\ 07\ 00:40:19\ EST\ 2016 244 create\ \-\-class\-path\ mods/com.greetings\ \-\-module\-path\ mlib 245 \ \ \-\-cmds\ commands\ \-\-config\ configfiles\ \-\-header\-files\ src/h 246 \ \ \-\-libs\ lib\ \-\-main\-class\ com.greetings.Main 247 \ \ \-\-man\-pages\ man\ \-\-module\-version\ 1.0 248 \ \ \-\-os\-arch\ "x86_x64"\ \-\-os\-name\ "Mac\ OS\ X" 249 \ \ \-\-os\-version\ "10.10.5"\ greetingsmod 250 \f[R] 251 .fi 252 .RE 253 .SH EXTRA OPTIONS FOR JMOD 254 .PP 255 In addition to the options described in \f[B]Options for jmod\f[R], the 256 following are extra options that can be used with the command. 257 .TP 258 .B \f[CB]\-\-do\-not\-resolve\-by\-default\f[R] 259 Exclude from the default root set of modules 260 .RS 261 .RE 262 .TP 263 .B \f[CB]\-\-warn\-if\-resolved\f[R] 264 Hint for a tool to issue a warning if the module is resolved. 265 One of deprecated, deprecated\-for\-removal, or incubating. 266 .RS 267 .RE 268 .SH JMOD CREATE EXAMPLE 269 .PP 270 The following is an example of creating a JMOD file: 271 .IP 272 .nf 273 \f[CB] 274 jmod\ create\ \-\-class\-path\ mods/com.greetings\ \-\-cmds\ commands 275 \ \ \-\-config\ configfiles\ \-\-header\-files\ src/h\ \-\-libs\ lib 276 \ \ \-\-main\-class\ com.greetings.Main\ \-\-man\-pages\ man\ \-\-module\-version\ 1.0 277 \ \ \-\-os\-arch\ "x86_x64"\ \-\-os\-name\ "Mac\ OS\ X" 278 \ \ \-\-os\-version\ "10.10.5"\ greetingsmod 279 \f[R] 280 .fi 281 .SH JMOD HASH EXAMPLE 282 .PP 283 The following example demonstrates what happens when you try to link a 284 leaf module (in this example, \f[CB]ma\f[R]) with a required module 285 (\f[CB]mb\f[R]), and the hash value recorded in the required module 286 doesn\[aq]t match that of the leaf module. 287 .IP "1." 3 288 Create and compile the following \f[CB]\&.java\f[R] files: 289 .RS 4 290 .IP \[bu] 2 291 \f[CB]jmodhashex/src/ma/module\-info.java\f[R] 292 .RS 2 293 .IP 294 .nf 295 \f[CB] 296 module\ ma\ { 297 \ \ requires\ mb; 298 } 299 \f[R] 300 .fi 301 .RE 302 .IP \[bu] 2 303 \f[CB]jmodhashex/src/mb/module\-info.java\f[R] 304 .RS 2 305 .IP 306 .nf 307 \f[CB] 308 module\ mb\ { 309 } 310 \f[R] 311 .fi 312 .RE 313 .IP \[bu] 2 314 \f[CB]jmodhashex2/src/ma/module\-info.java\f[R] 315 .RS 2 316 .IP 317 .nf 318 \f[CB] 319 module\ ma\ { 320 \ \ requires\ mb; 321 } 322 \f[R] 323 .fi 324 .RE 325 .IP \[bu] 2 326 \f[CB]jmodhashex2/src/mb/module\-info.java\f[R] 327 .RS 2 328 .IP 329 .nf 330 \f[CB] 331 module\ mb\ { 332 } 333 \f[R] 334 .fi 335 .RE 336 .RE 337 .IP "2." 3 338 Create a JMOD archive for each module. 339 Create the directories \f[CB]jmodhashex/jmods\f[R] and 340 \f[CB]jmodhashex2/jmods\f[R], and then run the following commands from the 341 \f[CB]jmodhashex\f[R] directory, then from the \f[CB]jmodhashex2\f[R] 342 directory: 343 .RS 4 344 .IP \[bu] 2 345 \f[CB]jmod\ create\ \-\-class\-path\ mods/ma\ jmods/ma.jmod\f[R] 346 .IP \[bu] 2 347 \f[CB]jmod\ create\ \-\-class\-path\ mods/mb\ jmods/mb.jmod\f[R] 348 .RE 349 .IP "3." 3 350 Optionally preview the \f[CB]jmod\ hash\f[R] command. 351 Run the following command from the \f[CB]jmodhashex\f[R] directory: 352 .RS 4 353 .PP 354 \f[CB]jmod\ hash\ \-\-dry\-run\ \-module\-path\ jmods\ \-\-hash\-modules\ .*\f[R] 355 .PP 356 The command prints the following: 357 .IP 358 .nf 359 \f[CB] 360 Dry\ run: 361 mb 362 \ \ hashes\ ma\ SHA\-256\ 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a 363 \f[R] 364 .fi 365 .PP 366 This indicates that the \f[CB]jmod\ hash\f[R] command (without the 367 \f[CB]\-\-dry\-run\f[R] option) will record the hash value of the leaf 368 module \f[CB]ma\f[R] in the module \f[CB]mb\f[R]. 369 .RE 370 .IP "4." 3 371 Record hash values in the JMOD archive files contained in the 372 \f[CB]jmodhashex\f[R] directory. 373 Run the following command from the \f[CB]jmodhashex\f[R] directory: 374 .RS 4 375 .RS 376 .PP 377 \f[CB]jmod\ hash\ \-\-module\-path\ jmods\ \-\-hash\-modules\ .*\f[R] 378 .RE 379 .PP 380 The command prints the following: 381 .RS 382 .PP 383 \f[CB]Hashes\ are\ recorded\ in\ module\ mb\f[R] 384 .RE 385 .RE 386 .IP "5." 3 387 Print information about each JMOD archive contained in the 388 \f[CB]jmodhashex\f[R] directory. 389 Run the highlighted commands from the \f[CB]jmodhashex\f[R] directory: 390 .RS 4 391 .IP 392 .nf 393 \f[CB] 394 jmod\ describe\ jmods/ma.jmod 395 396 ma 397 \ \ requires\ mandated\ java.base 398 \ \ requires\ mb 399 400 jmod\ describe\ jmods/mb.jmod 401 402 mb 403 \ \ requires\ mandated\ java.base 404 \ \ hashes\ ma\ SHA\-256\ 07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a 405 \f[R] 406 .fi 407 .RE 408 .IP "6." 3 409 Attempt to create a runtime image that contains the module \f[CB]ma\f[R] 410 from the directory \f[CB]jmodhashex2\f[R] but the module \f[CB]mb\f[R] from 411 the directory \f[CB]jmodhashex\f[R]. 412 Run the following command from the \f[CB]jmodhashex2\f[R] directory: 413 .RS 4 414 .IP \[bu] 2 415 \f[B]Oracle Solaris, Linux, and OS X:\f[R] 416 .RS 2 417 .RS 418 .PP 419 \f[CB]jlink\ \-\-module\-path\ $JAVA_HOME/jmods:jmods/ma.jmod:../jmodhashex/jmods/mb.jmod\ \-\-add\-modules\ ma\ \-\-output\ ma\-app\f[R] 420 .RE 421 .RE 422 .IP \[bu] 2 423 \f[B]Windows:\f[R] 424 .RS 2 425 .RS 426 .PP 427 \f[CB]jlink\ \-\-module\-path\ %JAVA_HOME%/jmods;jmods/ma.jmod;../jmodhashex/jmods/mb.jmod\ \-\-add\-modules\ ma\ \-\-output\ ma\-app\f[R] 428 .RE 429 .RE 430 .PP 431 The command prints an error message similar to the following: 432 .IP 433 .nf 434 \f[CB] 435 Error:\ Hash\ of\ ma\ (a2d77889b0cb067df02a3abc39b01ac1151966157a68dc4241562c60499150d2)\ differs\ to 436 expected\ hash\ (07667d5032004b37b42ec2bb81b46df380cf29e66962a16481ace2e71e74073a)\ recorded\ in\ mb 437 \f[R] 438 .fi 439 .RE