Author: bodewig
Date: Wed Sep 9 10:10:14 2009
New Revision: 812870
URL: http://svn.apache.org/viewvc?rev=812870&view=rev
Log:
document filesets
Added:
ant/sandbox/antlibs/compress/trunk/docs/fileset.html (contents, props
changed)
- copied, changed from r812756,
ant/core/trunk/docs/manual/CoreTypes/tarfileset.html
Copied: ant/sandbox/antlibs/compress/trunk/docs/fileset.html (from r812756,
ant/core/trunk/docs/manual/CoreTypes/tarfileset.html)
URL:
http://svn.apache.org/viewvc/ant/sandbox/antlibs/compress/trunk/docs/fileset.html?p2=ant/sandbox/antlibs/compress/trunk/docs/fileset.html&p1=ant/core/trunk/docs/manual/CoreTypes/tarfileset.html&r1=812756&r2=812870&rev=812870&view=diff
==============================================================================
--- ant/core/trunk/docs/manual/CoreTypes/tarfileset.html (original)
+++ ant/sandbox/antlibs/compress/trunk/docs/fileset.html Wed Sep 9 10:10:14
2009
@@ -18,39 +18,38 @@
<html>
<head>
<meta http-equiv="Content-Language" content="en-us">
- <link rel="stylesheet" type="text/css" href="../stylesheets/style.css">
-<title>TarFileSet Type</title>
+ <link rel="stylesheet" type="text/css" href="style.css">
+<title>Archive FileSets</title>
</head>
<body>
-<h2><a name="fileset">TarFileSet</a></h2>
-<p><em>TarFileSet</em> has been added as a stand-alone type in Ant
-1.7.</p>
+<h2><a name="archivefileset">Archive FileSets</h2>
-<p>A <code><tarfileset></code> is a special form of a <code><<a
- href="fileset.html">fileset</a>></code> which can behave in 2
-different ways : <br>
+<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><<a
href="http://ant.apache.org/manual/CoreTypes/fileset.html";>fileset</a>></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
- tarfileset is populated with tar entries found in the file <span
+ 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 tarfileset is populated with filesystem files found under <span
+is used, the fileset is populated with filesystem files found under <span
style="font-style: italic;">dir</span>.<br>
</li>
</ul>
-<p><code><tarfileset></code> supports all attributes of <code><<a
- href="fileset.html">fileset</a>></code>
+
+<p>Each archive fileset supports all attributes of <code><<a
+
href="http://ant.apache.org/manual/CoreTypes/fileset.html";>fileset</a>></code>
in addition to those listed below.<br>
</p>
-<p>A tarfileset can be defined with the <span style="font-style:
-italic;">id </span>attribute and referred to with the <span
-style="font-style: italic;">refid</span> attribute. This is also true
-for tarfileset which has been added in Ant 1.7.<br>
-</p>
+
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tbody>
@@ -73,9 +72,9 @@
</tr>
<tr>
<td valign="top">src</td>
- <td valign="top">may be used in place of the <i>dir</i> attribute
- to specify a tar file whose contents will be extracted and included
-in the archive.</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>
@@ -93,6 +92,143 @@
<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>
+ </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><arfileset></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>
+ <copy todir="some-dir">
+ <cmp:arfileset xmlns:cmp="antlib:org.apache.ant.compress">
+ <file file="some-archive.ar"/>
+ </cmp:arfileset>
+ </copy>
+</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="cpiofileset">CpioFileSet</a></h2>
+
+<p>A <code><cpiofileset></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>
+ </tbody>
+</table>
+
+<h4>Examples</h4>
+<blockquote>
+<pre>
+ <copy todir="some-dir">
+ <cmp:cpiofileset xmlns:cmp="antlib:org.apache.ant.compress">
+ <file file="some-archive.cpio"/>
+ </cmp:cpiofileset>
+ </copy>
+</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="tarfileset">TarFileSet</a></h2>
+
+<p>A <code><tarfileset></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>
@@ -117,48 +253,21 @@
</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.
- <em>Since Ant 1.8.0</em>
- </td>
- <td valign="top" align="center">No</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>
-
-<p>Please note that currently only the <a
-href="../CoreTasks/tar.html">tar</a> task uses the permission and
-ownership attributes.</p>
-
-<h3>Parameters specified as nested elements</h3>
-
-<h4>any <a href="resources.html">resource</a> or single element
-resource collection</h4>
-
-<p>The specified resource will be used as src.</p>
<h4>Examples</h4>
<blockquote>
<pre>
<copy todir="some-dir">
- <tarfileset includes="lib/**">
- <bzip2resource>
+ <cmp:tarfileset xmlns:cmp="antlib:org.apache.ant.compress"
+ includes="lib/**">
+ <cmp:bzip2resource>
<url url="http://example.org/dist/some-archive.tar.bz2"/>
- </bzip2resource>
- </tarfileset>
+ </cmp:bzip2resource>
+ </cmp:tarfileset>
</copy>
- </pre></blockquote>
+</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
@@ -167,5 +276,53 @@
directory, no files get overwritten unless they are out-of-date.</p>
+<h2><a name="zipfileset">ZipFileSet</a></h2>
+
+<p>A <code><zipfileset></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>
+ <cmp:zip destfile="${dist}/manual.zip"
xmlns:cmp="antlib:org.apache.ant.compress">
+ <cmp:zipfileset dir="htdocs/manual" prefix="docs/user-guide"/>
+ <cmp:zipfileset dir="." includes="ChangeLog27.txt"
fullpath="docs/ChangeLog.txt"/>
+ <cmp:zipfileset src="examples.zip" includes="**/*.html"
prefix="docs/examples"/>
+ </cmp: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>
+<blockquote>
+ <code>docs/user-guide/html/index.html<br>
+docs/ChangeLog.txt<br>
+docs/examples/index.html<br>
+ </code>
+</blockquote>
+
</body>
</html>
Propchange: ant/sandbox/antlibs/compress/trunk/docs/fileset.html
------------------------------------------------------------------------------
svn:eol-style = native
Propchange: ant/sandbox/antlibs/compress/trunk/docs/fileset.html
------------------------------------------------------------------------------
svn:mergeinfo =
