youys
/
ant

<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>&lt;fileset&gt;</code>
(<code>dir</code> becomes <code>basedir</code>) as well as the nested
<code>&lt;include&gt;</code>, <code>&lt;exclude&gt;</code> and
<code>&lt;patternset&gt;</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>&lt;include&gt;</code>); explicit nested
<code>&lt;fileset&gt;</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, &lt;zip&gt; can store Unix permissions
inside the archive (see description of the filemode and dirmode
attributes for <a href="#zipfileset">&lt;zipfileset&gt;</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
      (&quot;yes&quot;/&quot;no&quot;). 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 &quot;fail&quot;, &quot;skip&quot;, and &quot;create&quot;.  Default is &quot;skip&quot;.</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 &quot;add&quot;, &quot;preserve&quot;, and &quot;fail&quot;. The default value is &quot;add&quot;.  </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>&lt;fileset&gt;</code></a> elements to specify
the files to be included in the archive.</p>

<h4><a name="zipfileset">zipfileset</a></h4>

<p>A <code>&lt;zipfileset&gt;</code> is a special form of a
<code>&lt;fileset&gt;</code> that adds some extra functionality.  It
supports all attributes of <code>&lt;fileset&gt;</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>&lt;zipgroupfileset&gt;</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>  &lt;zip destfile=&quot;${dist}/manual.zip&quot;
       basedir=&quot;htdocs/manual&quot;
  /&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;zip destfile=&quot;${dist}/manual.zip&quot;
       basedir=&quot;htdocs/manual&quot;
       update=&quot;true&quot;
  /&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;zip destfile=&quot;${dist}/manual.zip&quot;
       basedir=&quot;htdocs/manual&quot;
       excludes=&quot;mydocs/**, **/todo.html&quot;
  /&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;zip destfile=&quot;${dist}/manual.zip&quot;
       basedir=&quot;htdocs/manual&quot;
       includes=&quot;api/**/*.html&quot;
       excludes=&quot;**/todo.html&quot;
  /&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;zip destfile=&quot;${dist}/manual.zip&quot;&gt;
    &lt;fileset dir=&quot;htdocs/manual&quot;/&gt;
    &lt;fileset dir=&quot;.&quot; includes=&quot;ChangeLog.txt&quot;/&gt;
  &lt;/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;zip destfile=&quot;${dist}/manual.zip&quot;&gt;
    &lt;zipfileset dir=&quot;htdocs/manual&quot; prefix=&quot;docs/user-guide&quot;/&gt;
    &lt;zipfileset dir=&quot;.&quot; includes=&quot;ChangeLog27.txt&quot; fullpath=&quot;docs/ChangeLog.txt&quot;/&gt;
    &lt;zipfileset src=&quot;examples.zip&quot; includes=&quot;**/*.html&quot; prefix=&quot;docs/examples&quot;/&gt;
  &lt;/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><code>    docs/user-guide/html/index.html
    docs/ChangeLog.txt
    docs/examples/index.html
</code></pre>
<p>
The code
<pre>
  &lt;zip destfile=&quot;${dist}/manual.zip&quot;&gt;
    &lt;zipfileset dir=&quot;htdocs/manual&quot; prefix=&quot;docs/user-guide&quot;/&gt;
    &lt;zipgroupfileset dir=&quot;.&quot; includes=&quot;examples*.zip&quot;/&gt;
  &lt;/zip&gt;</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 &copy; 2000-2002 Apache Software Foundation. All rights
Reserved.</p>

</body>
</html>