| <!-- |
| 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 "add", "preserve", and |
| "fail". The default value is |
| "fail". </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 |
| "fail" and "skip". Default is |
| "fail".</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ö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> |
| <cmp:tar destfile="${dist}/manual.tar" |
| xmlns:cmp="antlib:org.apache.ant.compress"> |
| <fileset dir="htdocs/manual"/> |
| <cmp:tar/> |
| <cmp:gzip destfile="${dist}/manual.tar.gz" |
| src="${dist}/manual.tar" |
| xmlns:cmp="antlib:org.apache.ant.compress"/></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> |
| <cmp:tar destfile="${dist}/manual.tar" |
| xmlns:cmp="antlib:org.apache.ant.compress"> |
| <fileset dir="htdocs/manual" |
| excludes="mydocs/**, **/todo.html" |
| /> |
| <cmp:tar/></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> |
| <cmp:tar destfile="${basedir}/docs.tar" |
| preserveLeadingSlashes="true"> |
| xmlns:cmp="antlib:org.apache.ant.compress"> |
| <cmp:tarfileset dir="${dir.src}/docs" |
| fullpath="/usr/doc/ant/README"> |
| <include name="readme.txt"/> |
| </cmp:tarfileset> |
| <cmp:tarfileset dir="${dir.src}/docs" |
| prefix="/usr/doc/ant"> |
| <include name="*.html"/> |
| </cmp:tarfileset> |
| </cmp:tar></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> |
| <cmp:tar format="oldgnu" |
| destfile="${dist.base}/${dist.name}-src.tar"> |
| <tarfileset dir="${dist.name}/.." filemode="755" username="ant" group="ant"> |
| <include name="${dist.name}/bootstrap.sh"/> |
| <include name="${dist.name}/build.sh"/> |
| </tarfileset> |
| <tarfileset dir="${dist.name}/.." username="ant" group="ant"> |
| <include name="${dist.name}/**"/> |
| <exclude name="${dist.name}/bootstrap.sh"/> |
| <exclude name="${dist.name}/build.sh"/> |
| </tarfileset> |
| </cmp:tar> |
| </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> |
| <cmp:gzip destfile="release.tar.gz" xmlns:cmp="antlib:org.apache.ant.compress"> |
| <cmp:tar> |
| <cmp:zipfileset src="release.zip"/> |
| </cmp:tar> |
| </cmp:gzip> |
| </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> |
| <cmp:zip destfile="${dist}/manual.zip |
| xmlns:cmp="antlib:org.apache.ant.compress""> |
| <fileset dir="htdocs/manual"/> |
| <cmp:zip/> |
| </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> |
| <cmp:zip destfile="${dist}/manual.zip" |
| mode="update" |
| xmlns:cmp="antlib:org.apache.ant.compress""> |
| <fileset dir="htdocs/manual"/> |
| </cmp:zip></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> |
| <cmp:zip destfile="${dist}/manual.zip" |
| xmlns:cmp="antlib:org.apache.ant.compress""> |
| <fileset dir="htdocs/manual" |
| excludes="mydocs/**, **/todo.html" |
| /> |
| </cmp:zip> |
| </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> |
| <cmp:zip destfile="${dist}/manual.zip" |
| xmlns:cmp="antlib:org.apache.ant.compress""> |
| <fileset dir="htdocs/manual" |
| includes="api/**/*.html" |
| excludes="**/todo.html" |
| /> |
| </cmp:zip> |
| </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> |
| <cmp:zip destfile="${dist}/manual.zip" xmlns:cmp="antlib:org.apache.ant.compress""> |
| <fileset dir="htdocs/manual"/> |
| <fileset dir="." includes="ChangeLog.txt"/> |
| </cmp:zip></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> |
| <cmp:zip destfile="${dist}/manual.zip" xmlns:cmp="antlib:org.apache.ant.compress""> |
| <cmp:zipfileset dir="htdocs/manual" prefix="docs/user-guide"/> |
| <cmp:zipfileset dir="." includes="ChangeLog27.txt" fullpath="docs/ChangeLog.txt"/> |
| <cmp:zipfileset src="examples.zip" includes="**/*.html" prefix="docs/examples"/> |
| </cmp:zip></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> |
| <cmp:zip destfile="${dist}/manual.zip" xmlns:cmp="antlib:org.apache.ant.compress""> |
| <cmp:zipfileset dir="htdocs/manual" prefix="docs/user-guide"/> |
| <cmp:archives> |
| <zips> |
| <fileset dir="." includes="examples*.zip"/> |
| </zips> |
| </cmp:archives> |
| </cmp:zip> |
| </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> |
| <cmp:zip destfile="${dist}/manual.zip" xmlns:cmp="antlib:org.apache.ant.compress""> |
| <mappedresources> |
| <fileset dir="htdocs/manual"/> |
| <globmapper from="*" to="docs/user-guide/*"/> |
| </mappedresources> |
| <archives> |
| <zips> |
| <fileset dir="." includes="examples*.zip"/> |
| </zips> |
| </archives> |
| </cmp:zip> |
| </pre> |
| |
| <p>The next example</p> |
| |
| <pre> |
| <cmp:zip dest="release.zip" xmlns:cmp="antlib:org.apache.ant.compress""> |
| <cmp:tarfileset src="release.tar"/> |
| </cmp:zip> |
| </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> |
