<!DOCTYPE REFENTRY PUBLIC "-//Sun Microsystems//DTD DocBook V3.0-Based SolBook Subset V2.0//EN" [
<!--ArborText, Inc., 1988-1999, v.4002-->
<!ENTITY % javaents SYSTEM "javaman.ent">
%javaents;
]>
<?Pub UDT _bookmark _target>
<?Pub Inc>
<refentry id="jar-1">
<!--@(#)jar.1 1.19 01/03/14 SMI;-->
<refmeta><refentrytitle>jar</refentrytitle><manvolnum>1</manvolnum>
<refmiscinfo class="date">23 Apr 2001</refmiscinfo>
<refmiscinfo class="sectdesc">&man1;</refmiscinfo>
<refmiscinfo class="software">&java-release;</refmiscinfo>
<refmiscinfo class="arch">generic</refmiscinfo>
<refmiscinfo class="copyright"> Copyright 2001 Sun Microsystems, Inc. All
rights reserved.  Copyright 2001 Sun Microsystems, Inc. Tous droits r&eacute;serv&eacute;s.
</refmiscinfo>
</refmeta>
<refnamediv><refname>jar</refname><refpurpose>Java archive tool</refpurpose>
</refnamediv>
<refsynopsisdiv><title>&synp-tt;</title>
<cmdsynopsis><command>jar</command><arg choice="opt"><option>C</option></arg>
<arg choice="opt">c</arg><arg choice="opt">f</arg><arg choice="opt">i</arg>
<arg choice="opt">J</arg><arg choice="opt">M</arg><arg choice="opt">m</arg>
<arg choice="opt">0</arg><arg choice="opt">t</arg><arg choice="opt">u</arg>
<arg choice="opt">v</arg><arg choice="opt"><arg choice="plain">x</arg><arg
choice="plain"><replaceable>file</replaceable></arg></arg><arg choice="opt"><replaceable>
manifest-file</replaceable></arg><arg choice="plain"><replaceable>destination
</replaceable></arg><arg choice="plain"><replaceable>input-file</replaceable></arg>
<arg choice="opt"><replaceable>input-files</replaceable></arg>
</cmdsynopsis></refsynopsisdiv>
<refsect1><title>&desc-tt;</title>
<indexterm id="jar-1-indx-1"><primary sortas="Java archive tool">Java archive
tool &mdash; jar</primary></indexterm><indexterm id="jar-1-indx-2"><primary
sortas="jar">jar &mdash; Java archive tool</primary></indexterm><para>The <command>
jar</command> tool is a Java&trade; application that combines multiple files
into a single <acronym>JAR</acronym> archive file. It is also a general-purpose
archiving and compression tool, based on <acronym remap="small">ZIP</acronym>
and the <acronym remap="small">ZLIB</acronym> compression format. However, <command>
jar</command> was designed mainly to facilitate the packaging of Java applets
or applications into a single archive. When the components of an applet or
application (.class files, images and sounds) are combined into a single archive,
they can be downloaded by a Java agent (like a browser) in a single <acronym
remap="small">HTTP</acronym> transaction, rather than require a new connection
for each piece. This dramatically improves download time. The <command>jar
</command> tool also compresses files, which further improves download time.
In addition, it allows individual entries in a file to be signed by the applet
author so that their origins can be authenticated. The syntax for the <command>
jar</command> tool is almost identical to the syntax for the <citerefentry>
<refentrytitle>tar</refentrytitle><manvolnum>1</manvolnum></citerefentry>
command. A <acronym>JAR</acronym> archive can be used as a class path entry,
whether or not it is compressed.</para>
<para>The three types of input files for the <command>jar</command> tool are:
</para>
<itemizedlist>
<listitem><para>Manifest file (optional)</para></listitem>
<listitem><para>Destination <acronym>JAR</acronym> file</para></listitem>
<listitem><para>Files to be archived</para></listitem>
</itemizedlist>
<para>Typical usage is:</para>
<informalexample>
<screen>example% <userinput>jar cf myjarfile *.class</userinput> </screen>
</informalexample>
<para>In this example, all the class files in the current directory are placed
in the file named <literal>myjarfile</literal>. A manifest file is automatically
generated by the <command>jar</command> tool and is always the first entry
in the <acronym>JAR</acronym> file. By default, it is named <literal remap="small and bold">
META-INF/MANIFEST.MF</literal>. The manifest file is the place where any meta-information
about the archive is stored. Refer to the <citetitle>Manifest Format</citetitle>
in the &also-tt; section for details about how meta-information is stored
in the manifest file.</para>
<para>To use a pre-existing manifest file to create a new <acronym>JAR</acronym>
archive, specify the old manifest file with the <option role="nodash">m</option>
option:</para>
<informalexample>
<screen>example% <userinput>jar cmf myManifestFile myJarFile *.class</userinput></screen>
</informalexample>
<para>When you specify <option role="nodash">cfm</option> instead of  <option
role="nodash">cmf</option> (that is, you invert the order of the  <option
role="nodash">m</option> and <option role="nodash">f</option> options), you
need to specify the name of the <acronym>JAR</acronym> archive first, followed
by the name of the manifest file:</para>
<informalexample>
<screen>example% <userinput>jar cfm myJarFile myManifestFile *.class</userinput></screen>
</informalexample>
<para>The manifest uses RFC822 <acronym remap="small">ASCII</acronym> format,
so it is easy to view and process manifest-file contents.</para>
</refsect1>
<refsect1><title>&opts-tt;</title>
<para>The following options are supported:</para>
<variablelist termlength="xtranarrow">
<varlistentry><term><option>C</option></term><listitem><para>Changes directories
during execution of the <command>jar</command> command. For example:<informalexample>
<screen>example% <userinput>jar uf foo.jar &ndash;C classes *</userinput></screen>
</informalexample></para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">c</option></term><listitem><para>
Creates a new or empty archive on the standard output.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">f</option></term><listitem><para>
The second argument specifies a <acronym>JAR</acronym> file to process. In
the case of creation, this refers to the name of the <acronym>JAR</acronym>
file to be created (instead of on <literal>stdout</literal>). For table or
xtract, the second argument identifies the <acronym>JAR</acronym> file to
be listed or extracted.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">i</option></term><listitem><para>
Generates index information for the specified <acronym>JAR</acronym> file
and its dependent <acronym>JAR</acronym> files. For example:<informalexample>
<screen>example% <userinput>jar i foo.jar</userinput><?Pub Caret></screen>
</informalexample>would generate an <literal remap="small and bold">INDEX.LIST
</literal> file in <literal>foo.jar</literal> which contains location information
for each package in <literal>foo.jar</literal> and all the <acronym>JAR</acronym>
files specified in <literal>foo.jar</literal>'s Class-Path attribute.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">J</option><replaceable>option</replaceable></term>
<listitem><para>Pass <replaceable>option</replaceable> to the Java virtual
machine, where option is one of the options described on the man page for
the java application launcher, java (1). For example, <literal>-J-Xms48m</literal>
sets the startup memory to 48 megabytes. It is a common convention for <literal>
-J</literal> to pass options to the underlying virtual machine.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">M</option></term><listitem><para>
Does not create a manifest file for the entries.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">m</option></term><listitem><para>
Includes manifest information from specified pre-existing manifest file. Example
use:<informalexample>
<screen>example% <userinput>jar cmf myManifestFile myJarFile *.class</userinput></screen>
</informalexample>You can add special-purpose name-value attribute headers
to the manifest file that are not contained in the default manifest. Examples
of such headers are those for vendor information, version information, package
sealing, and headers to make <acronym>JAR</acronym>-bundled applications executable.
See the <citetitle>JAR Files</citetitle> trail in the <citetitle>Java Tutorial
</citetitle> and the <citetitle>JRE Notes for Developers</citetitle> web page
for examples of using the <option role="nodash">m</option> option.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">0</option></term><listitem><para>
Stores only, without using <acronym remap="small">ZIP</acronym> compression.
</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">t</option></term><listitem><para>
Lists the table of contents from standard output.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">u</option></term><listitem><para>
Updates an existing <acronym>JAR</acronym> file by adding files or changing
the manifest. For example:<informalexample>
<screen>example% <userinput>jar uf foo.jar foo.class</userinput></screen>
</informalexample>adds the file  <literal>foo.class</literal> to the existing <acronym>
JAR</acronym> file <literal>foo.jar</literal>, and<informalexample>
<screen>example% <userinput>jar umf foo.jar</userinput> </screen>
</informalexample>updates <literal>foo.jar</literal>'s manifest with the information
in manifest.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">v</option></term><listitem><para>
Generates verbose output on <literal>stderr</literal>.</para>
</listitem></varlistentry>
<varlistentry><term><option role="nodash">x</option> <replaceable>file</replaceable></term>
<listitem><para>Extracts all files, or just the named files, from standard
input. If <replaceable>file</replaceable> is omitted, then all files are extracted;
otherwise, only the specified file or files are extracted. If any of the <replaceable>
file</replaceable>s is a directory, then that directory is processed recursively.
</para>
</listitem></varlistentry>
</variablelist></refsect1>
<refsect1><title>&exam-tt;</title>
<example role="example">
<title>Adding all of the files in a particular directory to an archive</title>
<para><screen>example% <userinput>ls</userinput>
<computeroutput>0.au         3.au         6.au          9.au            at_work.gif
1.au         4.au         7.au          Animator.class  monkey.jpg
e.au         5.au         8.au          Wave.class      spacemusic.au
example% jar cvf bundle.jar *
adding: 0.au
adding: 1.au
adding: 2.au
adding: 3.au
adding: 4.au
adding: 5.au
adding: 6.au
adding: 7.au
adding: 8.au
adding: 9.au
adding: Animator.class
adding: Wave.class
adding: at_work.gif
adding: monkey.jpg
adding: spacemusic.au
example%</computeroutput>

</screen></para>
</example>
<example role="example">
<title>Archiving subdirectories</title>
<para>If you already have subdirectories for images, audio files, and classes
that already exist in an HTML directory, use <command>jar</command> to archive
each directory to a single <acronym>JAR</acronym> file:</para>
<para><screen>example% <userinput>ls</userinput>
<computeroutput>audio classes images</computeroutput>
example% <userinput>jar cvf bundle.jar audio classes images</userinput>
<computeroutput>adding: audio/1.au
adding: audio/2.au
adding: audio/3.au
adding: audio/spacemusic.au
adding: classes/Animator.class
adding: classes/Wave.class
adding: images/monkey.jpg
adding: images/at_work.gif
example% ls &ndash;l
total 142
drwxr-xr-x   2 brown    green        512 Aug  1 22:33 audio
-rw-r--r--   1 brown    green      68677 Aug  1 22:36 bundle.jar
drwxr-xr-x   2 brown    green        512 Aug  1 22:26 classes
drwxr-xr-x   2 brown    green        512 Aug  1 22:25 images</computeroutput>
example% </screen></para>
</example>
<example role="example">
<title>Finding entry names in the JAR file</title>
<para>To see the entry names in the <acronym>JAR</acronym> file using the <command>
jar</command> tool and the <option role="nodash">t</option> option:</para>
<para><screen>example% <userinput>ls</userinput>
<computeroutput>audio bundle.jar classes images</computeroutput>
example% <userinput>jar tf bundle.jar</userinput>
<computeroutput>META-INF/MANIFEST.MF
audio/1.au
audio/2.au
audio/3.au
audio/spacemusic.au
classes/Animator.class
classes/Wave.class
images/monkey.jpg
images/at_work.gif</computeroutput>
example% </screen></para>
</example>
<example role="example">
<title>Displaying more information about files in the archive</title>
<para>To display more information about the files in the archive, such as
their size and last modified date, use the <option role="nodash">v</option>
option:</para>
<para><screen>example% <userinput>jar tvf bundle.jar</userinput>
<computeroutput>145 Thu Aug 01 22:27:00 PDT 1996 META-INF/MANIFEST.MF
946 Thu Aug 01 22:24:22 PDT 1996 audio/1.au
1039 Thu Aug 01 22:24:22 PDT 1996 audio/2.au
993 Thu Aug 01 22:24:22 PDT 1996 audio/3.au
48072 Thu Aug 01 22:24:23 PDT 1996 audio/spacemusic.au
16711 Thu Aug 01 22:25:50 PDT 1996 classes/Animator.class
3368 Thu Aug 01 22:26:02 PDT 1996 classes/Wave.class
12809 Thu Aug 01 22:24:48 PDT 1996 images/monkey.jpg
527 Thu Aug 01 22:25:20 PDT 1996 images/at_work.gif</computeroutput>
example% </screen></para>
</example>
<example role="example">
<title>Speeding up an application's class loading time</title>
<para>If you bundled a stock trade application (applet) into the following <acronym>
JAR</acronym> files:<informalexample>
<screen>main.jar buy.jar sell.jar other.jar</screen>
</informalexample>and you specified the <literal>Class-Path</literal> attribute
in <literal>main.jar</literal>'s manifest as<informalexample>
<screen>Class-Path: buy.jar sell.jar other.jar </screen>
</informalexample>then you can use the <option role="nodash">i</option> option
to speed up your application's class loading time:<informalexample>
<screen>example$ <userinput>jar i main.jar</userinput></screen>
</informalexample>An <literal remap="small and bold">INDEX.LIST</literal>
file is inserted in the <literal remap="small and bold">META-INF</literal>
directory which will enable the application class loader to download the right <acronym>
JAR</acronym> files when it is searching for classes or resources.</para>
</example>
</refsect1>
<refsect1><title>&attr-tt;</title>
<para>See <citerefentry><refentrytitle>attributes</refentrytitle><manvolnum>
5</manvolnum></citerefentry> for a description of the following attributes:
</para>
<informaltable frame="all" orient="port">
<tgroup cols="2" colsep="1" rowsep="1"><colspec colnum="1" colname="col1"
colwidth="1*" colsep="1" align="left"><colspec colnum="2" colname="col2" colwidth="1*"
align="left">
<thead>
<row><entry colname="col1" align="center" valign="top">ATTRIBUTE TYPE</entry>
<entry colname="col2" align="center" valign="top">ATTRIBUTE VALUE</entry>
</row>
</thead>
<tbody>
<row><entry>Availability</entry><entry>SUNWj3dev</entry></row>
</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1><title>&also-tt;</title>
<para><citerefentry><refentrytitle>keytool</refentrytitle><manvolnum>1</manvolnum>
</citerefentry>, <citerefentry><refentrytitle>attributes</refentrytitle><manvolnum>
5</manvolnum></citerefentry></para>
<variablelist termlength="wholeline">
<varlistentry><term remap="10"><citetitle>JAR Files</citetitle> @</term><listitem>
<para><ulink url="http://java.sun.com/docs/books/tutorial/jar">http://java.sun.com/docs/books/tutorial/jar
</ulink></para>
</listitem></varlistentry>
<varlistentry><term remap="10"><citetitle>JRE Notes</citetitle> @</term><listitem>
<para><ulink url="http://java.sun.com/j2se/1.4/runtime.html#example">http://java.sun.com/j2se/1.4/runtime.html#example
</ulink></para>
</listitem></varlistentry>
<varlistentry><term remap="10"><citetitle>JAR Guide</citetitle> @</term><listitem>
<para><ulink url="http://java.sun.com/j2se/1.4/docs/guide/jar/index.html">
http://java.sun.com/j2se/1.4/docs/guide/jar/index.html</ulink></para>
</listitem></varlistentry>
<varlistentry><term>For information on related topics, use the search link
@</term><listitem><para><ulink url="http://java.sun.com/">http://java.sun.com/
</ulink></para>
</listitem></varlistentry>
</variablelist></refsect1>
<!--+ 07/27/00 08:33:12
    | tagMorph:  $Id: tagMorph-engine 1.54 1998/01/19 05:44:48 $
    | tagMorph library:  $Id: libtagMorph.a 1.50 1998/01/19 22:02:51 $
    | sunman-to-solbook 1.17
    +-->
</refentry>
<?Pub *0000016358>
