<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<title>Zip Task</title>
</head>
<body>
<h2><a name="zip">Zip</a></h2>
<h3>Description</h3>
<p>Creates a zipfile.</p>
<p>The <i>basedir</i> attribute is the reference directory from where to zip.</p>
<p>Note that file permissions will not be stored in the resulting zipfile.</p>
<p>It is possible to refine the set of files that are being zipped. This can be
done with the <i>includes</i>, <i>includesfile</i>, <i>excludes</i>, <i>excludesfile</i> and <i>defaultexcludes</i>
attributes. With the <i>includes</i> or <i>includesfile</i> attribute you specify the files you want to
have included by using patterns. The <i>exclude</i> or <i>excludesfile</i> attribute is used to specify
the files you want to have excluded. This is also done with patterns. And
finally with the <i>defaultexcludes</i> 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
inclusion/exclusion of files works, and how to write patterns. </p>
<p>This task forms an implicit <a href="../CoreTypes/fileset.html">FileSet</a> and
supports all attributes of <code><fileset></code>
(<code>dir</code> becomes <code>basedir</code>) 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 <code>basedir</code> is optional; the implicit file set is <i>only used</i>
if <code>basedir</code> is set. You may use any mixture of the implicit file set
(with <code>basedir</code> set, and optional attributes like <code>includes</code>
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 <i>within</i> each fileset. The Zip task and its derivatives know a special form of a fileset named zipfileset 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 <i>src</i> attribute of any nested filesets
or by using the special nested fileset <i>zipgroupfileset</i>.</p>
<p>The <code>update</code> parameter controls what happens if the
ZIP file already exists. When set to <code>yes</code>, the ZIP file is
updated with the files specified. (New files are added; old files are
replaced with the new versions.) When set to <code>no</code> (the
default) the ZIP file is overwritten.</p>
<p>The <code>whenempty</code> parameter controls what happens when no files match.
If <code>skip</code> (the default), the ZIP is not created and a warning is issued.
If <code>fail</code>, the ZIP is not created and the build is halted with an error.
If <code>create</code>, 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 the platform's default 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 encoding attribute
and set it to UTF8 to create zip files that can safely be read by
Java.</p>
<p>Starting with Ant 1.6, <zip> can store Unix permissions
inside the archive (see description of the filemode and dirmode
attributes for <a href="#zipfileset"><zipfileset></a>).
Unfortunately there is no portable way to store these permissions.
Ant uses the algorithm used by <a href="http://www.info-zip.org">Info-Zip's</a>
implementation of the zip and unzip commands - these are the default
versions of zip and unzip for many Unix and Unix-like systems.</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 valign="top" align="center"><b>Required</b></td>
</tr>
<tr>
<td valign="top">destfile</td>
<td valign="top">the zip-file to create.</td>
<td align="center" valign="top">Yes</td>
</tr>
<tr>
<td valign="top">zipfile</td>
<td valign="top">the <i>deprecated</i> old name of destfile.</td>
<td align="center" valign="top">Yes</td>
</tr>
<tr>
<td valign="top">basedir</td>
<td valign="top">the directory from which to zip the files.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">compress</td>
<td valign="top">Not only store data but also compress them, defaults to true</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">encoding</td>
<td valign="top">The character encoding to use for filenames
inside the zip file. For a list of possible values see <a
href="http://java.sun.com/products/jdk/1.2/docs/guide/internat/encoding.doc.html">http://java.sun.com/products/jdk/1.2/docs/guide/internat/encoding.doc.html</a>.
Defaults to the platform's default character encoding.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">filesonly</td>
<td valign="top">Store only file entries, defaults to false</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">includes</td>
<td valign="top">comma- or space-separated list of patterns of files that must be
included. All files are included when omitted.</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">includesfile</td>
<td valign="top">the name of a file. Each line of this file is
taken to be an include pattern</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">excludes</td>
<td valign="top">comma- or space-separated list of patterns of files that must be
excluded. No files (except default excludes) are excluded when omitted.</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">excludesfile</td>
<td valign="top">the name of a file. Each line of this file is
taken to be an exclude pattern</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">defaultexcludes</td>
<td valign="top">indicates whether default excludes should be used or not
("yes"/"no"). Default excludes are used when omitted.</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">update</td>
<td valign="top">indicates whether to update or overwrite
the destination file if it already exists.</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", "skip", and "create". Default is "skip".</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">duplicate</td>
<td valign="top">behavior when a duplicate file is found. Valid values are "add", "preserve", and "fail". The default value is "add". </td>
<td valign="top" align="center">No</td>
</tr>
</table>
<h3>Parameters specified as nested elements</h3>
<h4>fileset</h4>
<p>The zip task supports any number of nested <a
href="../CoreTypes/fileset.html"><code><fileset></code></a> elements to specify
the files to be included in the archive.</p>
<h4><a name="zipfileset">zipfileset</a></h4>
<p>A <code><zipfileset></code> is a special form of a
<code><fileset></code> that adds some extra functionality. It
supports all attributes of <code><fileset></code> in addition to
those listed below.</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 valign="top" align="center"><b>Required</b></td>
</tr>
<tr>
<td valign="top">prefix</td>
<td valign="top">all files in the fileset are prefixed with that
path in the archive.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">fullpath</td>
<td valign="top">the file described by the fileset is placed at
that exact location in the archive.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">src</td>
<td valign="top">may be used in place of the <i>dir</i> attribute
to specify a zip file whose contents will be extracted and
included in the archive.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">filemode</td>
<td valign="top">A 3 digit octal string, specify the user, group
and other modes in the standard Unix fashion. Only applies to
plain files. Default is 644. <em>since Ant 1.6</em>.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">dirmode</td>
<td valign="top">A 3 digit octal string, specify the user, group
and other modes in the standard Unix fashion. Only applies to
directories. Default is 755. <em>since Ant 1.6</em>.</td>
<td align="center" valign="top">No</td>
</tr>
</table>
<p>The <i>fullpath</i> attribute can only be set for filesets that
represent a single file. The <i>prefix</i> and <i>fullpath</i>
attributes cannot both be set on the same fileset.</p>
<p>When using the <i>src</i> attribute, include and exclude patterns
may be used to specify a subset of the zip file for inclusion in the
archive as with the <i>dir</i> attribute.</p>
<h4>zipgroupfileset</h4>
<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 <i>zipfileset src</i> files are added.</p>
<h3>Examples</h3>
<pre> <zip destfile="${dist}/manual.zip"
basedir="htdocs/manual"
/></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> <zip destfile="${dist}/manual.zip"
basedir="htdocs/manual"
update="true"
/></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> <zip destfile="${dist}/manual.zip"
basedir="htdocs/manual"
excludes="mydocs/**, **/todo.html"
/></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> <zip destfile="${dist}/manual.zip"
basedir="htdocs/manual"
includes="api/**/*.html"
excludes="**/todo.html"
/></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> <zip destfile="${dist}/manual.zip">
<fileset dir="htdocs/manual"/>
<fileset dir="." includes="ChangeLog.txt"/>
</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> <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>
<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><code> docs/user-guide/html/index.html
docs/ChangeLog.txt
docs/examples/index.html
</code></pre>
<p>
The code
<pre>
<zip destfile="${dist}/manual.zip">
<zipfileset dir="htdocs/manual" prefix="docs/user-guide"/>
<zipgroupfileset dir="." includes="examples*.zip"/>
</zip></pre>
</pre>
<p>
<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>.
<hr>
<p align="center">Copyright © 2000-2002 Apache Software Foundation. All rights
Reserved.</p>
</body>
</html>