jdk

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

295
META-INF/
296
META-INF/MANIFEST.MF
297
com/
298
com/foo/
299
com/foo/Hello.class
300
com/foo/NameProvider.class
301
META-INF/versions/10/com/
302
META-INF/versions/10/com/foo/
303
META-INF/versions/10/com/foo/NameProvider.class
304
\f[R]
305
.fi
306
.PP
307
As well as other information, the file \f[V]META-INF/MANIFEST.MF\f[R],
308
will contain the following lines to indicate that this is a multirelease
309
JAR file with an entry point of \f[V]com.foo.Hello\f[R].
310
.IP
311
.nf
312
\f[CB]
313
\&...
314
Main-Class: com.foo.Hello
315
Multi-Release: true
316
\f[R]
317
.fi
318
.PP
319
Assuming that the \f[V]com.foo.Hello\f[R] class calls a method on the
320
\f[V]com.foo.NameProvider\f[R] class, running the program using JDK 10
321
will ensure that the \f[V]com.foo.NameProvider\f[R] class is the one in
322
\f[V]META-INF/versions/10/com/foo/\f[R].
323
Running the program using JDK 8 will ensure that the
324
\f[V]com.foo.NameProvider\f[R] class is the one at the root of the JAR,
325
in \f[V]com/foo\f[R].
326
.RE
327
.IP \[bu] 2
328
Create an archive, \f[V]my.jar\f[R], by reading options and lists of
329
class files from the file \f[V]classes.list\f[R].
330
.RS 2
331
.PP
332
\f[B]Note:\f[R]
333
.PP
334
To shorten or simplify the \f[V]jar\f[R] command, you can provide an arg
335
file that lists the files to include in the JAR file and pass it to the
336
\f[V]jar\f[R] command with the at sign (\f[V]\[at]\f[R]) as a prefix.
337
.RS
338
.PP
339
\f[V]jar --create --file my.jar \[at]classes.list\f[R]
340
.RE
341
.PP
342
If one or more entries in the arg file cannot be found then the jar
343
command fails without creating the JAR file.
344
.RE
345