2006-09-11 04:19:00 +00:00
|
|
|
<!--
|
|
|
|
|
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.
|
|
|
|
|
-->
|
2001-02-13 12:32:01 +00:00
|
|
|
<html>
|
|
|
|
|
|
|
|
|
|
<head>
|
|
|
|
|
<meta http-equiv="Content-Language" content="en-us">
|
2005-04-29 18:58:16 +00:00
|
|
|
<link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
|
2002-03-03 06:52:07 +00:00
|
|
|
<title>Zip Task</title>
|
2001-02-13 12:32:01 +00:00
|
|
|
</head>
|
|
|
|
|
|
|
|
|
|
<body>
|
|
|
|
|
|
2018-01-22 23:52:21 +01:00
|
|
|
<h2 id="zip">Zip</h2>
|
2001-02-13 12:32:01 +00:00
|
|
|
<h3>Description</h3>
|
|
|
|
|
<p>Creates a zipfile.</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>The <var>basedir</var> attribute is the reference directory from where to zip.</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
<p>Note that file permissions will not be stored in the resulting zipfile.</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
|
|
|
|
|
<p>It is possible to refine the set of files that are being zipped. This can be done with
|
|
|
|
|
the <var>includes</var>, <var>includesfile</var>, <var>excludes</var>, <var>excludesfile</var>
|
|
|
|
|
and <var>defaultexcludes</var> attributes. With the <var>includes</var> or <var>includesfile</var>
|
|
|
|
|
attribute you specify the files you want to have included by using patterns. The <var>exclude</var>
|
|
|
|
|
or <var>excludesfile</var> attribute is used to specify the files you want to have excluded. This is
|
|
|
|
|
also done with patterns. And finally with the <var>defaultexcludes</var> attribute, you can specify
|
|
|
|
|
whether you want to use default exclusions or not. See the section
|
|
|
|
|
on <a href="../dirtasks.html#directorybasedtasks">directory based tasks</a>, on how the
|
2018-01-22 23:52:21 +01:00
|
|
|
inclusion/exclusion of files works, and how to write patterns.</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
|
|
|
|
|
<p>This task forms an implicit <a href="../Types/fileset.html">FileSet</a> and supports most
|
|
|
|
|
attributes of <code><fileset></code> (<var>dir</var> becomes <var>basedir</var>) as well as
|
|
|
|
|
the nested <code><include></code>, <code><exclude></code>
|
|
|
|
|
and <code><patternset></code> elements.</p>
|
|
|
|
|
|
|
|
|
|
<p>Or, you may place within it nested file sets, or references to file sets. In this
|
|
|
|
|
case <var>basedir</var> is optional; the implicit file set is <em>only used</em>
|
|
|
|
|
if <var>basedir</var> is set. You may use any mixture of the implicit file set
|
|
|
|
|
(with <var>basedir</var> set, and optional attributes like <var>includes</var> and optional
|
|
|
|
|
subelements like <code><include></code>); explicit nested <code><fileset></code>
|
|
|
|
|
elements so long as at least one fileset total is specified. The ZIP file will only reflect the
|
|
|
|
|
relative paths of files <em>within</em> each fileset. The Zip task and its derivatives know a
|
|
|
|
|
special form of a fileset named <code>zipfileset</code> that has additional attributes (described
|
|
|
|
|
below).</p>
|
|
|
|
|
|
|
|
|
|
<p>The Zip task also supports the merging of multiple zip files into the zip file. This is possible
|
|
|
|
|
through either the <var>src</var> attribute of any nested filesets or by using the special nested
|
|
|
|
|
fileset <code>zipgroupfileset</code>.</p>
|
|
|
|
|
|
|
|
|
|
<p>The <var>update</var> parameter controls what happens if the ZIP file already exists. When set
|
|
|
|
|
to <q>yes</q>, the ZIP file is updated with the files specified. (New files are added; old files are
|
|
|
|
|
replaced with the new versions.) When set to <q>no</q> (the default) the ZIP file is overwritten if
|
|
|
|
|
any of the files that would be added to the archive are newer than the entries inside the archive.
|
|
|
|
|
Please note that ZIP files store file modification times with a granularity of 2 seconds. If a file
|
|
|
|
|
is less than 2 seconds newer than the entry in the archive, Apache Ant will not consider it
|
|
|
|
|
newer.</p>
|
|
|
|
|
|
|
|
|
|
<p>The <var>whenempty</var> parameter controls what happens when no files match. If <q>skip</q>
|
|
|
|
|
(the default), the ZIP is not created and a warning is issued. If <q>fail</q>, the ZIP is not
|
|
|
|
|
created and the build is halted with an error. If <q>create</q>, an empty ZIP file (explicitly zero
|
|
|
|
|
entries) is created, which should be recognized as such by compliant ZIP manipulation tools.</p>
|
|
|
|
|
|
|
|
|
|
<p>This task will now use default JVM character encoding for filenames—this is consistent with
|
|
|
|
|
the command line ZIP tools, but causes problems if you try to open them from within Java and your
|
|
|
|
|
filenames contain non US-ASCII characters. Use the <var>encoding</var> attribute and set it
|
|
|
|
|
to <q>UTF8</q> to create zip files that can safely be read by Java. For a more complete discussion,
|
2009-02-27 17:00:59 +00:00
|
|
|
see <a href="#encoding">below</a></p>
|
2002-12-09 12:40:38 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p><em>Since Ant 1.5.2</em>, <code><zip></code> can store Unix permissions inside the archive
|
|
|
|
|
(see description of the <var>filemode</var> and <var>dirmode</var> attributes
|
|
|
|
|
for <a href="../Types/zipfileset.html"><zipfileset></a>). Unfortunately there is no portable
|
2018-03-08 07:43:53 +01:00
|
|
|
way to store these permissions. Ant uses the algorithm used by <a href="http://www.info-zip.org"
|
2018-03-10 20:17:33 +01:00
|
|
|
target="_top">Info-Zip's</a> implementation of the <kbd>zip</kbd> and <kbd>unzip</kbd>
|
|
|
|
|
commands—these are the default versions of <kbd>zip</kbd> and <kbd>unzip</kbd> for many
|
2018-03-08 07:43:53 +01:00
|
|
|
Unix(-like) systems.</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
|
|
|
|
|
<p><strong>Please note that the zip format allows multiple files of the same fully-qualified name to
|
|
|
|
|
exist within a single archive. This has been documented as causing various problems for
|
|
|
|
|
unsuspecting users. If you wish to avoid this behavior you must set the <var>duplicate</var>
|
|
|
|
|
attribute to a value other than its default, <q>add</q>.</strong></p>
|
|
|
|
|
|
|
|
|
|
<p><strong>Please also note</strong> that different ZIP tools handle timestamps differently when it
|
|
|
|
|
comes to applying timezone offset calculations of files. Some ZIP libraries will store the
|
|
|
|
|
timestamps as they've been read from the filesystem while others will modify the timestamps both
|
|
|
|
|
when reading and writing the files to make all timestamps use the same timezone. A ZIP archive
|
|
|
|
|
created by one library may extract files with "wrong timestamps" when extracted by another
|
|
|
|
|
library.</p>
|
|
|
|
|
|
|
|
|
|
<p>Ant's ZIP classes use the same algorithm as the InfoZIP tools and zlib (timestamps get adjusted),
|
|
|
|
|
Windows' "compressed folders" function and WinZIP don't change the timestamps. This means that
|
|
|
|
|
using the <code>unzip</code> task on files created by Windows' compressed folders function may
|
|
|
|
|
create files with timestamps that are "wrong", the same is true if you use Windows' functions to
|
|
|
|
|
extract an Ant generated ZIP archive.</p>
|
2008-07-11 09:25:30 +00:00
|
|
|
|
2001-02-13 12:32:01 +00:00
|
|
|
<h3>Parameters</h3>
|
2018-02-28 07:58:59 +01:00
|
|
|
<table class="attr">
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
2018-05-15 10:29:27 +02:00
|
|
|
<th scope="col">Attribute</th>
|
|
|
|
|
<th scope="col">Description</th>
|
|
|
|
|
<th scope="col">Required</th>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>destfile</td>
|
|
|
|
|
<td>the zip file to create.</td>
|
|
|
|
|
<td rowspan="2">Exactly one of the two</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
2002-06-22 23:38:38 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>zipfile</td>
|
|
|
|
|
<td class="left"><em><u>deprecated</u></em> old name of <var>destfile</var>.</td>
|
2002-06-22 23:38:38 +00:00
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>basedir</td>
|
|
|
|
|
<td>the directory from which to zip the files.</td>
|
|
|
|
|
<td>No</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>compress</td>
|
|
|
|
|
<td>Not only store data but also compress them. Unless you set the <var>keepcompression</var>
|
|
|
|
|
attribute to <q>false</q>, this will apply to the entire archive, not only the files you've
|
|
|
|
|
added while updating.</td>
|
|
|
|
|
<td>No; defaults to <q>true</q></td>
|
2003-08-05 16:13:02 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>keepcompression</td>
|
|
|
|
|
<td>For entries coming from existing archives (like nested <code>zipfileset</code>s or while
|
|
|
|
|
updating the archive), keep the compression as it has been originally instead of using
|
|
|
|
|
the <var>compress</var> attribute. <em>Since Ant 1.6</em></td>
|
|
|
|
|
<td>No; defaults to <q>false</q></td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
2001-07-05 13:10:26 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>encoding</td>
|
|
|
|
|
<td>The character encoding to use for filenames inside the zip file. For a list of possible
|
|
|
|
|
values see
|
2018-03-08 07:43:53 +01:00
|
|
|
the <a href="https://docs.oracle.com/javase/8/docs/technotes/guides/intl/encoding.doc.html"
|
|
|
|
|
target="_top">Supported Encodings</a>.</td>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>No; defaults to default JVM character encoding</td>
|
2001-07-05 13:10:26 +00:00
|
|
|
</tr>
|
2001-07-12 07:36:50 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>filesonly</td>
|
|
|
|
|
<td>Store only file entries.</td>
|
|
|
|
|
<td>No; defaults to <q>false</q></td>
|
2001-07-12 07:36:50 +00:00
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>includes</td>
|
|
|
|
|
<td>comma- or space-separated list of patterns of files that must be included.</td>
|
|
|
|
|
<td>No; defaults to all (<q>**</q>)</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>includesfile</td>
|
|
|
|
|
<td>name of a file. Each line of this file is taken to be an include pattern.</td>
|
|
|
|
|
<td>No</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>excludes</td>
|
|
|
|
|
<td>comma- or space-separated list of patterns of files that must be excluded.</td>
|
|
|
|
|
<td>No; defaults to default excludes or none if <var>defaultexcludes</var> is <q>no</q></td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>excludesfile</td>
|
|
|
|
|
<td>name of a file. Each line of this file is taken to be an exclude pattern.</td>
|
|
|
|
|
<td>No</td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>defaultexcludes</td>
|
|
|
|
|
<td>indicates whether default excludes should be used or not (<q>yes|no</q>).</td>
|
|
|
|
|
<td>No; defaults to <q>yes</q></td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
2001-08-30 13:23:14 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>update</td>
|
|
|
|
|
<td>indicates whether to update or overwrite the destination file if it already exists.</td>
|
|
|
|
|
<td>No; default is <q>false</q></td>
|
2001-08-30 13:23:14 +00:00
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>whenempty</td>
|
|
|
|
|
<td>behavior when no files match. Valid values are <q>fail</q>, <q>skip</q>,
|
|
|
|
|
and <q>create</q>.</td>
|
|
|
|
|
<td>No; default is <q>skip</q></td>
|
2002-03-03 06:52:07 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>duplicate</td>
|
|
|
|
|
<td>behavior when a duplicate file is found. Valid values are <q>add</q>, <q>preserve</q>,
|
|
|
|
|
and <q>fail</q>.</td>
|
|
|
|
|
<td>No; default is <q>add</q></td>
|
2001-02-13 12:32:01 +00:00
|
|
|
</tr>
|
2004-02-27 14:17:41 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>roundup</td>
|
|
|
|
|
<td>Whether the file modification times will be rounded up to the next even number of
|
|
|
|
|
seconds.<br/>Zip archives store file modification times with a granularity of 2 seconds, so
|
|
|
|
|
the 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. <em>Since Ant 1.6.2</em></td>
|
|
|
|
|
<td>No; defaults to <q>true</q></td>
|
2004-02-27 14:17:41 +00:00
|
|
|
</tr>
|
2005-01-18 12:35:37 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>comment</td>
|
|
|
|
|
<td>Comment to store in the archive. <em>Since Ant 1.6.3</em></td>
|
|
|
|
|
<td>No</td>
|
2005-01-18 12:35:37 +00:00
|
|
|
</tr>
|
2005-02-02 23:55:51 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>level</td>
|
|
|
|
|
<td>Non-default level at which file compression should be performed. Valid values range
|
|
|
|
|
from <q>0</q> (no compression/fastest) to <q>9</q> (maximum compression/slowest). <em>Since
|
|
|
|
|
Ant 1.7</em></td>
|
|
|
|
|
<td>No</td>
|
2005-02-02 23:55:51 +00:00
|
|
|
</tr>
|
2008-07-17 14:44:30 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>preserve0permissions</td>
|
|
|
|
|
<td>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 <q>true</q> if you really want to
|
|
|
|
|
preserve the original permission field. <em>Since Ant 1.8.0</em>
|
2008-07-17 14:44:30 +00:00
|
|
|
</td>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>No; default is <q>false</q></td>
|
2008-07-17 14:44:30 +00:00
|
|
|
</tr>
|
2009-02-27 17:00:59 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>useLanguageEncodingFlag</td>
|
|
|
|
|
<td>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. <em>Since Ant 1.8.0</em>.<br/>See also
|
|
|
|
|
the <a href="#encoding">discussion below</a></td>
|
|
|
|
|
<td>No; default is <q>true</q></td>
|
2009-02-27 17:00:59 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>createUnicodeExtraFields</td>
|
|
|
|
|
<td>Whether to create Unicode extra fields to store the file names a second time inside the
|
|
|
|
|
entry's metadata.<br/>Possible values are <q>never</q>, <q>always</q>
|
|
|
|
|
and <q>not-encodeable</q> which will only add Unicode extra fields if the file name cannot be
|
|
|
|
|
encoded using the specified encoding. <em>Since Ant 1.8.0</em>.<br/>See also
|
|
|
|
|
the <a href="#encoding">discussion below</a></td>
|
|
|
|
|
<td>No; default is <q>never</q></td>
|
2009-03-04 16:54:39 +00:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>fallbacktoUTF8</td>
|
|
|
|
|
<td>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. <em>Since Ant 1.8.0</em>.<br/>See
|
|
|
|
|
also the <a href="#encoding">discussion below</a></td>
|
|
|
|
|
<td>No; default is <q>false</q></td>
|
2009-02-27 17:00:59 +00:00
|
|
|
</tr>
|
2013-03-31 11:24:47 +00:00
|
|
|
<tr>
|
2018-02-28 07:58:59 +01:00
|
|
|
<td>zip64Mode</td>
|
|
|
|
|
<td>When to use Zip64 extensions for entries. The possible values
|
|
|
|
|
are <q>never</q>, <q>always</q> and <q>as-needed</q>. <em>Since Ant 1.9.1</em>.<br/>See also
|
|
|
|
|
the <a href="#zip64">discussion below</a></td>
|
|
|
|
|
<td>No; default is <q>as-needed</q></td>
|
2013-03-31 11:24:47 +00:00
|
|
|
</tr>
|
2001-02-13 12:32:01 +00:00
|
|
|
</table>
|
2009-02-27 17:00:59 +00:00
|
|
|
|
2018-03-05 21:01:42 +01:00
|
|
|
<h3 id="encoding">Encoding of file names</h3>
|
2009-02-27 17:00:59 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>Traditionally the ZIP archive format uses CodePage 437 as encoding for file name, which is not
|
|
|
|
|
sufficient for many international character sets.</p>
|
|
|
|
|
|
|
|
|
|
<p>Over time different archivers have chosen different ways to work around the
|
2018-03-10 20:17:33 +01:00
|
|
|
limitation—the <code class="code">java.util.zip</code> packages simply uses UTF-8 as its
|
|
|
|
|
encoding for example.</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
|
|
|
|
|
<p>Ant has been offering the <q>encoding</q> attribute of the <code>zip</code>
|
|
|
|
|
and <code>unzip</code> task as a way to explicitly specify the encoding to use (or expect) <em>since
|
|
|
|
|
Ant 1.4</em>. It defaults to default JVM character encoding for <code>zip</code> and UTF-8
|
|
|
|
|
for <code>jar</code> and other jar-like tasks (<code>war</code>, <code>ear</code>, ...) as well as
|
|
|
|
|
the <code>unzip</code> family of tasks.</p>
|
|
|
|
|
|
|
|
|
|
<p>More recent versions of the ZIP specification introduce something called the <q>language encoding
|
|
|
|
|
flag</q> which can be used to signal that a file name has been encoded using UTF-8. <em>Since Ant
|
|
|
|
|
1.8.0</em>, all zip, jar and similar archives written by Ant will set this flag, if the encoding has
|
|
|
|
|
been set to UTF-8. Our interoperability tests with existing archivers didn't show any ill effects
|
|
|
|
|
(in fact, most archivers ignore the flag to date), but you can turn off the <q>language encoding
|
|
|
|
|
flag</q> by setting the attribute <var>useLanguageEncodingFlag</var> to <q>false</q> on
|
|
|
|
|
the <code>zip</code> task if you should encounter problems.</p>
|
|
|
|
|
|
|
|
|
|
<p>The <code>unzip</code> task (and similar tasks) will recognize the language encoding flag and
|
|
|
|
|
ignore the encoding set on the task if it has been found.</p>
|
|
|
|
|
|
|
|
|
|
<p>The InfoZIP developers have introduced new ZIP extra fields that can be used to add an additional
|
|
|
|
|
UTF-8 encoded file name to the entry's metadata. Most archivers ignore these extra
|
|
|
|
|
fields. <em>Since Ant 1.8.0</em>, the <code>zip</code> family of tasks support an
|
|
|
|
|
option <var>createUnicodeExtraFields</var>, which makes Ant write these extra fields either for all
|
|
|
|
|
entries (<q>always</q>) or only those whose name cannot be encoded using the specified encoding
|
|
|
|
|
(<q>not-encodeable</q>), it defaults to <q>never</q> since the extra fields create bigger
|
|
|
|
|
archives.</p>
|
|
|
|
|
|
|
|
|
|
<p>The <var>fallbackToUTF8</var> attribute of <code>zip</code> can be used to create archives that
|
|
|
|
|
use the specified encoding in the majority of cases but UTF-8 and the language encoding flag for
|
|
|
|
|
filenames that cannot be encoded using the specified encoding.</p>
|
|
|
|
|
|
|
|
|
|
<p>The <code>unzip</code> task will recognize the Unicode extra fields by default and read the file
|
|
|
|
|
name information from them, unless you set the optional
|
|
|
|
|
attribute <var>scanForUnicodeExtraFields</var> to <q>false</q>.</p>
|
2009-02-27 17:00:59 +00:00
|
|
|
|
2018-03-05 21:01:42 +01:00
|
|
|
<h4>Recommendations for interoperability</h4>
|
2009-02-27 17:00:59 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>The optimal setting of flags depends on the archivers you expect as consumers/producers of the
|
|
|
|
|
ZIP archives. Below are some test results which may be superseded with later versions of each
|
|
|
|
|
tool.</p>
|
2009-02-27 17:00:59 +00:00
|
|
|
|
|
|
|
|
<ul>
|
2018-03-10 20:17:33 +01:00
|
|
|
<li>The <code class="code">java.util.zip</code> package used by the <kbd>jar</kbd> executable or
|
|
|
|
|
to read jars from your <code>CLASSPATH</code> reads and writes UTF-8 names, it doesn't set or
|
|
|
|
|
recognize any flags or unicode extra fields.</li>
|
|
|
|
|
<li>Since Java 7, <code class="code">java.util.zip</code> writes UTF-8 by default and uses the
|
|
|
|
|
language encoding flag. It is possible to specify a different encoding when reading/writing
|
|
|
|
|
ZIPs via new constructors. The package now recognizes the language encoding flag when reading
|
|
|
|
|
and ignores the Unicode extra fields.</li>
|
2018-02-28 07:58:59 +01:00
|
|
|
<li>7Zip writes CodePage 437 by default but uses UTF-8 and the language encoding flag when writing
|
|
|
|
|
entries that cannot be encoded as CodePage 437 (similar to the <code>zip</code> task
|
|
|
|
|
with <var>fallbacktoUTF8</var> set to <q>true</q>). It recognizes the language encoding flag
|
|
|
|
|
when reading and ignores the Unicode extra fields.</li>
|
|
|
|
|
<li>WinZIP writes CodePage 437 and uses Unicode extra fields by default. It recognizes the
|
|
|
|
|
Unicode extra field and the language encoding flag when reading.</li>
|
|
|
|
|
<li>Windows' "compressed folder" feature doesn't recognize any flag or extra field and creates
|
|
|
|
|
archives using the default platform encoding—and expects archives to be in that encoding
|
|
|
|
|
when reading them.</li>
|
|
|
|
|
<li>InfoZIP based tools can recognize and write both, it is a compile time option and depends on
|
|
|
|
|
the platform so your mileage may vary.</li>
|
|
|
|
|
<li>PKWARE zip tools recognize both and prefer the language encoding flag. They create archives
|
|
|
|
|
using CodePage 437 if possible and UTF-8 plus the language encoding flag for file names that
|
|
|
|
|
cannot be encoded as CodePage 437.</li>
|
2009-02-27 17:00:59 +00:00
|
|
|
</ul>
|
|
|
|
|
|
|
|
|
|
<p>So, what to do?</p>
|
|
|
|
|
|
2018-03-10 20:17:33 +01:00
|
|
|
<p>If you are creating jars, then <code class="code">java.util.zip</code> is your main consumer. We
|
|
|
|
|
recommend you set the encoding to UTF-8 and keep the language encoding flag enabled. The flag won't
|
|
|
|
|
help or hurt <code class="code">java.util.zip</code> prior to Java 7 but archivers that support it
|
|
|
|
|
will show the correct file names.</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
|
|
|
|
|
<p>For maximum interoparability it is probably best to set the encoding to UTF-8, enable the
|
|
|
|
|
language encoding flag and create Unicode extra fields when writing ZIPs. Such archives should be
|
2018-03-10 20:17:33 +01:00
|
|
|
extracted correctly by <code class="code">java.util.zip</code>, 7Zip, WinZIP, PKWARE tools and most
|
|
|
|
|
likely InfoZIP tools. They will be unusable with Windows' "compressed folders" feature and bigger
|
|
|
|
|
than archives without the Unicode extra fields, though.</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
|
|
|
|
|
<p>If Windows' "compressed folders" is your primary consumer, then your best option is to explicitly
|
|
|
|
|
set the encoding to the target platform. You may want to enable creation of Unicode extra fields so
|
|
|
|
|
the tools that support them will extract the file names correctly.</p>
|
2009-02-27 17:00:59 +00:00
|
|
|
|
2018-01-22 23:52:21 +01:00
|
|
|
<h3 id="zip64">Zip64 extensions</h3>
|
2013-03-31 11:24:47 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>Zip64 extensions provide a way to create archives bigger than 4 GB or holding more than 65535
|
|
|
|
|
entries—or add individual entries bigger than 4 GB using the ZIP extension field mechanism.
|
|
|
|
|
These extensions are supported by most modern ZIP implementations.</p>
|
2013-03-31 11:24:47 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>When Ant writes compressed entries into the archive it creates it doesn't know the compressed
|
|
|
|
|
size of an entry before it has been written. Unfortunately the decision whether a Zip64 extra field
|
|
|
|
|
will be written has to be made before writing the entry's content.</p>
|
2013-03-31 11:24:47 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>Ant 1.9.0 introduced support for Zip64 extensions but didn't provide any control over their
|
|
|
|
|
usage. <em>Since Ant 1.9.1</em>, a new <var>zip64mode</var> attribute was added to
|
|
|
|
|
the <code>zip</code> family of tasks. It supports three values:
|
2013-03-31 11:24:47 +00:00
|
|
|
|
|
|
|
|
<ul>
|
2018-02-28 07:58:59 +01:00
|
|
|
<li><q>never</q> means no Zip64 extra fields will ever be written. This is the behavior of Ant
|
|
|
|
|
prior to 1.9.0 and the default behavior of <code>jar</code>, <code>ear</code>
|
2018-01-24 21:40:28 +01:00
|
|
|
and <code>war</code> <em>since Ant 1.9.1</em>.</li>
|
2018-02-28 07:58:59 +01:00
|
|
|
<li><q>always</q> means Zip64 extra fields are written for all entries.</li>
|
|
|
|
|
<li><q>as-needed</q> means Zip64 extra fields are written for all compressed entries to the "local
|
|
|
|
|
file header" (by default these are all files but not the directories) but only written to the
|
|
|
|
|
central directory if the entry really required Zip64 features. This is the default behavior of
|
|
|
|
|
Ant 1.9.0 and remains the default behavior of the <code>zip</code> task.</li>
|
2013-03-31 11:24:47 +00:00
|
|
|
</ul>
|
|
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p><q>as-needed</q> provides a good compromise if you don't know whether you archive will exceed the
|
|
|
|
|
limits of traditional zip files but don't want to waste too much space (the Zip64 extensions take up
|
|
|
|
|
extra space). Unfortunately some ZIP implementations don't understand Zip64 extra fields or fail to
|
|
|
|
|
parse archives with extra fields in local file headers that are not present in the central
|
2018-03-10 20:17:33 +01:00
|
|
|
directory, one such implementation is the <code class="code">java.util.zip</code> package of Java 5,
|
|
|
|
|
that's why the <code>jar</code> tasks default to <q>never</q>. Archives created
|
|
|
|
|
with <q>as-needed</q> can be read without problems with Java 6 and later.</p>
|
2013-03-31 11:24:47 +00:00
|
|
|
|
2001-02-13 12:32:01 +00:00
|
|
|
<h3>Parameters specified as nested elements</h3>
|
2002-12-09 12:40:38 +00:00
|
|
|
|
2005-11-29 04:51:01 +00:00
|
|
|
<h4>any resource collection</h4>
|
2018-03-05 17:35:30 +01:00
|
|
|
<p><a href="../Types/resources.html#collection">resource collections</a> are used to select groups
|
2018-02-28 07:58:59 +01:00
|
|
|
of files to archive.</p>
|
|
|
|
|
<p>Prior to Ant 1.7 only <code><fileset></code> and <code><zipfileset></code> have been
|
|
|
|
|
supported as nested elements.</p>
|
2002-12-09 12:40:38 +00:00
|
|
|
|
2018-01-22 23:52:21 +01:00
|
|
|
<h4 id="zipgroupfileset">zipgroupfileset</h4>
|
2018-02-28 07:58:59 +01:00
|
|
|
<p>A <code><zipgroupfileset></code> allows for multiple zip files to be merged into the
|
|
|
|
|
archive. Each file found in this fileset is added to the archive the same way
|
|
|
|
|
that <code>zipfileset</code> <var>src</var> files are added.</p>
|
2002-03-03 06:52:07 +00:00
|
|
|
|
2018-02-28 07:58:59 +01:00
|
|
|
<p><code><zipgroupfileset></code> is a <a href="../Types/fileset.html">fileset</a> and
|
|
|
|
|
supports all of its attributes and nested elements.</p>
|
2001-02-13 12:32:01 +00:00
|
|
|
|
|
|
|
|
<h3>Examples</h3>
|
2018-05-15 09:51:58 +02:00
|
|
|
<p>Zip all files in the <samp>htdocs/manual</samp> directory into a file
|
|
|
|
|
called <samp>manual.zip</samp> in the <samp>${dist}</samp> directory.</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
<pre>
|
|
|
|
|
<zip destfile="${dist}/manual.zip"
|
|
|
|
|
basedir="htdocs/manual"/></pre>
|
2018-05-15 09:51:58 +02:00
|
|
|
|
|
|
|
|
<p>Zip all files in the <samp>htdocs/manual</samp> directory into a file
|
|
|
|
|
called <samp>manual.zip</samp> in the <samp>${dist}</samp> directory. If <samp>manual.zip</samp>
|
|
|
|
|
doesn't exist, it is created; otherwise it is updated with the new/changed files.</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
<pre>
|
|
|
|
|
<zip destfile="${dist}/manual.zip"
|
|
|
|
|
basedir="htdocs/manual"
|
|
|
|
|
update="true"/></pre>
|
2018-05-15 09:51:58 +02:00
|
|
|
|
|
|
|
|
<p>Zip all files in the <samp>htdocs/manual</samp> directory. Files in the
|
|
|
|
|
directory <samp>mydocs</samp>, or files with the name <samp>todo.html</samp> are excluded.</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
<pre>
|
|
|
|
|
<zip destfile="${dist}/manual.zip"
|
|
|
|
|
basedir="htdocs/manual"
|
|
|
|
|
excludes="mydocs/**, **/todo.html"/></pre>
|
2018-05-15 09:51:58 +02:00
|
|
|
|
|
|
|
|
<p>Zip all files in the <samp>htdocs/manual</samp> directory. Only <samp>html</samp> files under the
|
|
|
|
|
directory <samp>api</samp> are zipped, and files with the name <samp>todo.html</samp> are
|
|
|
|
|
excluded.</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
<pre>
|
|
|
|
|
<zip destfile="${dist}/manual.zip"
|
|
|
|
|
basedir="htdocs/manual"
|
|
|
|
|
includes="api/**/*.html"
|
|
|
|
|
excludes="**/todo.html"/></pre>
|
2018-05-15 09:51:58 +02:00
|
|
|
|
|
|
|
|
<p>Zip all files in the <samp>htdocs/manual</samp> directory, and also add the
|
|
|
|
|
file <samp>ChangeLog.txt</samp> in the current directory. <samp>ChangeLog.txt</samp> will be added
|
|
|
|
|
to the top of the ZIP file, just as if it had been located
|
|
|
|
|
at <samp>htdocs/manual/ChangeLog.txt</samp>.</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
<pre>
|
|
|
|
|
<zip destfile="${dist}/manual.zip">
|
|
|
|
|
<fileset dir="htdocs/manual"/>
|
|
|
|
|
<fileset dir="." includes="ChangeLog.txt"/>
|
|
|
|
|
</zip></pre>
|
2018-05-15 09:51:58 +02:00
|
|
|
|
|
|
|
|
<p>Zip all files in the <samp>htdocs/manual</samp> directory into the <samp>docs/user-guide</samp>
|
|
|
|
|
directory in the archive, adds the file <samp>ChangeLog27.txt</samp> in the current directory
|
|
|
|
|
as <samp>docs/ChangeLog.txt</samp>, and includes all the <samp>html</samp> files
|
|
|
|
|
in <samp>examples.zip</samp> under <samp>docs/examples</samp>.</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
<pre>
|
|
|
|
|
<zip destfile="${dist}/manual.zip">
|
|
|
|
|
<zipfileset dir="htdocs/manual" prefix="docs/user-guide"/>
|
|
|
|
|
<zipfileset dir="." includes="ChangeLog27.txt" fullpath="docs/ChangeLog.txt"/>
|
|
|
|
|
<zipfileset src="examples.zip" includes="**/*.html" prefix="docs/examples"/>
|
|
|
|
|
</zip></pre>
|
2018-05-15 09:51:58 +02:00
|
|
|
<p>The archive might end up containing the files:</p>
|
2018-02-28 07:58:59 +01:00
|
|
|
<pre>
|
|
|
|
|
docs/user-guide/html/index.html
|
2001-02-13 12:32:01 +00:00
|
|
|
docs/ChangeLog.txt
|
2018-02-28 07:58:59 +01:00
|
|
|
docs/examples/index.html</pre>
|
2018-05-15 09:51:58 +02:00
|
|
|
|
|
|
|
|
<p>Zip all files in the <samp>htdocs/manual</samp> directory into the <samp>docs/user-guide</samp>
|
|
|
|
|
directory in the archive and include all the files in any file that
|
|
|
|
|
matches <samp>examples*.zip</samp>, such as all files within <samp>examples1.zip</samp>
|
|
|
|
|
or <samp>examples_for_brian.zip</samp>.</p>
|
2002-03-03 06:52:07 +00:00
|
|
|
<pre>
|
2018-02-28 07:58:59 +01:00
|
|
|
<zip destfile="${dist}/manual.zip">
|
|
|
|
|
<zipfileset dir="htdocs/manual" prefix="docs/user-guide"/>
|
|
|
|
|
<zipgroupfileset dir="." includes="examples*.zip"/>
|
|
|
|
|
</zip></pre>
|
2018-05-15 09:51:58 +02:00
|
|
|
<p>The same can be achieved with</p>
|
2008-11-28 16:05:23 +00:00
|
|
|
<pre>
|
2018-02-28 07:58:59 +01:00
|
|
|
<zip destfile="${dist}/manual.zip">
|
|
|
|
|
<mappedresources>
|
|
|
|
|
<fileset dir="htdocs/manual"/>
|
|
|
|
|
<globmapper from="*" to="docs/user-guide/*"/>
|
|
|
|
|
</mappedresources>
|
|
|
|
|
<archives>
|
|
|
|
|
<zips>
|
|
|
|
|
<fileset dir="." includes="examples*.zip"/>
|
|
|
|
|
</zips>
|
|
|
|
|
</archives>
|
|
|
|
|
</zip></pre>
|
|
|
|
|
|
2018-05-15 09:51:58 +02:00
|
|
|
<p>Re-package 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>
|
2005-11-29 04:51:01 +00:00
|
|
|
<pre>
|
2013-08-24 05:55:38 +00:00
|
|
|
<zip destfile="release.zip">
|
2005-11-29 04:51:01 +00:00
|
|
|
<tarfileset src="release.tar"/>
|
2018-02-28 07:58:59 +01:00
|
|
|
</zip></pre>
|
2005-11-29 04:51:01 +00:00
|
|
|
|
2001-02-13 12:32:01 +00:00
|
|
|
</body>
|
|
|
|
|
</html>
|
