t
 Copyright (c) 1997, 2013, 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.

 Arch: generic
 Software: JDK 8
 Date: 21 November 2013
 SectDesc: Basic Tools
 Title: jar.1

 jar 1 "21 November 2013" "JDK 8" "Basic Tools"
 -----------------------------------------------------------------
 * Define some portability stuff
 -----------------------------------------------------------------
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 http://bugs.debian.org/507673
 http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 -----------------------------------------------------------------
 * set default formatting
 -----------------------------------------------------------------
 disable hyphenation
 disable justification (adjust text to left margin only)
 -----------------------------------------------------------------
 * MAIN CONTENT STARTS HERE *
 -----------------------------------------------------------------


 NAME 
jar - Manipulates Java Archive (JAR) files.

 SYNOPSIS 
Create JAR file

 

jar c[efmMnv0] [entrypoint] [jarfile] [manifest] [-C dir] file ... [-Joption ...] [@arg-file ...]

 

Update JAR file

 

jar u[efmMnv0] [entrypoint] [jarfile] [manifest] [-C dir] file ... [-Joption ...] [@arg-file ...]

 

Extract JAR file

 

jar x[vf] [jarfile] file ... [-Joption ...] [@arg-file ...]

 

List Contents of JAR file

 

jar t[vf] [jarfile] file ... [-Joption ...] [@arg-file ...]

 

Add Index to JAR file

 

jar i jarfile [-Joption ...] [@arg-file ...]

 

 DESCRIPTION 
The \f3jar command is a general-purpose archiving and compression tool, based on ZIP and the ZLIB compression format. However, the \f3jar command was designed mainly to package Java applets or applications into a single archive. When the components of an applet or 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 \f3jar command also compresses files, which further improves download time. The \f3jar command also allows individual entries in a file to be signed by the applet author so that their origin can be authenticated. A JAR file can be used as a class path entry, whether or not it is compressed.


The syntax for the \f3jar command resembles the syntax for the \f3tar command. It has several operation modes, defined by one of the mandatory operation arguments. Other arguments are either options that modify the behavior of the operation, or operands required to perform the operation.

 OPERATION ARGUMENTS 
When using the \f3jar command, you have to select an operation to be performed by specifying one of the following operation arguments. You can mix them up with other one-letter options on the command line, but usually the operation argument is the first argument specified.

 
c
Create a new JAR archive.

 
i
Generate index information for a JAR archive.

 
t
List the contents of a JAR archive.

 
u
Update a JAR archive.

 
x
Extract files from a JAR archive.

 OPTIONS 
Use the following options to customize how the JAR file is created, updated, extracted, or viewed:

 
e
Sets the class specified by the entrypoint operand to be the entry point\f3 for a standalone Java application bundled into an executable JAR file. The use of this option creates or overrides the \f3Main-Class attribute value in the manifest file. The \f3e option can be used when creating (\f3c) or updating (\f3u) the JAR file.

For example, the following command creates the \f3Main.jar archive with the \f3Main.class file where the \f3Main-Class attribute value in the manifest is set to \f3Main:

 
\f3jar cfe Main.jar Main Main.class

 

 
\f3

 


The Java Runtime Environment (JRE) can directly call this application by running the following command:

 
\f3java -jar Main.jar

 

 
\f3

 


If the entry point class name is in a package, then it could use either the dot (.) or slash (/) as the delimiter. For example, if \f3Main.class is in a package called \f3mydir, then the entry point can be specified in one of the following ways:

 
\f3jar -cfe Main.jar mydir/Main mydir/Main.class

 

 
\f3jar -cfe Main.jar mydir.Main mydir/Main.class

 

 
\f3

 


Note

Specifying both \f3m and \f3e options together when a particular manifest also contains the \f3Main-Class attribute results in an ambiguous \f3Main-Class specification. The ambiguity leads to an error and the \f3jar command creation or update operation is terminated.

 
f
Sets the file specified by the jarfile operand to be the name of the JAR file that is created (\f3c), updated (\f3u), extracted (\f3x) from, or viewed (\f3t). Omitting the \f3f option and the jarfile operand instructs the \f3jar command to accept the JAR file name from \f3stdin (for \f3x and \f3t) or send the JAR \f3file to \f3stdout (for \f3c and \f3u).

 
m
Includes names and values of attributes from the file specified by the \f3manifest operand in the manifest file of the \f3jar command (located in the archive at \f3META-INF/MANIFEST.MF). The \f3jar command adds the attribute\(cqs name and value to the JAR file unless an entry already exists with the same name, in which case the \f3jar command updates the value of the attribute. The \f3m option can be used when creating (\f3c) or updating (\f3u) the JAR file.

You can add special-purpose name-value attribute pairs to the manifest that are not contained in the default manifest file. For example, you can add attributes that specify vendor information, release information, package sealing, or to make JAR-bundled applications executable. For examples of using the \f3m option, see Packaging Programs at http://docs.oracle.com/javase/tutorial/deployment/jar/index.html

 
M
Does not create a manifest file entry (for \f3c and \f3u), or delete a manifest file entry when one exists (for \f3u). The \f3M option can be used when creating (\f3c) or updating (\f3u) the JAR file.

 
n
When creating (\f3c) a JAR file, this option normalizes the archive so that the content is not affected by the packing and unpacking operations of the pack200(1) command. Without this normalization, the signature of a signed JAR can become invalid.

 
v
Generates verbose output to standard output. See Examples.

 
0
(Zero) Creates (\f3c) or updates (\f3u) the JAR file without using ZIP compression.


-C dir


When creating (\f3c) or updating (\f3u) a JAR file, this option temporarily changes the directory while processing files specified by the file operands. Its operation is intended to be similar to the \f3-C option of the UNIX \f3tar utility.For example, the following command changes to the \f3classes directory and adds the \f3Bar.class file from that directory to \f3my.jar:

 
\f3jar uf my.jar -C classes Bar.class

 

 
\f3

 


The following command changes to the \f3classes directory and adds to \f3my.jar all files within the classes directory (without creating a \f3classes directory in the JAR file), then changes back to the original directory before changing to the \f3bin directory to add \f3Xyz.class to \f3my.jar.

 
\f3jar uf my.jar -C classes . -C bin Xyz.class

 

 
\f3

 


If \f3classes contained files \f3bar1 and \f3bar2, then the JAR file will contain the following after running the previous command:

 
\f3% jar tf my.jar

 

 
\f3META-INF/

 

 
\f3META-INF/MANIFEST.MF

 

 
\f3bar1

 

 
\f3bar2

 

 
\f3Xyz.class

 

 
\f3

 


 
-Joption
Sets the specified JVM option to be used when the JRE runs the JAR file. JVM options are described on the reference page for the java(1) command. For example, \f3-J-Xms48m sets the startup memory to 48 MB.

 OPERANDS 
The following operands are recognized by the \f3jar command.

 
file
When creating (\f3c) or updating (\f3u) a JAR file, the file operand defines the path and name of the file or directory that should be added to the archive. When extracting (\f3x) or listing the contents (\f3t) of a JAR file, the file operand defines the path and name of the file to be extrated or listed. At least one valid file or directory must be specified. Separate multiple file operands with spaces. If the entrypoint, jarfile, or manifest operands are used, the file operands must be specified after them.

 
entrypoint
When creating (\f3c) or updating (\f3u) a JAR file, the entrypoint operand defines the name of the class that should be the entry point\f3 for a standalone Java application bundled into an executable JAR file. The entrypoint operand must be specified if the \f3e option is present.

 
jarfile
Defines the name of the file to be created (\f3c), updated (\f3u), extracted (\f3x), or viewed (\f3t). The jarfile operand must be specified if the \f3f option is present. Omitting the \f3f option and the jarfile operand instructs the \f3jar command to accept the JAR file name from \f3stdin (for \f3x and \f3t) or send the JAR \f3file to \f3stdout (for \f3c and \f3u).

When indexing (\f3i) a JAR file, specify the jarfile operand without the \f3f option.

 
manifest
When creating (\f3c) or updating (\f3u) a JAR file, the manifest operand defines the preexisting manifest files with names and values of attributes to be included in \f3MANIFEST.MF in the JAR file. The manifest operand must be specified if the \f3f option is present.

 
@arg-file
To shorten or simplify the \f3jar command, you can specify arguments in a separate text file and pass it to the \f3jar command with the at sign (@) as a prefix. When the \f3jar command encounters an argument beginning with the at sign, it expands the contents of that file into the argument list.

An argument file can include options and arguments of the \f3jar command (except the \f3-J options, because they are passed to the launcher, which does not support argument files). The arguments within a file can be separated by spaces or newline characters. File names within an argument file are relative to the current directory from which you run the \f3jar command, not relative to the location of the argument file. Wild cards, such as the asterisk (*), that might otherwise be expanded by the operating system shell, are not expanded.

The following example, shows how to create a \f3classes.list file with names of files from the current directory output by the \f3find command:

 
\f3find . -name '*.class' -print > classes.list

 

 
\f3

 


You can then execute the \f3jar command and pass the \f3classes.list file to it using the @arg-file syntax:

 
\f3jar cf my.jar @classes.list

 

 
\f3

 


An argument file can be specified with a path, but any file names inside the argument file that have relative paths are relative to the current working directory of the \f3jar command, not to the path passed in, for example:

 
\f3jar @dir/classes.list

 

 
\f3

 


 NOTES 
The \f3e, \f3f, and \f3m options must appear in the same order on the command line as the entrypoint, jarfile, and manifest operands, for example:

 
\f3jar cmef myManifestFile MyMainClass myFile.jar *.class

 

 
\f3

 

 EXAMPLES 
\f3Example 1 Adding All Files From the Current Directory With Verbose Output

 
\f3% ls

 

 
\f31.au Animator.class monkey.jpg

 

 
\f32.au Wave.class spacemusic.au

 

 
\f33.au at_work.gif

 

 
\f3

 

 
\f3% jar cvf bundle.jar *

 

 
\f3added manifest

 

 
\f3adding: 1.au(in = 2324) (out= 67)(deflated 97%)

 

 
\f3adding: 2.au(in = 6970) (out= 90)(deflated 98%)

 

 
\f3adding: 3.au(in = 11616) (out= 108)(deflated 99%)

 

 
\f3adding: Animator.class(in = 2266) (out= 66)(deflated 97%)

 

 
\f3adding: Wave.class(in = 3778) (out= 81)(deflated 97%)

 

 
\f3adding: at_work.gif(in = 6621) (out= 89)(deflated 98%)

 

 
\f3adding: monkey.jpg(in = 7667) (out= 91)(deflated 98%)

 

 
\f3adding: spacemusic.au(in = 3079) (out= 73)(deflated 97%)

 

 
\f3

 
\f3Example 2 Adding Files From Subdirectories

 
\f3% ls -F

 

 
\f3audio/ classes/ images/

 

 
\f3% jar cvf bundle.jar audio classes images

 

 
\f3added manifest

 

 
\f3adding: audio/(in = 0) (out= 0)(stored 0%)

 

 
\f3adding: audio/1.au(in = 2324) (out= 67)(deflated 97%)

 

 
\f3adding: audio/2.au(in = 6970) (out= 90)(deflated 98%)

 

 
\f3adding: audio/3.au(in = 11616) (out= 108)(deflated 99%)

 

 
\f3adding: audio/spacemusic.au(in = 3079) (out= 73)(deflated 97%)

 

 
\f3adding: classes/(in = 0) (out= 0)(stored 0%)

 

 
\f3adding: classes/Animator.class(in = 2266) (out= 66)(deflated 97%)

 

 
\f3adding: classes/Wave.class(in = 3778) (out= 81)(deflated 97%)

 

 
\f3adding: images/(in = 0) (out= 0)(stored 0%)

 

 
\f3adding: images/monkey.jpg(in = 7667) (out= 91)(deflated 98%)

 

 
\f3adding: images/at_work.gif(in = 6621) (out= 89)(deflated 98%)

 

 
\f3

 

 
\f3% ls -F

 

 
\f3audio/ bundle.jar classes/ images/

 

 
\f3

 
\f3Example 3 Listing the Contents of JAR

 
\f3% jar tf bundle.jar

 

 
\f3META-INF/

 

 
\f3META-INF/MANIFEST.MF

 

 
\f3audio/1.au

 

 
\f3audio/2.au

 

 
\f3audio/3.au

 

 
\f3audio/spacemusic.au

 

 
\f3classes/Animator.class

 

 
\f3classes/Wave.class

 

 
\f3images/monkey.jpg

 

 
\f3images/at_work.gif

 

 
\f3

 
\f3Example 4 Adding an Index


Use the \f3i option when you split the interdependent classes for a stock trade application into three JAR files: \f3main.jar, \f3buy.jar, and \f3sell.jar. If you specify the \f3Class-Path attribute in the \f3main.jar manifest, then you can use the \f3i option to speed up the class loading time for your application:

 
\f3Class-Path: buy.jar sell.jar

 

 
\f3jar i main.jar

 

 
\f3

 
An \f3INDEX.LIST file is inserted to the \f3META-INF directory. This enables the application class loader to download the specified JAR files when it is searching for classes or resources.


The application class loader uses the information stored in this file for efficient class loading. To copy directories, first compress files in \f3dir1 to \f3stdout, then pipeline and extract from \f3stdin to \f3dir2 (omitting the \f3-f option from both \f3jar commands):

 
\f3(cd dir1; jar c .) | (cd dir2; jar x)

 

 
\f3

 

 SEE ALSO 
 0.2i 
pack200(1).

 0.2i 
The JAR section of The Java Tutorials at http://docs.oracle.com/javase/tutorial/deployment/jar/index.html




'pl 8.5i
'bp