Mac Developer Library Developer
Search

 

This manual page is part of Xcode Tools version 5.0

To obtain these tools:

If you are running a version of Xcode Tools other than 5.0, view the documentation locally:

  • In Xcode

  • In Terminal, using the man(1) command

Reading manual pages

Manual pages are intended as a quick reference for people who already understand a technology.

  • To learn how the manual is organized or to learn about command syntax, read the manual page for manpages(5).

  • For more information about this technology, look for other documentation in the Apple Developer Library.

  • For general information about writing shell scripts, read Shell Scripting Primer.



jar(1)                                                                                                jar(1)



NAME
       jar - Java archive tool

SYNOPSIS
       Create jar file
       jar c[v0M]f jarfile [ -C dir ] inputfiles [ -Joption ]
       jar c[v0]mf manifest jarfile [ -C dir ] inputfiles [ -Joption ]
       jar c[v0M] [ -C dir ] inputfiles [ -Joption ]
       jar c[v0]m manifest [ -C dir ] inputfiles [ -Joption ]

       Update jar file
       jar u[v0M]f jarfile [ -C dir ] inputfiles [ -Joption ]
       jar u[v0]mf manifest jarfile [ -C dir ] inputfiles [ -Joption ]
       jar u[v0M] [ -C dir ] inputfiles [ -Joption ]
       jar u[v0]m manifest [ -C dir ] inputfiles [ -Joption ]

       Extract jar file
       jar x[v]f jarfile [ inputfiles ] [ -Joption ]
       jar x[v] [ inputfiles ] [ -Joption ]

       List table of contents of jar file
       jar t[v]f jarfile [ inputfiles ] [ -Joption ]
       jar t[v] [ inputfiles ] [ -Joption ]

       Add index to jar file
       jar i jarfile [ -Joption ]

PARAMETERS
       cuxtivOMmf     Options that control the jar command.

       jarfile        Jar  file to be created (c), updated (u), extracted (x), or have its table of contents
                      viewed (t). The f option and filename jarfile are a pair -- if either is present, they
                      must  both appear. Note that omitting f and jarfile accepts a "jar file" from standard
                      input (for x and t) or sends the "jar file" to standard output (for c and u).

       inputfiles     Files or directories, separated by spaces, to be combined into jarfile (for c and  u),
                      or  to  be  extracted (for x) or listed (for t) from jarfile. All directories are pro-cessed processed
                      cessed recursively. The files are compressed unless option O (zero) is used.

       manifest       Pre-existing manifest file whose name: value pairs are to be included  in  MANIFEST.MF
                      in  the  jar  file.   The  m  option  and filename manifest are a pair -- if either is
                      present, they must both appear. The letters m and f must appear in the same order that
                      manifest and jarfile appear.

       -C dir         Temporarily changes directories to dir while processing the following inputfiles argu-ment. argument.
                      ment.  Multiple -C dir inputfiles sets are allowed.

       -Joption       Option to be passed into the Java runtime environment. (There must be no space between
                      -J and option).

DESCRIPTION
       The  jar  tool  combines multiple files into a single JAR archive file.  jar is a general-purpose ar-chiving archiving
       chiving and compression tool, based on ZIP  and  the  ZLIB  compression  format.   However,  jar  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 HTTP transaction,
       rather than require a new connection for each piece.  This dramatically improves download time.   The
       jar  tool  also compresses files, which further improves download time.  In addition, it allows indi-vidual individual
       vidual entries in a file to be signed by the applet author so that their  origins  can  be  authenti-cated. authenticated.
       cated.   The syntax for the jar tool is almost identical to the syntax for the tar(1) command.  A jar
       archive can be used as a class path entry, whether or not it is compressed.

       Typical usage to combine files into a jar file is:

              % jar cf myFile.jar *.class

       In this example, all the class files in the current directory are placed in the file named myjarfile.
       A  manifest  file  entry named META-INF/MANIFEST.MF is automatically generated by the jar tool and is
       always the first entry in the jar file.  The manifest file is the place  where  any  meta-information
       about  the  archive  is  stored as name:value pairs.  Refer to the Jar File specification for details
       about how meta-information is stored in the manifest file.

       If you have a pre-existing manifest file whose name: value pairs you want the jar tool to include for
       the new jar archive, you can specify it using the m option:

            % jar cmf myManifestFile myJarFile *.class

       Be  sure  that  any  pre-existing manifest file that you use ends with a new line. The last line of a
       manifest file will not be parsed if it doesn't end with a new line  character.  Note  that  when  you
       specify  "cfm"  instead of "cmf" (i.e., you invert the order of the "m" and "f" options), you need to
       specify the name of the jar archive first, followed by the name of the manifest file:

            % jar cfm myJarFile myManifestFile *.class

       The manifest is in a text format inspired by RFC822 ASCII format, so it is easy to view  and  process
       manifest-file contents.

       To extract the files from a jar file, use x , as in:

            % jar xf myFile.jar

       To extract only certain files from a jar file, supply their filenames:

            % jar xf myFile.jar foo bar

       Beginning  with version 1.3 of the Java 2 SDK, the jar utility supports JarIndex, which allows appli-cation application
       cation class loaders to load classes more efficiently from jar files. If an application or applet  is
       bundled  into multiple jar files,  only the necessary jar files will be downloaded and opened to load
       classes. This performance optimization is enabled by running jar with the i option. It will  generate
       package  location  information  for  the specified main jar file and all the jar files it depends on,
       which need to be specified in the Class-Path attribute of the main jar file's manifest.

            % jar i main.jar

       In this example, an INDEX.LIST file is inserted into the META-INF directory of main.jar.  The  appli-cation application
       cation  class loader will use the information stored in this file for efficient class loading.  Refer
       to the JarIndex specification for details about how location information is stored in the index file.

       A  standard  way to copy directories is to first compress files in dir1 to standard out, then extract
       from standard in to dir2 (omitting f from both jar commands):

            % (cd dir1; jar c .) | (cd dir2; jar x)

       Examples of using the jar tool to operate on jar files and jar file manifests are provided below  and
       in the Jar trail of the Java Tutorial.

OPTIONS
       c    Creates  a  new  archive  file named jarfile (if f is specified) or to standard output (if f and
            jarfile are omitted). Add to it the files and directories specified by inputfiles.

       u    Updates an existing file jarfile (when f is specified) by adding to  it  files  and  directories
            specified by inputfiles. For example:

            jar uf foo.jar foo.class

       would add the file foo.class to the existing jar file foo.jar. The u option can also update the mani-fest manifest
       fest entry, as given by this example:

            jar umf manifest foo.jar

       updates the foo.jar manifest with the name: value pairs in manifest.

       x    Extracts files and directories from jarfile (if f is specified) or  standard  input  (if  f  and
            jarfile are omitted). If inputfiles is specified, only those specified files and directories are
            extracted. Otherwise, all files and directories are extracted.

       t    Lists the table of contents from jarfile (if f is specified) or standard input (if f and jarfile
            are omitted). If inputfiles is specified, only those specified files and directories are listed.
            Otherwise, all files and directories are listed.

       i    Generate index information for the specified jarfile and its dependent jar files. For example:

            jar i foo.jar

       would generate an INDEX.LIST file in foo.jar which contains location information for each package  in
       foo.jar  and all the jar files specified in the Class-Path attribute of foo.jar.  See the index exam-ple. example.
       ple.

       f    Specifies the file jarfile to be created (c), updated (u), extracted (x), indexed (i), or viewed
            (t).  The  f option and filename jarfile are a pair -- if present, they must both appear.  Omit-ting Omitting
            ting f and jarfile accepts a "jar file" from standard input (for x and  t)  or  sends  the  "jar
            file" to standard output (for c and u).

       v    Generates verbose output to standard output. Examples shown below.

       0    Zero. Store without using ZIP compression.

       M    Do not create a manifest file entry (for c and u), or delete a manifest file entry if one exists
            (for u).

       m    Includes name: value attribute pairs from the specified manifest file manifest in  the  file  at
            META-INF/MANIFEST.MF.  A name: value pair is added unless one already exists with the same name,
            in which case its value is updated.

       On the command line, the letters m and f must appear in the same  order  that  manifest  and  jarfile
       appear. Example use:

            jar cmf myManifestFile myFile.jar *.class

       You  can add special-purpose name: value attribute pairs to the manifest that aren't contained in the
       default manifest. Examples of such attributes would be those for vendor information, version informa-tion, information,
       tion,  package  sealing,  and to make JAR-bundled applications executable. See the JAR Files trail in
       the Java Tutorial and the Notes for Developers page for examples of using the m option.

       -C   Temporarily changes directories (cd dir) during execution of the jar  command  while  processing
            the  following  inputfiles argument. Its operation is intended to be similar to the -C option of
            the UNIX tar utility.  For example:

               % jar uf foo.jar -C classes bar.classes

       would change to the classes directory and add the bar.class from that directory to foo.jar. The  fol-lowing following
       lowing command,

               jar uf foo.jar -C classes . -C bin xyz.class

       would  change  to  the  classes  directory  and add to foo.jar all files within the classes directory
       (without creating a classes directory in the jar file), then change back to  the  original  directory
       before  changing  to  the  bin directory to add xyz.class to foo.jar. If classes holds files bar1 and
       bar2, then here's what the jar file would contain using jar tf foo.jar:

               META-INF/
               META-INF/MANIFEST.MF
               bar1
               bar2
               xyz.class

       Joption
            Pass option to the Java runtime environment, where option is one of the options described on the
            man  page  for  the java application launcher, java(1).  For example, -J-Xms48m sets the startup
            memory to 48 megabytes. It is a common convention for -J to pass options to the underlying  vir-tual virtual
            tual machine.

COMMAND LINE ARGUMENT FILES
       To  shorten  or simplify the jar command line, you can specify one or more files that themselves con-tain contain
       tain arguments to the jar command (except -J options).  This enables you to create  jar  commands  of
       any length, overcoming command line limits imposed by the operating system.

       An  argument  file  can include options and filenames. The arguments within a file can be space-sepa-rated space-separated
       rated or newline-separated. Filenames within an argument file are relative to the current  directory,
       not  the location of the argument file. Wildcards (*) that might otherwise be expanded by the operat-ing operating
       ing system shell are not expanded. Use of the '@' character to recursively  interpret  files  is  not
       supported.  The  -J options are not supported because they are passed to the launcher, which does not
       support argument files.

       When executing jar, pass in the path and name of each argument file with the '@'  leading  character.
       When  jar  encounters  an  argument beginning with the character `@', it expands the contents of that
       file into the argument list.

       For example, you could use a single argument file named "classes.list"  to  hold  the  names  of  the
       files:

            % find . -name '*.class' -print > classes.list

       Then execute the jar command passing in the argfile:

            % jar cf my.jar @classes.list

       An  argument  file can be passed in with a path, but any filenames inside the argument file that have
       relative paths are relative to the current working directory, not the path passed in. Here's such  an
       example:

            % jar @path1/classes.list

EXAMPLES
       To  add  all  the  files in a particular directory to an archive (overwriting contents if the archive
       already exists). Enumerating verbosely (with the "v" option) will tell you more information about the
       files in the archive, such as their size and last modified date.

              % ls
              1.au          Animator.class    monkey.jpg
              2.au          Wave.class        spacemusic.au
              3.au          at_work.gif
              % jar cvf bundle.jar *
              added manifest
              adding: 1.au(in = 2324) (out= 67)(deflated 97%)
              adding: 2.au(in = 6970) (out= 90)(deflated 98%)
              adding: 3.au(in = 11616) (out= 108)(deflated 99%)
              adding: Animator.class(in = 2266) (out= 66)(deflated 97%)
              adding: Wave.class(in = 3778) (out= 81)(deflated 97%)
              adding: at_work.gif(in = 6621) (out= 89)(deflated 98%)
              adding: monkey.jpg(in = 7667) (out= 91)(deflated 98%)
              adding: spacemusic.au(in = 3079) (out= 73)(deflated 97%)
       If you already have separate subdirectories for images, audio files and classes, you can combine them
       into a single jar file:

              % ls -F
              audio/ classes/ images/

              % jar cvf bundle.jar audio classes images
              added manifest
              adding: audio/(in = 0) (out= 0)(stored 0%)
              adding: audio/1.au(in = 2324) (out= 67)(deflated 97%)
              adding: audio/2.au(in = 6970) (out= 90)(deflated 98%)
              adding: audio/3.au(in = 11616) (out= 108)(deflated 99%)
              adding: audio/spacemusic.au(in = 3079) (out= 73)(deflated 97%)
              adding: classes/(in = 0) (out= 0)(stored 0%)
              adding: classes/Animator.class(in = 2266) (out= 66)(deflated 97%)
              adding: classes/Wave.class(in = 3778) (out= 81)(deflated 97%)
              adding: images/(in = 0) (out= 0)(stored 0%)
              adding: images/monkey.jpg(in = 7667) (out= 91)(deflated 98%)
              adding: images/at_work.gif(in = 6621) (out= 89)(deflated 98%)

              % ls -F
              audio/ bundle.jar classes/ images/

       To see the entry names in the jarfile, use the t option:

              % jar tf bundle.jar
              META-INF/
              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

       To add an index file to the jar file for speeding up class loading, use the "i" option.

       Let's say you split the inter-dependent classes for a stock trade application, into three jar  files:
       main.jar,  buy.jar,  and  sell.jar.  If you specify the Class-path attribute in the main.jar manifest
       as:

            Class-Path: buy.jar sell.jar

       then you can use the i option to speed up your application's class loading time:

            % jar i main.jar

       An INDEX.LIST file is inserted to the META-INF directory which  will  enable  the  application  class
       loader to download the specified jar files when it is searching for classes or resources.

SEE ALSO
       The JAR Overview @
         http://java.sun.com/javase/6/docs/technotes/guides/jar/jarGuide.html


       The JAR File Specification @
         http://java.sun.com/javase/6/docs/technotes/guides/jar/jar.html


       The JARIndex Spec @
         http://java.sun.com/javase/6/docs/technotes/guides/jar/jar.html


       JAR Tutorial @
         http://java.sun.com/docs/books/tutorial/jar/


       pack2__ Reference Page @
         http://java.sun.com/javase/6/docs/technotes/tools/share/pack200.html




                                                 22 Jun 2004                                          jar(1)

Reporting Problems

The way to report a problem with this manual page depends on the type of problem:

Content errors
Report errors in the content of this documentation with the feedback links below.
Bug reports
Report bugs in the functionality of the described tool or API through Bug Reporter.
Formatting problems
Report formatting mistakes in the online version of these pages with the feedback links below.

Feedback