donaldp 00/12/12 17:33:26
Modified: docs index.html
Log:
Patch to unify handling of prefix filesets between war/jar/zip.
It also removes a number of small errors in zip task.
Deprecated <prefixedfileset> element of war in favour of normal <fileset>
element in zip
Submitted By: "Rosen, Alex" <[EMAIL PROTECTED]>
Revision Changes Path
1.171 +39 -76 jakarta-ant/docs/index.html
Index: index.html
===================================================================
RCS file: /home/cvs/jakarta-ant/docs/index.html,v
retrieving revision 1.170
retrieving revision 1.171
diff -u -r1.170 -r1.171
--- index.html 2000/12/09 06:16:54 1.170
+++ index.html 2000/12/13 01:33:25 1.171
@@ -29,7 +29,7 @@
</ul>
<p>Version: @VERSION@</p>
-<p>$Id: index.html,v 1.170 2000/12/09 06:16:54 jon Exp $</p>
+<p>$Id: index.html,v 1.171 2000/12/13 01:33:25 donaldp Exp $</p>
<hr>
<h2>Table of Contents</h2>
@@ -2725,6 +2725,11 @@
If <code>create</code> (the default), the JAR is created anyway with only a
manifest.
If <code>skip</code>, the JAR is not created and a warning is issued.
If <code>fail</code>, the JAR is not created and the build is halted with an
error.
+<p>(The Jar task is a shortcut for specifying the manifest file of a JAR
file.
+The same thing can be accomplished by using the <i>fullpath</i>
+attribute of the filesets in a Zip task. The one difference is that if the
+<i>manifest</i> attribute is not specified, the Jar task will
+include an empty one for you.)</p>
</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
@@ -2791,13 +2796,13 @@
</table>
<h3>Examples</h3>
<pre> <jar jarfile="${dist}/lib/app.jar"
basedir="${build}/classes" /></pre>
-<p>jars all files in the <code>${build}/classes</code> directory in a file
+<p>jars all files in the <code>${build}/classes</code> directory into a file
called <code>app.jar</code> in the <code>${dist}/lib</code> directory.</p>
<pre> <jar jarfile="${dist}/lib/app.jar"
basedir="${build}/classes"
excludes="**/Test.class"
/></pre>
-<p>jars all files in the <code>${build}/classes</code> directory in a file
+<p>jars all files in the <code>${build}/classes</code> directory into a file
called <code>app.jar</code> in the <code>${dist}/lib</code> directory. Files
with the name <code>Test.class</code> are excluded.</p>
<pre> <jar jarfile="${dist}/lib/app.jar"
@@ -2805,7 +2810,7 @@
includes="mypackage/test/**"
excludes="**/Test.class"
/></pre>
-<p>jars all files in the <code>${build}/classes</code> directory in a file
+<p>jars all files in the <code>${build}/classes</code> directory into a file
called <code>app.jar</code> in the <code>${dist}/lib</code> directory. Only
files under the directory <code>mypackage/test</code> are used, and files
with
the name <code>Test.class</code> are excluded.</p>
@@ -2816,7 +2821,7 @@
<fileset dir="${src}/resources"/>
</jar></pre>
<p>jars all files in the <code>${build}/classes</code> directory and also
-in the <code>${src}/resources</code> directory together in a file
+in the <code>${src}/resources</code> directory together into a file
called <code>app.jar</code> in the <code>${dist}/lib</code> directory.
Files with the name <code>Test.class</code> are excluded.
If there are files such as
<code>${build}/classes/mypackage/MyClass.class</code>
@@ -4434,14 +4439,14 @@
<h3>Examples</h3>
<pre> <tar tarfile="${dist}/manual.tar"
basedir="htdocs/manual" />
<gzip zipfile="${dist}/manual.tar.gz"
src="${dist}/manual.tar" /></pre>
-<p>tars all files in the <code>htdocs/manual</code> directory in a file
called <code>manual.tar</code>
+<p>tars all files in the <code>htdocs/manual</code> directory into a file
called <code>manual.tar</code>
in the <code>${dist}</code> directory, then applies the gzip task to
compress
it.</p>
<pre> <tar tarfile="${dist}/manual.tar"
basedir="htdocs/manual"
excludes="mydocs/**, **/todo.html"
/></pre>
-<p>tars all files in the <code>htdocs/manual</code> directory in a file
called <code>manual.tar</code>
+<p>tars all files in the <code>htdocs/manual</code> directory into a file
called <code>manual.tar</code>
in the <code>${dist}</code> directory. Files in the directory
<code>mydocs</code>,
or files with the name <code>todo.html</code> are excluded.</p>
<hr>
@@ -4779,10 +4784,10 @@
<p>An extension of the <a href="#jar">Jar</a> task with special
treatment for files that should end up in the
<code>WEB-INF/lib</code>, <code>WEB-INF/classes</code> or
-<code>WEB-INF</code> directories of the Web Application Archive. It
-also gives you more control over where your files end up in the
-archive by means of its nested <code>prefixedfileset</code>
-element.</p>
+<code>WEB-INF</code> directories of the Web Application Archive.
+<p>(The War task is a shortcut for specifying the particular layout of a WAR
file.
+The same thing can be accomplished by using the <i>prefix</i> and
<i>fullpath</i>
+attributes of the filesets in a Zip or Jar task.)</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
@@ -4866,60 +4871,6 @@
end up in the <code>WEB-INF</code> directory of the war file. If this
fileset includes a file named <code>web.xml</code>, the file is
ignored and you will get a warning.</p>
-<h4>prefixedfileset</h4>
-<p>The nested <code>prefixedfileset</code> element specifies a <a
-href="#fileset">FileSet</a> with an additional prefix attribute. All
-files included in this fileset will end up in the <em>prefix</em>
-directory of the war file, where <em>prefix</em> is the value of the
-<code>prefix</code> attribute.</p>
-<table border="1" cellpadding="2" cellspacing="0">
- <tr>
- <td valign="top"><b>Attribute</b></td>
- <td valign="top"><b>Description</b></td>
- <td align="center" valign="top"><b>Required</b></td>
- </tr>
- <tr>
- <td valign="top">prefix</td>
- <td valign="top">The prefix directory to add to each filename when
- adding it to the archive. Default is none.</td>
- <td valign="top" align="center">No</td>
- </tr>
- <tr>
- <td valign="top">dir</td>
- <td valign="top">The root of the directory tree of this FileSet.</td>
- <td valign="top" align="center">Yes</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">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>
-</table>
<h3>Examples</h3>
<p>Assume the following structure in the project's base directory:
<pre>
@@ -4941,7 +4892,7 @@
<exclude name="jdbc1.jar" />
</lib>
<classes dir="build/main" />
- <prefixedfileset dir="src/graphics/images/gifs"
+ <fileset dir="src/graphics/images/gifs"
prefix="images"/>
</war>
</pre>
@@ -4986,6 +4937,13 @@
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 <em>within</em> each fileset.</p>
+<p>Inside of <code><zip></code> elements, nested filesets may include
one of two special attributes:
+<i>prefix</i> or <i>fullpath</i>. These attributes modify the location of
the files when they are placed
+inside the archive. If the <i>prefix</i> attribute is set, all the 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 filset 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.)</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.
@@ -5053,31 +5011,36 @@
<pre> <zip zipfile="${dist}/manual.zip"
basedir="htdocs/manual"
/></pre>
-<p>zips all files in the <code>htdocs/manual</code> directory in a file
called <code>manual.zip</code>
+<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 zipfile="${dist}/manual.zip"
basedir="htdocs/manual"
excludes="mydocs/**, **/todo.html"
/></pre>
-<p>zips all files in the <code>htdocs/manual</code> directory in a file
called <code>manual.zip</code>
-in the <code>${dist}</code> directory. Files in the directory
<code>mydocs</code>,
+<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 zipfile="${dist}/manual.zip"
basedir="htdocs/manual"
includes="api/**/*.html"
excludes="**/todo.html"
/></pre>
-<p>zips all files in the <code>htdocs/manual</code> directory in a file
called <code>manual.zip</code>
-in the <code>${dist}</code> directory. Only html files under the directory
<code>api</code>
+<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 zipfile="${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 in a file
called <code>manual.zip</code>
-in the <code>${dist}</code> directory, and also adds the file
<code>ChangeLog.txt</code> in the
+<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 zipfile="${dist}/manual.zip">
+ <fileset dir="htdocs/manual"
prefix="docs/user-guide"/>
+ <fileset dir="." includes="ChangeLog27.txt"
fullpath="docs/ChangeLog.txt"/>
+ </zip></pre>
+<p>zips all files in the <code>htdocs/manual</code> directory into the
<code>docs/user-guide</code> directory
+in the archive, and also adds the file <code>ChangeLog27.txt</code> in the
+current directory as <code>docs/ChangeLog.txt</code>. For example, the
archive might end up containing two files:
+<code>docs/user-guide/html/index.html</code> and
<code>docs/ChangeLog.txt</code></p>
<hr>
<h2><a name="optionaltasks">Optional tasks</a></h2>
@@ -5188,7 +5151,7 @@
basedir="htdocs/manual"
/>
</pre></blockquote>
-<p>cabs all files in the htdocs/manual directory in a file called
+<p>cabs all files in the htdocs/manual directory into a file called
manual.cab in the ${dist} directory.</p>
<blockquote><pre>
<cab cabfile="${dist}/manual.cab"
@@ -5196,7 +5159,7 @@
excludes="mydocs/**, **/todo.html"
/>
</pre></blockquote>
-<p>cabs all files in the htdocs/manual directory in a file called
+<p>cabs all files in the htdocs/manual directory into a file called
manual.cab in the ${dist} directory. Files in the directory mydocs,
or files with the name todo.html are excluded.</p>
<blockquote><pre>
@@ -5207,7 +5170,7 @@
verbose="yes"
/>
</pre></blockquote>
-<p>cab all files in the htdocs/manual directory in a file called
+<p>cab all files in the htdocs/manual directory into a file called
manual.cab in the ${dist} directory. Only html files under the
directory api are archived, and files with the name todo.html are
excluded. Output from the cabarc tool is displayed in the build
