<!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
-->
<html>

<head>
  <meta http-equiv="Content-Language" content="en-us">
  <link rel="stylesheet" type="text/css" href="style.css">
  <title>Archiving Task</title>
</head>

<body>

  <h2><a name="archive">Archiving Tasks</a></h2>

  <p>For each of the supported archiving formats there is a
    correspondig <code>archiving</code> task.  These tasks are
    supersets of the
    core <a href="http://ant.apache.org/manual/CoreTasks/tar.html">tar</a>
    and <a href="http://ant.apache.org/manual/CoreTasks/zip.html">zip</a>
    tasks but don't share any code with them.  Note that some
    attributes may use different defaults from the core tasks or some
    functionality may be available in different ways than with the core
    tasks - see the <a href="#tar">tar</a> and <a href="#zip">zip</a>
    documentation for details.</p>

  <p>If some of the nested resources that shall be added to the
    archive are archive resources themselves - i.e. they come from one
    of this Antlib's <a href="entry.html"><code>entry</code></a> or
    <a href="fileset.html"><code>fileset</code></a> resources or are
    core <a href="http://ant.apache.org/manual/CoreTypes/resources.html#tarentry"><code>tarentry</code></a>
    or <a href="http://ant.apache.org/manual/CoreTypes/resources.html#zipentry"><code>zipentry</code></a>
    resources or returned by a
    core <a href="http://ant.apache.org/manual/CoreTypes/tarfileset.html"><code>tarfileset</code></a>
    or <a href="http://ant.apache.org/manual/CoreTypes/zipfileset.html"><code>zipfileset</code></a>
    - the task will try to preserve the entry's permissions and as
    many other attributes of the entry as the archiving format
    supports.</p>

  <p>All archiving tasks share the following attributes and nested
    elements:</p>

  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">dest</td>
      <td valign="top">the destination resource to create.</td>
      <td align="center" valign="top" rowspan="2">Exactly one of the
        two or a nested dest element.</td>
    </tr>
    <tr>
      <td valign="top">destfile</td>
      <td valign="top">the destination file to create.</td>
    </tr>
    <tr>
      <td valign="top">encoding</td>
      <td valign="top">The character encoding to use for filenames
        inside the archive.  For a list of possible values
        see <a href="http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html">http://java.sun.com/j2se/1.5.0/docs/guide/intl/encoding.doc.html</a>.
        The magic value
        <code>native-encoding</code> can be used to explicitly select
        the platform's default character encoding.  Defaults to the
        platform's default character encoding.<br/>
        Currently ignored by all but the tar (<em>since Compress
        Antlib 1.2</em>), cpio (<em>since Compress
        Antlib 1.3</em>) and zip tasks.
      </td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">filesonly</td>
      <td valign="top">Store only file entries, defaults to true</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">preserve0permissions</td>
      <td valign="top">when updating an archive or adding entries from a
        different archive Ant will assume that a Unix permissions value of
        0 (nobody is allowed to do anything to the file/directory) means
        that the permissions haven't been stored at all rather than real
        permissions and will instead apply its own default values.<br/>
        Set this attribute to true if you really want to preserve the
        original permission field.
        Default is false.
      </td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">roundup</td>
      <td valign="top">Whether the file modification times will be
        rounded up taking the timestamp granularity of the archiving
        format into account.  ZIP archives store file modification
        times with a granularity of two seconds, the other formats use
        a single second as granularity.<br/>

        Times will either be rounded up or down.  If you round down,
        the archive will always seem out-of-date when you rerun the
        task, so the default is to round up.  Rounding up may lead to
        a different type of problems like JSPs inside a web archive
        that seem to be slightly more recent than precompiled pages,
        rendering precompilation useless.<br/>

        Defaults to true.
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">preserveLeadingSlashes</td>
      <td valign="top">Indicates whether leading `/'s should
        be preserved in the file names. Default is <code>false</code>.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">duplicate</td>
      <td valign="top">behavior when a duplicate entry is found.
        Valid values are &quot;add&quot;, &quot;preserve&quot;, and
        &quot;fail&quot;. The default value is
        &quot;fail&quot;.  </td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">whenempty</td>
      <td valign="top">behavior when no files match.  Valid values are
        &quot;fail&quot; and &quot;skip&quot;.  Default is
        &quot;fail&quot;.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">mode</td>
      <td valign="top">One of "create", "force-create", "replace",
        "force-replace" or "update" - see below.  Default is
        "create".</td>
      <td valign="top" align="center">No</td>
    </tr>
  </table>

  <h4><a name="mode"><em>mode</em> attribute</a></h4>

  <p>There are three basic modes a task can be in:</p>

  <ul>

    <li><strong>create</strong> - creates an archive that will contain
      all resources that have been specified as nested resources.</li>

    <li><strong>replace</strong> - creates an archive that will
      contain all resources that have been specified as nested
      resources.  If the <em>dest</em> archive exists before running
      the task, any resource of the original archive that doesn't
      match a resource specified as nested resource will be
      preserved.</li>

    <li><strong>update</strong> - creates an archive that will
      contain all resources that have been specified as nested
      resources that are newer than their corresponding entries in the
      <em>dest</em> archive - or that don't exist in the <em>dest</em>
      archive.  If the <em>dest</em> archive exists before running the
      task, any resource of the original archive that doesn't match a
      resource specified as nested resource or is more recent than the
      nested resource will be preserved.</li>

  </ul>

  <p>If the <em>dest</em> archive doesn't exist before running the
    task, all modes behave the same.  If it does
    exist, <strong>create</strong> may remove existing
    entries and <strong>replace</strong> may replace entries that are
    more recent than the specified source resources.</p>

  <p>All three modes will first check whether the <em>dest</em>
    archive is "out of date".  An archive is considered out of date
    if</p>

  <ul>
    <li>it doesn't exist.</li>
    <li>it exists but for at least one source resource there is no
      matching entry in the <em>dest</em> resource.</li>
    <li>the matching entry for at least one source resource is older
      than the source resource.</li>
  </ul>

  <p>Neither of the basic modes will modifiy the <em>dest</em> archive
    if it is not "out of date".  For the <strong>create</strong>
    and <strong>replace</strong> modes there are
    variants <strong>force-create</strong>
    and <strong>force-replace</strong> that will bypass the "out of
    date" check and always replace (entries in) existing archives.</p>

  <h3>Parameters specified as nested elements</h3>

  <h4>dest</h4>

  <p>Accepts
    any <a href="http://ant.apache.org/manual/CoreTypes/resources.html">resource</a>
    or single element resource collection as nested element.</p>

  <p>The specified resource will be used as dest.</p>

  <h4>any <a href="http://ant.apache.org/manual/CoreTypes/resources.html">resource</a>
    or resource collection</h4>

  <p>This specifies the files and directories that shall be added to
    the archive.</p>

  <h3><a name="ar">Ar</a></h3>

  <p>An <a href="#archive">archiving task</a> creating archives of the
    AR format.</p>

  <p>The AR format is pretty limited, by default it can only store file names up
    to 16 characters and not store directories at all.  It is not
    possible to set the <code>filesonly</code> attribute to true for
    the <code>ar</code> task.</p>

  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">format</td>
      <td valign="top">Ar format for entries with names longer than
        16 characters.  Supported values are "ar" which doesn't
        support entries of that length and results in a build failure
        and "bsd".</td>
      <td valign="top" align="center">No, default is "ar"</td>
    </tr>
  </table>

  <h3><a name="cpio">Cpio</a></h3>

  <p>An <a href="#archive">archiving task</a> creating archives of the
    CPIO format.</p>

  <p>This task supports the following additional attributes:</p>

  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">format</td>
      <td valign="top">CPIO format for the archive to create.  One of
        "binary", "old-ascii", "new-ascii"<!-- or "crc"-->.  "odc" can be
        used as a synonym for "old-ascii".</td>
      <td valign="top" align="center">No, default is "binary"</td>
    </tr>
    <tr>
      <td valign="top">blocksize</td>
      <td valign="top">Block size for the archive.  Must be a
        positive number.</td>
      <td valign="top" align="center">No, default is 512.</td>
    </tr>
  </table>

  <h3><a name="sevenz">SevenZ</a></h3>

  <p><em>Since Compress Antlib 1.3</em></p>

  <p>An <a href="#archive">archiving task</a> creating archives of the
    7z format.  As of Commons Compress 1.8 this task only supports
    writing unencrypted archives.</p>

  <h3>Parameters</h3>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">contentCompression</td>
      <td valign="top">compression algorithm to use for entry
        contents.<br></br>
        As of Commons Compress 1.8 this can be "LZMA2",
        "BZIP2", "DEFLATE" or "COPY" where "COPY" means no compression
        at all.</td>
      <td valign="top" align="center">No, default is LZMA2.</td>
    </tr>
    <tr>
      <td valign="top">keepcompression</td>
      <td valign="top">For entries coming from existing archives (like
        nested <em>sevenzfileset</em>s or while updating the archive), keep
        the compression as it has been originally instead of using the
        <em>contentCompression</em> attribute.  Defaults to false.
        <em>since 1.5</em></td>
      <td align="center" valign="top">No</td>
    </tr>
  </table>

  <h3>Parameters specified as nested elements</h3>

  <h4>contentMethod</h4>

  <p>Specifies and configures a content method to use when creating an
  archive.  Multiple methods build a pipeline where the first method
  is used to process the original input and its output is sent ot the
  next method until the final output is written to the archive.</p>

  <p>As of Commons Compress 1.8 in addition to the compression methods
    "LZMA2", "BZIP2", "DEFLATE" or "COPY" filters can be used.  Names
    of filter methods end with "_FILTER" and must not be used as final
    method - this is neither enforced by this antlib or Commons
    Compress but 7z may fail to extract the archive.  As of Commons
    Compress 1.8 the supported filters are "BCJ_X86_FILTER",
    "BCJ_PPC_FILTER", "BCJ_IA64_FILTER", "BCJ_ARM_FILTER",
    "BCJ_ARM_THUMB_FILTER", "BCJ_SPARC_FILTER" and "DELTA_FILTER".
    The "BCJ" filters may improve compression ratio for executables
    for a given platform.</p>

  <p>Some methods support additional options, "DELTA_FILTER" even
    requires one.  The interpretation or even the type of an option
    depends on the method -
    see <a href="http://commons.apache.org/proper/commons-compress/javadocs/api-1.8/org/apache/commons/compress/archivers/sevenz/SevenZMethodConfiguration.html">Commons
    Compress' documentation</a>.  As of version 1.5 only numeric
    options are supported.</p>

  <strong>Parameters of contentMethod</strong>
  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">method</td>
      <td valign="top">method to use.</td>
      <td valign="top" align="center">Yes.</td>
    </tr>
    <tr>
      <td valign="top">option</td>
      <td valign="top">Numeric option for this method.</td>
      <td align="center" valign="top">No</td>
    </tr>
  </table>

  <h3><a name="tar">Tar</a></h3>

  <p>An <a href="#archive">archiving task</a> creating archives of the
    TAR format.</p>

  <p>This task does not support the <code>compression</code> attribute
    of
    the <a href="http://ant.apache.org/manual/CoreTasks/tar.html">core
    task</a>.  You should use a <a href="pack.html">compressing
    task</a> with a <code>tar</code> task as nested element
    instead.</p>

  <p>This task supports the following additional attributes:</p>

  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">format</td>
      <td valign="top">Tar format to use.
        See <a href="#tarformat">the section below.  Supported values
        are "ustar", "oldgnu", "gnu", "star" and "pax".</td>
      <td valign="top" align="center">No, default is "ustar"</td>
    </tr>
  </table>

  <h4><a name="tarformat"></a>Tar format</h4>

  <p>Over time the original tar format has seen various extensions and
    revisions.  The Apache Commons Compress library supports the
    original format (called "ustar") and some extensions added later,
    but not all of them.  It supports a subset of features offered by
    the POSIX 1003.1 standard (often referred to as PAX), but this
    support is not complete.</p>

  <p>The Compress Antlib follows Commons Compress' support.  Currently
    the format affects two areas, files bigger than 8 GiB or that need
    other numeric values not fitting into the traditional tar headers
    and entries with names longer than 100 characters.  For Commons
    Compress these areas can be configured separately while the Antlib
    chooses them based on a single format attribute.</p>

  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Format Attribute</b></td>
      <td valign="top"><b>Numeric values too big like files bigger 8GiB</b></td>
      <td valign="top"><b>Entry names longer 100 characters</b></td>
      <td valign="top"><b>Notes</b></td>
    </tr>
    <tr>
      <td valign="top">ustar</td>
      <td valign="top">Not supported, throws an exception.</td>
      <td valign="top">Not supported, throws an exception.</td>
      <td valign="top">Default.</td>
    </tr>
    <tr>
      <td valign="top">oldgnu</td>
      <td valign="top">Not supported, throws an exception.</td>
      <td valign="top">Uses a GNU tar specific extension.</td>
      <td valign="top">Created archives may be unreadable on MacOS X,
        Solaris or with other non-GNU implementations of tar.</td>
    </tr>
    <tr>
      <td valign="top">star</td>
      <td valign="top" rowspan="2">Uses an extension first introduced by J&#xf6;rg
          Schilling's <a href="http://developer.berlios.de/projects/star">star</a>
          and later adopted by GNU tar and BSD tar.</td>
      <td valign="top">Uses a
          PAX <a href="http://pubs.opengroup.org/onlinepubs/009695399/utilities/pax.html#tag_04_100_13_03">extended
          header</a> as defined by POSIX 1003.1.</td>
      <td valign="top">Created archives will be readable by star and
        modern versions of GNU tar and BSD tar.</td>
    </tr>
    <tr>
      <td valign="top">gnu</td>
      <td valign="top">Uses a GNU tar specific extension.</td>
      <td valign="top">Created archives may be unreadable on MacOS X,
        Solaris or with other non-GNU implementations of tar.  The
        archives are similar to what GNU tar would create by
        default.</td>
    </tr>
    <tr>
      <td valign="top">pax</td>
      <td valign="top" colspan="2">Uses use a PAX extended header as
          defined by POSIX 1003.1.</td>
      <td valign="top">Created archives will be readable by all modern
        implementations of tar.</td>
    </tr>
  </table>

  <h4>Examples</h4>

<pre>
&lt;cmp:tar destfile=&quot;${dist}/manual.tar&quot;
    xmlns:cmp="antlib:org.apache.ant.compress"&gt;
  &lt;fileset dir="htdocs/manual"/&gt;
&lt;cmp:tar/&gt;
&lt;cmp:gzip destfile=&quot;${dist}/manual.tar.gz&quot;
    src=&quot;${dist}/manual.tar&quot;
    xmlns:cmp="antlib:org.apache.ant.compress"/&gt;</pre>

  <p>tars all files in the <code>htdocs/manual</code> directory into a
    file called <code>manual.tar</code> in the <code>${dist}</code>
    directory, then applies the gzip task to compress it.</p>

<pre>
&lt;cmp:tar destfile=&quot;${dist}/manual.tar&quot;
    xmlns:cmp="antlib:org.apache.ant.compress"&gt;
  &lt;fileset dir=&quot;htdocs/manual&quot;
     excludes=&quot;mydocs/**, **/todo.html&quot;
  /&gt;
&lt;cmp:tar/&gt;</pre>

  <p>tars all files in the <code>htdocs/manual</code> directory into a
    file called <code>manual.tar</code> in the <code>${dist}</code>
    directory. Files in the directory <code>mydocs</code>, or files
    with the name <code>todo.html</code> are excluded.</p>

<pre>
&lt;cmp:tar destfile=&quot;${basedir}/docs.tar&quot;
    preserveLeadingSlashes=&quot;true&quot;&gt;
    xmlns:cmp="antlib:org.apache.ant.compress"&gt;
  &lt;cmp:tarfileset dir=&quot;${dir.src}/docs&quot;
              fullpath=&quot;/usr/doc/ant/README&quot;&gt;
    &lt;include name=&quot;readme.txt&quot;/&gt;
  &lt;/cmp:tarfileset&gt;
  &lt;cmp:tarfileset dir=&quot;${dir.src}/docs&quot;
              prefix=&quot;/usr/doc/ant&quot;&gt;
    &lt;include name=&quot;*.html&quot;/&gt;
  &lt;/cmp:tarfileset&gt;
&lt;/cmp:tar&gt;</pre>

  <p>Writes the file <code>docs/readme.txt</code> as
    <code>/usr/doc/ant/README</code> into the archive. All
    <code>*.html</code> files in the <code>docs</code> directory are
    prefixed by <code>/usr/doc/ant</code>, so for example
    <code>docs/index.html</code> is written as
    <code>/usr/doc/ant/index.html</code> to the archive.</p>

<pre>
&lt;cmp:tar format=&quot;oldgnu&quot;
     destfile=&quot;${dist.base}/${dist.name}-src.tar&quot;&gt;
  &lt;tarfileset dir=&quot;${dist.name}/..&quot; filemode=&quot;755&quot; username=&quot;ant&quot; group=&quot;ant&quot;&gt;
    &lt;include name=&quot;${dist.name}/bootstrap.sh&quot;/&gt;
    &lt;include name=&quot;${dist.name}/build.sh&quot;/&gt;
  &lt;/tarfileset&gt;
  &lt;tarfileset dir=&quot;${dist.name}/..&quot; username=&quot;ant&quot; group=&quot;ant&quot;&gt;
    &lt;include name=&quot;${dist.name}/**&quot;/&gt;
    &lt;exclude name=&quot;${dist.name}/bootstrap.sh&quot;/&gt;
    &lt;exclude name=&quot;${dist.name}/build.sh&quot;/&gt;
  &lt;/tarfileset&gt;
&lt;/cmp:tar&gt;
</pre>
<p>This example shows building a tar which uses the GNU extensions for long paths and
where some files need to be marked as executable (mode 755)
and the rest are use the default mode (read-write by owner). The first
fileset selects just the executable files. The second fileset must exclude
the executable files and include all others. </p>

<pre>
&lt;cmp:gzip destfile="release.tar.gz" xmlns:cmp="antlib:org.apache.ant.compress"&gt;
  &lt;cmp:tar&gt;
    &lt;cmp:zipfileset src="release.zip"/&gt;
  &lt;/cmp:tar&gt;
&lt;/cmp:gzip&gt;
</pre>

  <p>Re-packages a ZIP archive as a GZip compressed tar archive.  If
    Unix file permissions have been stored as part of the ZIP file,
    they will be retained in the resulting tar archive.</p>

  <h3><a name="zip">Zip</a></h3>

  <p>An <a href="#archive">archiving task</a> creating archives of the
    ZIP format.</p>

  <p>The discussion about encodings in
    the <a href="http://ant.apache.org/manual/CoreTasks/zip.html#encoding">core
      zip task manual</a> applies to this task as well.</p>
  
  <p><b>Note</b> the following attributes have default values
    different from the core zip
    task: <code>filesonly</code>, <code>whenempty</code>
    and <code>duplicate</code>.  The core task's <code>compress</code>
    attribute isn't available for this task, use
    the <code>level</code> attribute instead where a level of 0
    corresponds to no compression and not specifying a level at all to
    default compression.</p>

  <p>This task supports the following additional attributes:</p>

  <table border="1" cellpadding="2" cellspacing="0">
    <tr>
      <td valign="top"><b>Attribute</b></td>
      <td valign="top"><b>Description</b></td>
      <td align="center" valign="top"><b>Required</b></td>
    </tr>
    <tr>
      <td valign="top">level</td>
      <td valign="top">Non-default level at which file compression should be
        performed. Valid values range from 0 (no compression/fastest) to 9
        (maximum compression/slowest).</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">comment</td>
      <td valign="top">Comment to store in the archive.</td>
      <td valign="top" align="center">No</td>
    </tr>
    <tr>
      <td valign="top">keepcompression</td>
      <td valign="top">For entries coming from existing archives (like
        nested <em>zipfileset</em>s or while updating the archive), keep
        the compression as it has been originally instead of using the
        <em>level</em> attribute.  Defaults to false.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">useLanguageEncodingFlag</td>
      <td valign="top">Whether to set the language encoding flag if the
        encoding is UTF-8.  This setting doesn't have any effect if the
        encoding is not UTF-8.
        <br/>See also
        the <a href="http://ant.apache.org/manual/CoreTasks/zip.html#encoding">discussion</a>
        in the core task's manual.
        Default is true.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">createUnicodeExtraFields</td>
      <td valign="top">Whether to create unicode extra fields to store
        the file names a second time inside the entry's metadata.
        <br>Possible values are "never", "always" and "not-encodable"
        which will only add Unicode extra fields if the file name cannot
        be encoded using the specified encoding.
        <br/>See also
        the <a href="http://ant.apache.org/manual/CoreTasks/zip.html#encoding">discussion</a>
        in the core task's manual.
        Default is "never".</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">fallbacktoUTF8</td>
      <td valign="top">Whether to use UTF-8 and the language encoding
        flag instead of the specified encoding if a file name cannot be
        encoded using the specified encoding.
        <br/>See also
        the <a href="http://ant.apache.org/manual/CoreTasks/zip.html#encoding">discussion</a>
        in the core task's manual.
        Default is false.</td>
      <td align="center" valign="top">No</td>
    </tr>
    <tr>
      <td valign="top">zip64Mode</td>
      <td valign="top">Controls whether Zip64 extended information is
        written to the archive.<br/>
        In order to store entries bigger than 4GB or more than 65536
        entries inside an archive, so called Zip64 extensions must be
        used.  An archive that uses such extensions may not be
        readable by all unarchivers.<br/>
        The possible modes are "always", "never" and "as-needed".  The
        default is "as-needed" which enables Zip64 extensions if a
        resource is added to the archive whose size is known to exceed
        4GB or if there are more than 65536 entries.  "as-needed" does
        not work for resources of unknown size (like URL-resources),
        if you try to archive such resources, the default will be
        "never" instead of "as-needed".<br/>
        If the mode is "never" and the resource actually exceeds the
        limit, the build will fail.
      </td>
      <td align="center" valign="top">No</td>
    </tr>
  </table>

<h3>Examples</h3>
<pre>
&lt;cmp:zip destfile=&quot;${dist}/manual.zip
    xmlns:cmp="antlib:org.apache.ant.compress"&quot;&gt;
  &lt;fileset dir=&quot;htdocs/manual&quot;/&gt;
&lt;cmp:zip/&gt;
</pre>

  <p>zips all files in the <code>htdocs/manual</code> directory into a
    file called <code>manual.zip</code> in the <code>${dist}</code>
    directory.</p>

<!--pre>
&lt;cmp:zip destfile=&quot;${dist}/manual.zip&quot;
    mode="update"
    xmlns:cmp="antlib:org.apache.ant.compress"&quot;&gt;
  &lt;fileset dir=&quot;htdocs/manual&quot;/&gt;
&lt;/cmp:zip&gt;</pre>

  <p>zips all files in the <code>htdocs/manual</code> directory into a
    file called <code>manual.zip</code> in the <code>${dist}</code>
    directory. If <code>manual.zip</code> doesn't exist, it is
    created; otherwise it is updated with the new/changed files.</p-->

<pre>
&lt;cmp:zip destfile=&quot;${dist}/manual.zip&quot;
    xmlns:cmp="antlib:org.apache.ant.compress"&quot;&gt;
  &lt;fileset dir=&quot;htdocs/manual&quot;
       excludes=&quot;mydocs/**, **/todo.html&quot;
    /&gt;
&lt;/cmp:zip&gt;
</pre>

  <p>zips all files in the <code>htdocs/manual</code> directory. Files
    in the directory <code>mydocs</code>, or files with the
    name <code>todo.html</code> are excluded.</p>

<pre>
&lt;cmp:zip destfile=&quot;${dist}/manual.zip&quot;
    xmlns:cmp="antlib:org.apache.ant.compress"&quot;&gt;
  &lt;fileset dir=&quot;htdocs/manual&quot;
       includes=&quot;api/**/*.html&quot;
       excludes=&quot;**/todo.html&quot;
    /&gt;
&lt;/cmp:zip&gt;
</pre>

  <p>zips all files in the <code>htdocs/manual</code> directory. Only
    html files under the directory <code>api</code> are zipped, and
    files with the name <code>todo.html</code> are excluded.</p>

<pre>
&lt;cmp:zip destfile=&quot;${dist}/manual.zip&quot; xmlns:cmp="antlib:org.apache.ant.compress"&quot;&gt;
  &lt;fileset dir=&quot;htdocs/manual&quot;/&gt;
  &lt;fileset dir=&quot;.&quot; includes=&quot;ChangeLog.txt&quot;/&gt;
&lt;/cmp:zip&gt;</pre>

  <p>zips all files in the <code>htdocs/manual</code> directory, and
    also adds the file <code>ChangeLog.txt</code> in the current
    directory. <code>ChangeLog.txt</code> will be added to the top of
    the ZIP file, just as if it had been located
    at <code>htdocs/manual/ChangeLog.txt</code>.</p>

<pre>
&lt;cmp:zip destfile=&quot;${dist}/manual.zip&quot; xmlns:cmp="antlib:org.apache.ant.compress"&quot;&gt;
  &lt;cmp:zipfileset dir=&quot;htdocs/manual&quot; prefix=&quot;docs/user-guide&quot;/&gt;
  &lt;cmp:zipfileset dir=&quot;.&quot; includes=&quot;ChangeLog27.txt&quot; fullpath=&quot;docs/ChangeLog.txt&quot;/&gt;
  &lt;cmp:zipfileset src=&quot;examples.zip&quot; includes=&quot;**/*.html&quot; prefix=&quot;docs/examples&quot;/&gt;
&lt;/cmp:zip&gt;</pre>

  <p>zips all files in the <code>htdocs/manual</code> directory into
    the <code>docs/user-guide</code> directory in the archive, adds
    the file <code>ChangeLog27.txt</code> in the current directory
    as <code>docs/ChangeLog.txt</code>, and includes all the html
    files in <code>examples.zip</code>
    under <code>docs/examples</code>.  The archive might end up
    containing the files:</p>
<pre>    docs/user-guide/html/index.html
    docs/ChangeLog.txt
    docs/examples/index.html
</pre>

  <p>The code</p>

<pre>
&lt;cmp:zip destfile=&quot;${dist}/manual.zip&quot; xmlns:cmp="antlib:org.apache.ant.compress"&quot;&gt;
  &lt;cmp:zipfileset dir=&quot;htdocs/manual&quot; prefix=&quot;docs/user-guide&quot;/&gt;
  &lt;cmp:archives&gt;
    &lt;zips&gt;
      &lt;fileset dir=&quot;.&quot; includes=&quot;examples*.zip&quot;/&gt;
    &lt;/zips&gt;
  &lt;/cmp:archives&gt;
&lt;/cmp:zip&gt;
</pre>

  <p>zips all files in the <code>htdocs/manual</code> directory into
    the <code>docs/user-guide</code> directory in the archive and
    includes all the files in any file that
    maches <code>examples*.zip</code>, such as all files
    within <code>examples1.zip</code>
    or <code>examples_for_brian.zip</code>.  The same can be achieved
    with</p>

<pre>
&lt;cmp:zip destfile=&quot;${dist}/manual.zip&quot; xmlns:cmp="antlib:org.apache.ant.compress"&quot;&gt;
  &lt;mappedresources&gt;
    &lt;fileset dir=&quot;htdocs/manual&quot;/&gt;
    &lt;globmapper from="*" to="docs/user-guide/*"/&gt;
  &lt;/mappedresources&gt;
  &lt;archives&gt;
    &lt;zips&gt;
      &lt;fileset dir=&quot;.&quot; includes=&quot;examples*.zip&quot;/&gt;
    &lt;/zips&gt;
  &lt;/archives&gt;
&lt;/cmp:zip&gt;
</pre>

  <p>The next example</p>

<pre>
&lt;cmp:zip dest="release.zip" xmlns:cmp="antlib:org.apache.ant.compress"&quot;&gt;
  &lt;cmp:tarfileset src="release.tar"/&gt;
&lt;/cmp:zip&gt;
</pre>

  <p>re-packages a TAR archive as a ZIP archive.  If Unix file
    permissions have been stored as part of the TAR file, they will be
    retained in the resulting ZIP archive.</p>

</body>
</html>