mirror of
https://github.com/apache/ant.git
synced 2025-05-15 20:45:11 +00:00
e967d77e02
PR: 5020 Reported By: jesse.glick@netbeans.com (Jesse Glick) git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@271131 13f79535-47bb-0310-9956-ffa450edef68
198 lines
10 KiB
HTML
198 lines
10 KiB
HTML
<html>
|
|
|
|
<head>
|
|
<meta http-equiv="Content-Language" content="en-us">
|
|
<title>AZip 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 <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>
|
|
<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">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 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 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.</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>zipfileset</h4>
|
|
<p>A <code><zipfileset></code> has three additional attributes: <i>prefix</i>, <i>fullpath</i>, and <i>src</i>. The
|
|
<i>prefix</i> and <i>fullpath</i> attributes modify the location of the files when they are placed
|
|
inside the archive. If the <i>prefix</i> attribute is set, all files in the fileset are prefixed
|
|
with that path in the archive. If the <i>fullpath</i> attribute is set, the file described by the fileset is placed at that
|
|
exact location in the archive. (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.) The <i>src</i> attribute
|
|
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. As with directories, include and exclude patterns may be used to specify a subset of the zip file
|
|
for inclusion in the archive.</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>
|
|
<hr>
|
|
<p align="center">Copyright © 2001-2002 Apache Software Foundation. All rights
|
|
Reserved.</p>
|
|
|
|
</body>
|
|
</html>
|
|
|