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 "JAR" "1" "2018" "JDK 13" "JDK Commands" 25 .hy 26 .SH NAME 27 .PP 28 jar \- create an archive for classes and resources, and manipulate or 29 restore individual classes or resources from an archive 30 .SH SYNOPSIS 31 .PP 32 \f[CB]jar\f[R] [\f[I]OPTION\f[R] ...] [ [\f[CB]\-\-release\f[R] 33 \f[I]VERSION\f[R]] [\f[CB]\-C\f[R] \f[I]dir\f[R]] \f[I]files\f[R]] ... 34 .SH DESCRIPTION 35 .PP 36 The \f[CB]jar\f[R] command is a general\-purpose archiving and compression 37 tool, based on the ZIP and ZLIB compression formats. 38 Initially, the \f[CB]jar\f[R] command was designed to package Java applets 39 (not supported since JDK 11) or applications; however, beginning with 40 JDK 9, users can use the \f[CB]jar\f[R] command to create modular JARs. 41 For transportation and deployment, it\[aq]s usually more convenient to 42 package modules as modular JARs. 43 .PP 44 The syntax for the \f[CB]jar\f[R] command resembles the syntax for the 45 \f[CB]tar\f[R] command. 46 It has several main operation modes, defined by one of the mandatory 47 operation arguments. 48 Other arguments are either options that modify the behavior of the 49 operation or are required to perform the operation. 50 .PP 51 When modules or the components of an application (files, images and 52 sounds) are combined into a single archive, they can be downloaded by a 53 Java agent (such as a browser) in a single HTTP transaction, rather than 54 requiring a new connection for each piece. 55 This dramatically improves download times. 56 The \f[CB]jar\f[R] command also compresses files, which further improves 57 download time. 58 The \f[CB]jar\f[R] command also enables individual entries in a file to be 59 signed so that their origin can be authenticated. 60 A JAR file can be used as a class path entry, whether or not it\[aq]s 61 compressed. 62 .PP 63 An archive becomes a modular JAR when you include a module descriptor, 64 \f[CB]module\-info.class\f[R], in the root of the given directories or in 65 the root of the \f[CB]\&.jar\f[R] archive. 66 The following operations described in \f[B]Operation Modifiers Valid 67 Only in Create and Update Modes\f[R] are valid only when creating or 68 updating a modular jar or updating an existing non\-modular jar: 69 .IP \[bu] 2 70 \f[CB]\-\-module\-version\f[R] 71 .IP \[bu] 2 72 \f[CB]\-\-hash\-modules\f[R] 73 .IP \[bu] 2 74 \f[CB]\-\-module\-path\f[R] 75 .PP 76 \f[B]Note:\f[R] 77 .PP 78 All mandatory or optional arguments for long options are also mandatory 79 or optional for any corresponding short options. 80 .SH MAIN OPERATION MODES 81 .PP 82 When using the \f[CB]jar\f[R] command, you must specify the operation for 83 it to perform. 84 You specify the operation mode for the \f[CB]jar\f[R] command by including 85 the appropriate operation arguments described in this section. 86 You can mix an operation argument with other one\-letter options. 87 Generally the operation argument is the first argument specified on the 88 command line. 89 .TP 90 .B \f[CB]\-c\f[R] or \f[CB]\-\-create\f[R] 91 Creates the archive. 92 .RS 93 .RE 94 .TP 95 .B \f[CB]\-i=\f[R]\f[I]FILE\f[R] or \f[CB]\-\-generate\-index=\f[R]\f[I]FILE\f[R] 96 Generates index information for the specified JAR file. 97 .RS 98 .RE 99 .TP 100 .B \f[CB]\-t\f[R] or \f[CB]\-\-list\f[R] 101 Lists the table of contents for the archive. 102 .RS 103 .RE 104 .TP 105 .B \f[CB]\-u\f[R] or \f[CB]\-\-update\f[R] 106 Updates an existing JAR file. 107 .RS 108 .RE 109 .TP 110 .B \f[CB]\-x\f[R] or \f[CB]\-\-extract\f[R] 111 Extracts the named (or all) files from the archive. 112 .RS 113 .RE 114 .TP 115 .B \f[CB]\-d\f[R] or \f[CB]\-\-describe\-module\f[R] 116 Prints the module descriptor or automatic module name. 117 .RS 118 .RE 119 .SH OPERATION MODIFIERS VALID IN ANY MODE 120 .PP 121 You can use the following options to customize the actions of any 122 operation mode included in the \f[CB]jar\f[R] command. 123 .TP 124 .B \f[CB]\-C\f[R] \f[I]DIR\f[R] 125 Changes the specified directory and includes the \f[I]files\f[R] 126 specified at the end of the command line. 127 .RS 128 .PP 129 \f[CB]jar\f[R] [\f[I]OPTION\f[R] ...] [ [\f[CB]\-\-release\f[R] 130 \f[I]VERSION\f[R]] [\f[CB]\-C\f[R] \f[I]dir\f[R]] \f[I]files\f[R]] 131 .RE 132 .TP 133 .B \f[CB]\-f=\f[R]\f[I]FILE\f[R] or \f[CB]\-\-file=\f[R]\f[I]FILE\f[R] 134 Specifies the archive file name. 135 .RS 136 .RE 137 .TP 138 .B \f[CB]\-\-release\f[R] \f[I]VERSION\f[R] 139 Creates a multirelease JAR file. 140 Places all files specified after the option into a versioned directory 141 of the JAR file named 142 \f[CB]META\-INF/versions/\f[R]\f[I]VERSION\f[R]\f[CB]/\f[R], where 143 \f[I]VERSION\f[R] must be must be a positive integer whose value is 9 or 144 greater. 145 .RS 146 .PP 147 At run time, where more than one version of a class exists in the JAR, 148 the JDK will use the first one it finds, searching initially in the 149 directory tree whose \f[I]VERSION\f[R] number matches the JDK\[aq]s major 150 version number. 151 It will then look in directories with successively lower 152 \f[I]VERSION\f[R] numbers, and finally look in the root of the JAR. 153 .RE 154 .TP 155 .B \f[CB]\-v\f[R] or \f[CB]\-\-verbose\f[R] 156 Sends or prints verbose output to standard output. 157 .RS 158 .RE 159 .SH OPERATION MODIFIERS VALID ONLY IN CREATE AND UPDATE MODES 160 .PP 161 You can use the following options to customize the actions of the create 162 and the update main operation modes: 163 .TP 164 .B \f[CB]\-e=\f[R]\f[I]CLASSNAME\f[R] or \f[CB]\-\-main\-class=\f[R]\f[I]CLASSNAME\f[R] 165 Specifies the application entry point for standalone applications 166 bundled into a modular or executable modular JAR file. 167 .RS 168 .RE 169 .TP 170 .B \f[CB]\-m=\f[R]\f[I]FILE\f[R] or \f[CB]\-\-manifest=\f[R]\f[I]FILE\f[R] 171 Includes the manifest information from the given manifest file. 172 .RS 173 .RE 174 .TP 175 .B \f[CB]\-M\f[R] or \f[CB]\-\-no\-manifest\f[R] 176 Doesn\[aq]t create a manifest file for the entries. 177 .RS 178 .RE 179 .TP 180 .B \f[CB]\-\-module\-version=\f[R]\f[I]VERSION\f[R] 181 Specifies the module version, when creating or updating a modular JAR 182 file, or updating a non\-modular JAR file. 183 .RS 184 .RE 185 .TP 186 .B \f[CB]\-\-hash\-modules=\f[R]\f[I]PATTERN\f[R] 187 Computes and records the hashes of modules matched by the given pattern 188 and that depend upon directly or indirectly on a modular JAR file being 189 created or a non\-modular JAR file being updated. 190 .RS 191 .RE 192 .TP 193 .B \f[CB]\-p\f[R] or \f[CB]\-\-module\-path\f[R] 194 Specifies the location of module dependence for generating the hash. 195 .RS 196 .RE 197 .TP 198 .B \f[CB]\@\f[R]\f[I]file\f[R] 199 Reads \f[CB]jar\f[R] options and file names from a text file. 200 .RS 201 .RE 202 .SH OPERATION MODIFIERS VALID ONLY IN CREATE, UPDATE, AND 203 GENERATE\-INDEX MODES 204 .PP 205 You can use the following options to customize the actions of the create 206 (\f[CB]\-c\f[R] or \f[CB]\-\-create\f[R]) the update (\f[CB]\-u\f[R] or 207 \f[CB]\-\-update\f[R] ) and the generate\-index (\f[CB]\-i\f[R] or 208 \f[CB]\-\-generate\-index=\f[R]\f[I]FILE\f[R]) main operation modes: 209 .TP 210 .B \f[CB]\-0\f[R] or \f[CB]\-\-no\-compress\f[R] 211 Stores without using ZIP compression. 212 .RS 213 .RE 214 .SH OTHER OPTIONS 215 .PP 216 The following options are recognized by the \f[CB]jar\f[R] command and not 217 used with operation modes: 218 .TP 219 .B \f[CB]\-h\f[R] or \f[CB]\-\-help\f[R][\f[CB]:compat\f[R]] 220 Displays the command\-line help for the \f[CB]jar\f[R] command or 221 optionally the compatibility help. 222 .RS 223 .RE 224 .TP 225 .B \f[CB]\-\-help\-extra\f[R] 226 Displays help on extra options. 227 .RS 228 .RE 229 .TP 230 .B \f[CB]\-\-version\f[R] 231 Prints the program version. 232 .RS 233 .RE 234 .SH EXAMPLES OF JAR COMMAND SYNTAX 235 .IP \[bu] 2 236 Create an archive, \f[CB]classes.jar\f[R], that contains two class files, 237 \f[CB]Foo.class\f[R] and \f[CB]Bar.class\f[R]. 238 .RS 2 239 .RS 240 .PP 241 \f[CB]jar\ \-\-create\ \-\-file\ classes.jar\ Foo.class\ Bar.class\f[R] 242 .RE 243 .RE 244 .IP \[bu] 2 245 Create an archive, \f[CB]classes.jar\f[R], by using an existing manifest, 246 \f[CB]mymanifest\f[R], that contains all of the files in the directory 247 \f[CB]foo/\f[R]. 248 .RS 2 249 .RS 250 .PP 251 \f[CB]jar\ \-\-create\ \-\-file\ classes.jar\ \-\-manifest\ mymanifest\ \-C\ foo/\f[R] 252 .RE 253 .RE 254 .IP \[bu] 2 255 Create a modular JAR archive,\f[CB]foo.jar\f[R], where the module 256 descriptor is located in \f[CB]classes/module\-info.class\f[R]. 257 .RS 2 258 .RS 259 .PP 260 \f[CB]jar\ \-\-create\ \-\-file\ foo.jar\ \-\-main\-class\ com.foo.Main\ \-\-module\-version\ 1.0\ \-C\ foo/classes\ resources\f[R] 261 .RE 262 .RE 263 .IP \[bu] 2 264 Update an existing non\-modular JAR, \f[CB]foo.jar\f[R], to a modular JAR 265 file. 266 .RS 2 267 .RS 268 .PP 269 \f[CB]jar\ \-\-update\ \-\-file\ foo.jar\ \-\-main\-class\ com.foo.Main\ \-\-module\-version\ 1.0\ \-C\ foo/module\-info.class\f[R] 270 .RE 271 .RE 272 .IP \[bu] 2 273 Create a versioned or multi\-release JAR, \f[CB]foo.jar\f[R], that places 274 the files in the \f[CB]classes\f[R] directory at the root of the JAR, and 275 the files in the \f[CB]classes\-10\f[R] directory in the 276 \f[CB]META\-INF/versions/10\f[R] directory of the JAR. 277 .RS 2 278 .PP 279 In this example, the \f[CB]classes/com/foo\f[R] directory contains two 280 classes, \f[CB]com.foo.Hello\f[R] (the entry point class) and 281 \f[CB]com.foo.NameProvider\f[R], both compiled for JDK 8. 282 The \f[CB]classes\-10/com/foo\f[R] directory contains a different version 283 of the \f[CB]com.foo.NameProvider\f[R] class, this one containing JDK 10 284 specific code and compiled for JDK 10. 285 .PP 286 Given this setup, create a multirelease JAR file \f[CB]foo.jar\f[R] by 287 running the following command from the directory containing the 288 directories \f[CB]classes\f[R] and \f[CB]classes\-10\f[R] . 289 .RS 290 .PP 291 \f[CB]jar\ \-\-create\ \-\-file\ foo.jar\ \-\-main\-class\ com.foo.Hello\ \-C\ classes\ .\ \-\-release\ 10\ \-C\ classes\-10\ .\f[R] 292 .RE 293 .PP 294 The JAR file \f[CB]foo.jar\f[R] now contains: 295 .IP 296 .nf 297 \f[CB] 298 %\ jar\ \-tf\ foo.jar 299 300 META\-INF/ 301 META\-INF/MANIFEST.MF 302 com/ 303 com/foo/ 304 com/foo/Hello.class 305 com/foo/NameProvider.class 306 META\-INF/versions/10/com/ 307 META\-INF/versions/10/com/foo/ 308 META\-INF/versions/10/com/foo/NameProvider.class 309 \f[R] 310 .fi 311 .PP 312 As well as other information, the file \f[CB]META\-INF/MANIFEST.MF\f[R], 313 will contain the following lines to indicate that this is a multirelease 314 JAR file with an entry point of \f[CB]com.foo.Hello\f[R]. 315 .IP 316 .nf 317 \f[CB] 318 \&... 319 Main\-Class:\ com.foo.Hello 320 Multi\-Release:\ true 321 \f[R] 322 .fi 323 .PP 324 Assuming that the \f[CB]com.foo.Hello\f[R] class calls a method on the 325 \f[CB]com.foo.NameProvider\f[R] class, running the program using JDK 10 326 will ensure that the \f[CB]com.foo.NameProvider\f[R] class is the one in 327 \f[CB]META\-INF/versions/10/com/foo/\f[R]. 328 Running the program using JDK 8 will ensure that the 329 \f[CB]com.foo.NameProvider\f[R] class is the one at the root of the JAR, 330 in \f[CB]com/foo\f[R]. 331 .RE 332 .IP \[bu] 2 333 Create an archive, \f[CB]my.jar\f[R], by reading options and lists of 334 class files from the file \f[CB]classes.list\f[R]. 335 .RS 2 336 .PP 337 \f[B]Note:\f[R] 338 .PP 339 To shorten or simplify the \f[CB]jar\f[R] command, you can specify 340 arguments in a separate text file and pass it to the \f[CB]jar\f[R] 341 command with the at sign (\f[CB]\@\f[R]) as a prefix. 342 .RS 343 .PP 344 \f[CB]jar\ \-\-create\ \-\-file\ my.jar\ \@classes.list\f[R] 345 .RE 346 .RE