<!--
   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 zip task.
      </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, 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>

  <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="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 for entries with names longer than
        100 characters.  Supported values are "ustar" which doesn't
        support entries of that length and results in a build failure
        and "oldgnu".</td>
      <td valign="top" align="center">No, default is "ustar"</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 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>
  </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>