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