blob: 53a8d59ecb940d9ceaead8ad14f6fafb443827aa [file] [log] [blame]
<!--
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.
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
<link rel="stylesheet" type="text/css" href="style.css">
<title>Archive FileSets</title>
</head>
<body>
<h2><a name="archivefileset">Archive FileSets</h2>
<p>For each of the supported archiving formats there is a
correspondig <code>fileset</code> resource collection.</p>
<p>Such a <code>fileset</code> is a special form of
a <code>&lt;<a href="http://ant.apache.org/manual/CoreTypes/fileset.html">fileset</a>&gt;</code>
which can behave in 2 different ways : <br>
</p>
<ul>
<li>When the <span style="font-style: italic;">src</span> attribute
is used - or a nested resource collection has been specified, the
fileset is populated with archive entries found in the file <span
style="font-style: italic;">src</span>.<br>
</li>
<li>When the <span style="font-style: italic;">dir</span> attribute
is used, the fileset is populated with filesystem files found under <span
style="font-style: italic;">dir</span>.<br>
</li>
</ul>
<p>Each archive fileset supports all attributes of <code>&lt;<a
href="http://ant.apache.org/manual/CoreTypes/fileset.html">fileset</a>&gt;</code>
in addition to those listed below.<br>
</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tbody>
<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 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.</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.</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">erroronmissingarchive</td>
<td valign="top">
Specify what happens if the archive does not exist.
If true, a build error will happen; if false, the fileset
will be ignored/empty.
Defaults to true.
</td>
<td valign="top" align="center">No</td>
</tr>
<tr>
<td valign="top">skipUnreadableEntries</td>
<td valign="top">Sometimes archives may contain entries that use
features not (yet) supported by Apache Commons Compress,
encryption for example. Trying to read from such an archive will
normally lead to an error. Sometimes Commons Compress can
signal it doesn't know how to handle an entry and if you set
<code>skipUnreadableEntries</code> to true, the Compress Antlib
will simply skip those entries, avoiding the error.
<br/><em>since Compress Antlib 1.1</em></td>
<td valign="top" align="center">No, defaults to false</td>
</tr>
</tbody>
</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 archive for inclusion in the
archive as with the <i>dir</i> attribute.</p>
<h3>Parameters specified as nested elements</h3>
<h4>any <a href="http://ant.apache.org/manual/CoreTypes/resources.html">resource</a> or single element
resource collection</h4>
<p>The specified resource will be used as src.</p>
<h2><a name="arfileset">ArFileSet</a></h2>
<p>A <code>&lt;arfileset&gt;</code> is
an <a href="#archivefileset">archive fileset</a> with attributes to
specify user and group ids in addition to the parameters
specified above.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tbody>
<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">uid</td>
<td valign="top">The user identifier (UID) for the ar entry. This is an integer value
and is not the same as the username.
</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">gid</td>
<td valign="top">The group identifier (GID) for the ar entry.
</td>
<td align="center" valign="top">No</td>
</tr>
</tbody>
</table>
<h4>Examples</h4>
<blockquote>
<pre>
&lt;copy todir="some-dir"&gt;
&lt;cmp:arfileset xmlns:cmp="antlib:org.apache.ant.compress"&gt;
&lt;file file="some-archive.ar"/&gt;
&lt;/cmp:arfileset&gt;
&lt;/copy&gt;
</pre></blockquote>
<p>extracts some-archive.ar, uncompresses and extracts it on the fly
and copies the contents of it into some-dir. File timestamps will
be compared between the archive's entries and files inside the
target directory, no files get overwritten unless they are
out-of-date.</p>
<h2><a name="arjfileset">ArjFileSet</a></h2>
<p><em>Since Apache Compress Antlib 1.3</em>.</p>
<p>A <code>&lt;arjfileset&gt;</code> is
an <a href="#archivefileset">archive fileset</a>.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tbody>
<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">encoding</td>
<td valign="top">
The character encoding that has been used for filenames
inside the arj file. 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>.<br>
Defaults <code>native-encoding</code> which is the magic value for
the platform's default character encoding.<br/>
<em>since Compress Antlib 1.3</em></td>
<td align="center" valign="top">No</td>
</tr>
</tbody>
</table>
<h4>Examples</h4>
<blockquote>
<pre>
&lt;copy todir="some-dir"&gt;
&lt;cmp:arjfileset xmlns:cmp="antlib:org.apache.ant.compress"&gt;
&lt;file file="some-archive.arj"/&gt;
&lt;/cmp:arjfileset&gt;
&lt;/copy&gt;
</pre></blockquote>
<p>extracts some-archive.arj
and copies the contents of it into some-dir. File timestamps will
be compared between the archive's entries and files inside the
target directory, no files get overwritten unless they are
out-of-date.</p>
<h2><a name="cpiofileset">CpioFileSet</a></h2>
<p>A <code>&lt;cpiofileset&gt;</code> is
an <a href="#archivefileset">archive fileset</a> with attributes to
specify user and group ids in addition to the parameters
specified above.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tbody>
<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">uid</td>
<td valign="top">The user identifier (UID) for the cpio entry. This is an integer value
and is not the same as the username.
</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">gid</td>
<td valign="top">The group identifier (GID) for the cpio entry.
</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">encoding</td>
<td valign="top">
The character encoding that has been used for filenames
inside the cpio file. 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>.<br>
Defaults <code>native-encoding</code> which is the magic value for
the platform's default character encoding.<br/>
<em>since Compress Antlib 1.3</em></td>
<td align="center" valign="top">No</td>
</tr>
</tbody>
</table>
<h4>Examples</h4>
<blockquote>
<pre>
&lt;copy todir="some-dir"&gt;
&lt;cmp:cpiofileset xmlns:cmp="antlib:org.apache.ant.compress"&gt;
&lt;file file="some-archive.cpio"/&gt;
&lt;/cmp:cpiofileset&gt;
&lt;/copy&gt;
</pre></blockquote>
<p>extracts some-archive.cpio, uncompresses and extracts it on the fly
and copies the contents of it into some-dir. File timestamps will
be compared between the archive's entries and files inside the
target directory, no files get overwritten unless they are
out-of-date.</p>
<h2><a name="dumpfileset">DumpFileSet</a></h2>
<p><em>Since Apache Compress Antlib 1.1</em>.</p>
<p>A <code>&lt;dumpfileset&gt;</code> is
an <a href="#archivefileset">archive fileset</a> with attributes to
specify user and group ids in addition to the parameters
specified above.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tbody>
<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">uid</td>
<td valign="top">The user identifier (UID) for the dump entry. This is an integer value
and is not the same as the username.
</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">gid</td>
<td valign="top">The group identifier (GID) for the dump entry.
</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">encoding</td>
<td valign="top">
The character encoding that has been used for filenames
inside the dump file. 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>.<br>
Defaults <code>native-encoding</code> which is the magic value for
the platform's default character encoding.<br/>
<em>since Compress Antlib 1.3</em></td>
<td align="center" valign="top">No</td>
</tr>
</tbody>
</table>
<h4>Examples</h4>
<blockquote>
<pre>
&lt;copy todir="some-dir"&gt;
&lt;cmp:dumpfileset xmlns:cmp="antlib:org.apache.ant.compress"&gt;
&lt;file file="some-archive.dump"/&gt;
&lt;/cmp:dumpfileset&gt;
&lt;/copy&gt;
</pre></blockquote>
<p>extracts some-archive.dump, uncompresses and extracts it on the fly
and copies the contents of it into some-dir. File timestamps will
be compared between the archive's entries and files inside the
target directory, no files get overwritten unless they are
out-of-date.</p>
<h2><a name="sevenzfileset">SevenZFileSet</a></h2>
<p><em>Since Apache Compress Antlib 1.3</em>.</p>
<p>A <code>&lt;sevenzfileset&gt;</code> is
an <a href="#archivefileset">archive fileset</a> for 7z archives.</p>
<h2><a name="tarfileset">TarFileSet</a></h2>
<p>A <code>&lt;tarfileset&gt;</code> is
an <a href="#archivefileset">archive fileset</a> with attributes to
specify user and group ownership in addition to the parameters
specified above.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tbody>
<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">username</td>
<td valign="top">The username for the tar entry. This is not the same as the UID.
</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">group</td>
<td valign="top">The groupname for the tar entry. This is not the same as the GID.
</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">uid</td>
<td valign="top">The user identifier (UID) for the tar entry. This is an integer value
and is not the same as the username.
</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">gid</td>
<td valign="top">The group identifier (GID) for the tar entry.
</td>
<td align="center" valign="top">No</td>
</tr>
<tr>
<td valign="top">encoding</td>
<td valign="top">
The character encoding that has been used for filenames
inside the tar file. 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>.<br>
Defaults <code>native-encoding</code> which is the magic value for
the platform's default character encoding.<br/>
<em>since Compress Antlib 1.2</em></td>
<td align="center" valign="top">No</td>
</tr>
</tbody>
</table>
<h4>Examples</h4>
<blockquote>
<pre>
&lt;copy todir="some-dir"&gt;
&lt;cmp:tarfileset xmlns:cmp="antlib:org.apache.ant.compress"
includes="lib/**"&gt;
&lt;cmp:bzip2resource&gt;
&lt;url url="http://example.org/dist/some-archive.tar.bz2"/&gt;
&lt;/cmp:bzip2resource&gt;
&lt;/cmp:tarfileset&gt;
&lt;/copy&gt;
</pre></blockquote>
<p>downloads the archive some-archive.tar.bz2, uncompresses and
extracts it on the fly, copies the contents of the lib directory into
some-dir and discards the rest of the archive. File timestamps will
be compared between the archive's entries and files inside the target
directory, no files get overwritten unless they are out-of-date.</p>
<h2><a name="zipfileset">ZipFileSet</a></h2>
<p>A <code>&lt;zipfileset&gt;</code> is
an <a href="#archivefileset">archive fileset</a> with an attribute
to specify the encoding of filenames inside the archive in addition
to the parameters specified above.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tbody>
<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">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/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>.
Defaults to the platform's default character encoding.</td>
<td align="center" valign="top">No</td>
</tr>
</tbody>
</table>
<h4>Examples</h4>
<pre>
&lt;cmp:zip destfile="${dist}/manual.zip" xmlns:cmp="antlib:org.apache.ant.compress"&gt;
&lt;cmp:zipfileset dir="htdocs/manual" prefix="docs/user-guide"/&gt;
&lt;cmp:zipfileset dir="." includes="ChangeLog27.txt" fullpath="docs/ChangeLog.txt"/&gt;
&lt;cmp:zipfileset src="examples.zip" includes="**/*.html" prefix="docs/examples"/&gt;
&lt;/cmp: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>
<blockquote>
<code>docs/user-guide/html/index.html<br>
docs/ChangeLog.txt<br>
docs/examples/index.html<br>
</code>
</blockquote>
</body>
</html>