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" "2020" "JDK 14" "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