347 lines
11 KiB
Groff
347 lines
11 KiB
Groff
.\" Copyright (c) 1994, 2019, Oracle and/or its affiliates. All rights reserved.
|
|
.\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
|
|
.\"
|
|
.\" This code is free software; you can redistribute it and/or modify it
|
|
.\" under the terms of the GNU General Public License version 2 only, as
|
|
.\" published by the Free Software Foundation.
|
|
.\"
|
|
.\" This code is distributed in the hope that it will be useful, but WITHOUT
|
|
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
|
|
.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
|
|
.\" version 2 for more details (a copy is included in the LICENSE file that
|
|
.\" accompanied this code).
|
|
.\"
|
|
.\" You should have received a copy of the GNU General Public License version
|
|
.\" 2 along with this work; if not, write to the Free Software Foundation,
|
|
.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
|
|
.\"
|
|
.\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
|
|
.\" or visit www.oracle.com if you need additional information or have any
|
|
.\" questions.
|
|
.\"
|
|
.\" Automatically generated by Pandoc 2.3.1
|
|
.\"
|
|
.TH "JAR" "1" "2020" "JDK 14" "JDK Commands"
|
|
.hy
|
|
.SH NAME
|
|
.PP
|
|
jar \- create an archive for classes and resources, and manipulate or
|
|
restore individual classes or resources from an archive
|
|
.SH SYNOPSIS
|
|
.PP
|
|
\f[CB]jar\f[R] [\f[I]OPTION\f[R] ...] [ [\f[CB]\-\-release\f[R]
|
|
\f[I]VERSION\f[R]] [\f[CB]\-C\f[R] \f[I]dir\f[R]] \f[I]files\f[R]] ...
|
|
.SH DESCRIPTION
|
|
.PP
|
|
The \f[CB]jar\f[R] command is a general\-purpose archiving and compression
|
|
tool, based on the ZIP and ZLIB compression formats.
|
|
Initially, the \f[CB]jar\f[R] command was designed to package Java applets
|
|
(not supported since JDK 11) or applications; however, beginning with
|
|
JDK 9, users can use the \f[CB]jar\f[R] command to create modular JARs.
|
|
For transportation and deployment, it\[aq]s usually more convenient to
|
|
package modules as modular JARs.
|
|
.PP
|
|
The syntax for the \f[CB]jar\f[R] command resembles the syntax for the
|
|
\f[CB]tar\f[R] command.
|
|
It has several main operation modes, defined by one of the mandatory
|
|
operation arguments.
|
|
Other arguments are either options that modify the behavior of the
|
|
operation or are required to perform the operation.
|
|
.PP
|
|
When modules or the components of an application (files, images and
|
|
sounds) are combined into a single archive, they can be downloaded by a
|
|
Java agent (such as a browser) in a single HTTP transaction, rather than
|
|
requiring a new connection for each piece.
|
|
This dramatically improves download times.
|
|
The \f[CB]jar\f[R] command also compresses files, which further improves
|
|
download time.
|
|
The \f[CB]jar\f[R] command also enables individual entries in a file to be
|
|
signed so that their origin can be authenticated.
|
|
A JAR file can be used as a class path entry, whether or not it\[aq]s
|
|
compressed.
|
|
.PP
|
|
An archive becomes a modular JAR when you include a module descriptor,
|
|
\f[CB]module\-info.class\f[R], in the root of the given directories or in
|
|
the root of the \f[CB]\&.jar\f[R] archive.
|
|
The following operations described in \f[B]Operation Modifiers Valid
|
|
Only in Create and Update Modes\f[R] are valid only when creating or
|
|
updating a modular jar or updating an existing non\-modular jar:
|
|
.IP \[bu] 2
|
|
\f[CB]\-\-module\-version\f[R]
|
|
.IP \[bu] 2
|
|
\f[CB]\-\-hash\-modules\f[R]
|
|
.IP \[bu] 2
|
|
\f[CB]\-\-module\-path\f[R]
|
|
.PP
|
|
\f[B]Note:\f[R]
|
|
.PP
|
|
All mandatory or optional arguments for long options are also mandatory
|
|
or optional for any corresponding short options.
|
|
.SH MAIN OPERATION MODES
|
|
.PP
|
|
When using the \f[CB]jar\f[R] command, you must specify the operation for
|
|
it to perform.
|
|
You specify the operation mode for the \f[CB]jar\f[R] command by including
|
|
the appropriate operation arguments described in this section.
|
|
You can mix an operation argument with other one\-letter options.
|
|
Generally the operation argument is the first argument specified on the
|
|
command line.
|
|
.TP
|
|
.B \f[CB]\-c\f[R] or \f[CB]\-\-create\f[R]
|
|
Creates the archive.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-i=\f[R]\f[I]FILE\f[R] or \f[CB]\-\-generate\-index=\f[R]\f[I]FILE\f[R]
|
|
Generates index information for the specified JAR file.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-t\f[R] or \f[CB]\-\-list\f[R]
|
|
Lists the table of contents for the archive.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-u\f[R] or \f[CB]\-\-update\f[R]
|
|
Updates an existing JAR file.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-x\f[R] or \f[CB]\-\-extract\f[R]
|
|
Extracts the named (or all) files from the archive.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-d\f[R] or \f[CB]\-\-describe\-module\f[R]
|
|
Prints the module descriptor or automatic module name.
|
|
.RS
|
|
.RE
|
|
.SH OPERATION MODIFIERS VALID IN ANY MODE
|
|
.PP
|
|
You can use the following options to customize the actions of any
|
|
operation mode included in the \f[CB]jar\f[R] command.
|
|
.TP
|
|
.B \f[CB]\-C\f[R] \f[I]DIR\f[R]
|
|
Changes the specified directory and includes the \f[I]files\f[R]
|
|
specified at the end of the command line.
|
|
.RS
|
|
.PP
|
|
\f[CB]jar\f[R] [\f[I]OPTION\f[R] ...] [ [\f[CB]\-\-release\f[R]
|
|
\f[I]VERSION\f[R]] [\f[CB]\-C\f[R] \f[I]dir\f[R]] \f[I]files\f[R]]
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-f=\f[R]\f[I]FILE\f[R] or \f[CB]\-\-file=\f[R]\f[I]FILE\f[R]
|
|
Specifies the archive file name.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-release\f[R] \f[I]VERSION\f[R]
|
|
Creates a multirelease JAR file.
|
|
Places all files specified after the option into a versioned directory
|
|
of the JAR file named
|
|
\f[CB]META\-INF/versions/\f[R]\f[I]VERSION\f[R]\f[CB]/\f[R], where
|
|
\f[I]VERSION\f[R] must be must be a positive integer whose value is 9 or
|
|
greater.
|
|
.RS
|
|
.PP
|
|
At run time, where more than one version of a class exists in the JAR,
|
|
the JDK will use the first one it finds, searching initially in the
|
|
directory tree whose \f[I]VERSION\f[R] number matches the JDK\[aq]s major
|
|
version number.
|
|
It will then look in directories with successively lower
|
|
\f[I]VERSION\f[R] numbers, and finally look in the root of the JAR.
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-v\f[R] or \f[CB]\-\-verbose\f[R]
|
|
Sends or prints verbose output to standard output.
|
|
.RS
|
|
.RE
|
|
.SH OPERATION MODIFIERS VALID ONLY IN CREATE AND UPDATE MODES
|
|
.PP
|
|
You can use the following options to customize the actions of the create
|
|
and the update main operation modes:
|
|
.TP
|
|
.B \f[CB]\-e=\f[R]\f[I]CLASSNAME\f[R] or \f[CB]\-\-main\-class=\f[R]\f[I]CLASSNAME\f[R]
|
|
Specifies the application entry point for standalone applications
|
|
bundled into a modular or executable modular JAR file.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-m=\f[R]\f[I]FILE\f[R] or \f[CB]\-\-manifest=\f[R]\f[I]FILE\f[R]
|
|
Includes the manifest information from the given manifest file.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-M\f[R] or \f[CB]\-\-no\-manifest\f[R]
|
|
Doesn\[aq]t create a manifest file for the entries.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-module\-version=\f[R]\f[I]VERSION\f[R]
|
|
Specifies the module version, when creating or updating a modular JAR
|
|
file, or updating a non\-modular JAR file.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-hash\-modules=\f[R]\f[I]PATTERN\f[R]
|
|
Computes and records the hashes of modules matched by the given pattern
|
|
and that depend upon directly or indirectly on a modular JAR file being
|
|
created or a non\-modular JAR file being updated.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-p\f[R] or \f[CB]\-\-module\-path\f[R]
|
|
Specifies the location of module dependence for generating the hash.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\@\f[R]\f[I]file\f[R]
|
|
Reads \f[CB]jar\f[R] options and file names from a text file.
|
|
.RS
|
|
.RE
|
|
.SH OPERATION MODIFIERS VALID ONLY IN CREATE, UPDATE, AND
|
|
GENERATE\-INDEX MODES
|
|
.PP
|
|
You can use the following options to customize the actions of the create
|
|
(\f[CB]\-c\f[R] or \f[CB]\-\-create\f[R]) the update (\f[CB]\-u\f[R] or
|
|
\f[CB]\-\-update\f[R] ) and the generate\-index (\f[CB]\-i\f[R] or
|
|
\f[CB]\-\-generate\-index=\f[R]\f[I]FILE\f[R]) main operation modes:
|
|
.TP
|
|
.B \f[CB]\-0\f[R] or \f[CB]\-\-no\-compress\f[R]
|
|
Stores without using ZIP compression.
|
|
.RS
|
|
.RE
|
|
.SH OTHER OPTIONS
|
|
.PP
|
|
The following options are recognized by the \f[CB]jar\f[R] command and not
|
|
used with operation modes:
|
|
.TP
|
|
.B \f[CB]\-h\f[R] or \f[CB]\-\-help\f[R][\f[CB]:compat\f[R]]
|
|
Displays the command\-line help for the \f[CB]jar\f[R] command or
|
|
optionally the compatibility help.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-help\-extra\f[R]
|
|
Displays help on extra options.
|
|
.RS
|
|
.RE
|
|
.TP
|
|
.B \f[CB]\-\-version\f[R]
|
|
Prints the program version.
|
|
.RS
|
|
.RE
|
|
.SH EXAMPLES OF JAR COMMAND SYNTAX
|
|
.IP \[bu] 2
|
|
Create an archive, \f[CB]classes.jar\f[R], that contains two class files,
|
|
\f[CB]Foo.class\f[R] and \f[CB]Bar.class\f[R].
|
|
.RS 2
|
|
.RS
|
|
.PP
|
|
\f[CB]jar\ \-\-create\ \-\-file\ classes.jar\ Foo.class\ Bar.class\f[R]
|
|
.RE
|
|
.RE
|
|
.IP \[bu] 2
|
|
Create an archive, \f[CB]classes.jar\f[R], by using an existing manifest,
|
|
\f[CB]mymanifest\f[R], that contains all of the files in the directory
|
|
\f[CB]foo/\f[R].
|
|
.RS 2
|
|
.RS
|
|
.PP
|
|
\f[CB]jar\ \-\-create\ \-\-file\ classes.jar\ \-\-manifest\ mymanifest\ \-C\ foo/\f[R]
|
|
.RE
|
|
.RE
|
|
.IP \[bu] 2
|
|
Create a modular JAR archive,\f[CB]foo.jar\f[R], where the module
|
|
descriptor is located in \f[CB]classes/module\-info.class\f[R].
|
|
.RS 2
|
|
.RS
|
|
.PP
|
|
\f[CB]jar\ \-\-create\ \-\-file\ foo.jar\ \-\-main\-class\ com.foo.Main\ \-\-module\-version\ 1.0\ \-C\ foo/classes\ resources\f[R]
|
|
.RE
|
|
.RE
|
|
.IP \[bu] 2
|
|
Update an existing non\-modular JAR, \f[CB]foo.jar\f[R], to a modular JAR
|
|
file.
|
|
.RS 2
|
|
.RS
|
|
.PP
|
|
\f[CB]jar\ \-\-update\ \-\-file\ foo.jar\ \-\-main\-class\ com.foo.Main\ \-\-module\-version\ 1.0\ \-C\ foo/module\-info.class\f[R]
|
|
.RE
|
|
.RE
|
|
.IP \[bu] 2
|
|
Create a versioned or multi\-release JAR, \f[CB]foo.jar\f[R], that places
|
|
the files in the \f[CB]classes\f[R] directory at the root of the JAR, and
|
|
the files in the \f[CB]classes\-10\f[R] directory in the
|
|
\f[CB]META\-INF/versions/10\f[R] directory of the JAR.
|
|
.RS 2
|
|
.PP
|
|
In this example, the \f[CB]classes/com/foo\f[R] directory contains two
|
|
classes, \f[CB]com.foo.Hello\f[R] (the entry point class) and
|
|
\f[CB]com.foo.NameProvider\f[R], both compiled for JDK 8.
|
|
The \f[CB]classes\-10/com/foo\f[R] directory contains a different version
|
|
of the \f[CB]com.foo.NameProvider\f[R] class, this one containing JDK 10
|
|
specific code and compiled for JDK 10.
|
|
.PP
|
|
Given this setup, create a multirelease JAR file \f[CB]foo.jar\f[R] by
|
|
running the following command from the directory containing the
|
|
directories \f[CB]classes\f[R] and \f[CB]classes\-10\f[R] .
|
|
.RS
|
|
.PP
|
|
\f[CB]jar\ \-\-create\ \-\-file\ foo.jar\ \-\-main\-class\ com.foo.Hello\ \-C\ classes\ .\ \-\-release\ 10\ \-C\ classes\-10\ .\f[R]
|
|
.RE
|
|
.PP
|
|
The JAR file \f[CB]foo.jar\f[R] now contains:
|
|
.IP
|
|
.nf
|
|
\f[CB]
|
|
%\ jar\ \-tf\ foo.jar
|
|
|
|
META\-INF/
|
|
META\-INF/MANIFEST.MF
|
|
com/
|
|
com/foo/
|
|
com/foo/Hello.class
|
|
com/foo/NameProvider.class
|
|
META\-INF/versions/10/com/
|
|
META\-INF/versions/10/com/foo/
|
|
META\-INF/versions/10/com/foo/NameProvider.class
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
As well as other information, the file \f[CB]META\-INF/MANIFEST.MF\f[R],
|
|
will contain the following lines to indicate that this is a multirelease
|
|
JAR file with an entry point of \f[CB]com.foo.Hello\f[R].
|
|
.IP
|
|
.nf
|
|
\f[CB]
|
|
\&...
|
|
Main\-Class:\ com.foo.Hello
|
|
Multi\-Release:\ true
|
|
\f[R]
|
|
.fi
|
|
.PP
|
|
Assuming that the \f[CB]com.foo.Hello\f[R] class calls a method on the
|
|
\f[CB]com.foo.NameProvider\f[R] class, running the program using JDK 10
|
|
will ensure that the \f[CB]com.foo.NameProvider\f[R] class is the one in
|
|
\f[CB]META\-INF/versions/10/com/foo/\f[R].
|
|
Running the program using JDK 8 will ensure that the
|
|
\f[CB]com.foo.NameProvider\f[R] class is the one at the root of the JAR,
|
|
in \f[CB]com/foo\f[R].
|
|
.RE
|
|
.IP \[bu] 2
|
|
Create an archive, \f[CB]my.jar\f[R], by reading options and lists of
|
|
class files from the file \f[CB]classes.list\f[R].
|
|
.RS 2
|
|
.PP
|
|
\f[B]Note:\f[R]
|
|
.PP
|
|
To shorten or simplify the \f[CB]jar\f[R] command, you can specify
|
|
arguments in a separate text file and pass it to the \f[CB]jar\f[R]
|
|
command with the at sign (\f[CB]\@\f[R]) as a prefix.
|
|
.RS
|
|
.PP
|
|
\f[CB]jar\ \-\-create\ \-\-file\ my.jar\ \@classes.list\f[R]
|
|
.RE
|
|
.RE
|