@@ -8,29 +8,62 @@
<body>
<h2><a name="directorybasedtasks">Directory-based Tasks</a></h2>
<p>Some tasks use directory trees for the task they perform.
For example, the <a
href="CoreTasks/javac.html">javac</a> task, which works upon a directory tree
with <code>.java</code> files.
Sometimes it can be very useful to work on a subset of that directory tree. This
section describes how you can select a subset of such a directory tree.</p>
<p>Ant gives you two ways to create a subset, both of which can be used at the same
time:</p>
<p>Some tasks use directory trees for the actions they perform.
For example, the <a href="CoreTasks/javac.html">javac</a> task, which
compiles a directory tree with <code>.java</code> files into
<code>.class</code> files, is one of these directory-based tasks. Because
some of these tasks do so much work with a directory tree, the task itself
can act as an implicit <a href="CoreTypes/fileset.html">FileSet</a>.</p>
<p>Whether the fileset is implicit or not, it can often be very useful to
work on a subset of the directory tree. This section describes how you can
select a subset of such a directory tree when using one of these
directory-based tasks.</p>
<p>Ant gives you two ways to create a subset of files in a fileset, both of
which can be used at the same time:</p>
<ul>
<li>Only include files/directories that match at least one pattern of a set of
patterns.</li>
<li>Exclude files/directories that match at least one pattern a set of
patterns.</li>
<li>Only include files and directories that match any
<code>include</code> patterns and do not match any
<code>exclude</code> patterns in a given
<a href="CoreTypes/patternset.html">PatternSet</a>.</li>
<li>Select files based on selection criteria defined by a collection of
<a href="CoreTypes/selectors.html">selector</a> nested elements.</li>
</ul>
<p>When both inclusion and exclusion are used, only files/directories that match
the include patterns, and don't match the exclude patterns, are used.</p>
<p>Patterns can be specified inside the buildfile via task attributes or
nested elements and via external files. Each line of the external file
<h3><a name="patternset">Patternset</a></h3>
<p>We said that Directory-based tasks can sometimes act as an implicit
<a href="CoreTypes/fileset.html"><code><fileset></code></a>,
but in addtion to that, a FileSet acts as an implicit
<a href="CoreTypes/patternset.html"><code><patternset></code></a>.</p>
<p>The inclusion and exclusion elements of the implicit PatternSet can be
specified inside the directory-based task (or explicit fileset) via
either:</p>
<ul>
<li>the attributes <code>includes</code> and
<code>excludes</code>.</li>
<li>nested elements <code><include></code> and
<code><exclude></code>.</li>
<li>external files specified with the attributes
<code>includesfile</code> and <code>excludesfile</code>.</li>
<li>external files specified with the nested elements
<code><includesfile></code> and <code><excludesfile></code>.
</li>
</ul>
When dealing with an external file, each line of the file
is taken as a pattern that is added to the list of include or exclude
patterns.</p>
<h3><a name="patterns">Patterns</a></h3>
<p>As described earlier, patterns are used for the inclusion and exclusion.
These patterns look very much like the patterns used in DOS and UNIX:</p>
<p>When both inclusion and exclusion are used, only files/directories that
match at least one of the include patterns and don't match any of the
exclude patterns are used. If no include pattern is given, all files
are assumed to match the include pattern (with the possible exception of
the default excludes).</p>
<h4><a name="patterns">Patterns</a></h4>
<p>As described earlier, patterns are used for the inclusion and exclusion
of files. These patterns look very much like the patterns used in DOS and
UNIX:</p>
<p>'*' matches zero or more characters, '?' matches one character.</p>
<p><b>Examples:</b></p>
<p>
@@ -45,7 +78,8 @@ not <code>FooBar.xml</code> (does not end with <code>.java</code>).</p>
Combinations of <code>*</code>'s and <code>?</code>'s are allowed.</p>
<p>Matching is done per-directory. This means that first the first directory in
the pattern is matched against the first directory in the path to match. Then
the second directory is matched, and so on. For example, when we have the pattern <code>/?abc/*/*.java</code>
the second directory is matched, and so on. For example, when we have the pattern
<code>/?abc/*/*.java</code>
and the path <code>/xabc/foobar/test.java</code>,
the first <code>?abc</code> is matched with <code>xabc</code>,
then <code>*</code> is matched with <code>foobar</code>,
@@ -72,7 +106,8 @@ For example, <code>mypackage/test/</code> is interpreted as if it were
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top"><code>**/CVS/*</code></td>
<td valign="top">Matches all files in <code>CVS</code> directories that can be located
<td valign="top">Matches all files in <code>CVS</code>
directories that can be located
anywhere in the directory tree.<br>
Matches:
<pre>
@@ -82,12 +117,14 @@ For example, <code>mypackage/test/</code> is interpreted as if it were
</pre>
But not:
<pre>
org/apache/CVS/foo/bar/Entries (<code>foo/bar/</code> part does not match)</td>
org/apache/CVS/foo/bar/Entries (<code>foo/bar/</code>
part does not match)</td>
</pre>
</tr>
<tr>
<td valign="top"><code>org/apache/jakarta/**</code></td>
<td valign="top">Matches all files in the <code>org/apache/jakarta</code> directory tree.<br>
<td valign="top">Matches all files in the <code>org/apache/jakarta</code>
directory tree.<br>
Matches:
<pre>
org/apache/jakarta/tools/ant/docs/index.html
@@ -124,7 +161,57 @@ For example, <code>mypackage/test/</code> is interpreted as if it were
<p>When these patterns are used in inclusion and exclusion, you have a powerful
way to select just the files you want.</p>
<h3>Examples</h3>
<h3><a name="selectors">Selectors</a></h3>
<p>The <a href="CoreTypes/fileset.html"><code><fileset></code></a>,
whether implicit or explicit in the
directory-based task, also acts as an
<a href="CoreTypes/selectors.html#andselect"><code><and></code></a>
selector container. This can be used to create arbitrarily complicated
selection criteria for the files the task should work with. See the
<a href="CoreTypes/selectors.html">Selector</a> documentation for more
information.</p>
<h3><a name="tasklist">Standard Tasks/Filesets</a></h3>
<p>Many of the standard tasks in ant take one or more filesets which follow
the rules given here. This list, a subset of those, is a list of standard ant
tasks that can act as an implicit fileset:</p>
<ul>
<li><a href="CoreTasks/checksum.html"><checksum></a></li>
<li><a href="CoreTasks/copydir.html"><copydir></a> (deprecated)</li>
<li><a href="CoreTasks/delete.html"><delete></a></li>
<li><a href="CoreTasks/dependset.html"><dependset></a></li>
<li><a href="CoreTasks/fixcrlf.html"><fixcrlf></a></li>
<li><a href="CoreTasks/javac.html"><javac></a></li>
<li><a href="CoreTasks/replace.html"><replace></a></li>
<li><a href="CoreTasks/rmic.html"><rmic></a></li>
<li><a href="CoreTasks/style.html"><style> (aka <xslt>)</a></li>
<li><a href="CoreTasks/tar.html"><tar></a></li>
<li><a href="CoreTasks/zip.html"><zip></a></li>
<li><a href="OptionalTasks/ejb.html#ddcreator"><ddcreator></a></li>
<li><a href="OptionalTasks/ejb.html#ejbjar.html"><ejbjar></a></li>
<li><a href="OptionalTasks/ejb.html#ejbc"><ejbc></a></li>
<li><a href="OptionalTasks/cab.html"><cab></a></li>
<li><a href="OptionalTasks/icontract.html"><icontract></a></li>
<li><a href="OptionalTasks/native2ascii.html"><native2ascii></a></li>
<li><a href="OptionalTasks/netrexxc.html"><netrexxc></a></li>
<li>
<a href="OptionalTasks/renameextensions.html"><renameextensions></a>
</li>
<li><a href="OptionalTasks/depend.html"><depend></a></li>
<li><a href="OptionalTasks/dotnet.html"><ilasm></a></li>
<li><a href="OptionalTasks/dotnet.html"><csc></a></li>
<li><a href="OptionalTasks/dotnet.html"><vbc></a></li>
<li><a href="OptionalTasks/translate.html"><translate></a></li>
<li>
<a href="Integration/VAJAntTool.html#vajexport"><vajexport></a>
</li>
<li><image></li>
<li><a href="OptionalTasks/jlink.html"><jlink></a> (deprecated)</li>
<li><a href="OptionalTasks/jspc.html"><jspc></a></li>
<li><a href="OptionalTasks/wljspc.html"><wljspc></a></li>
</ul>
<h3><a name="examples">Examples</a></h3>
<pre>
<copy todir="${dist}">
<fileset dir="${src}"
@@ -136,7 +223,6 @@ way to select just the files you want.</p>
located in the directory tree defined by <code>${src}</code> to the
destination directory defined by <code>${dist}</code>,
but excludes all <code>*.gif</code> files from the copy.</p>
<p> This example can also be expressed using nested elements:</p>
<pre>
<copy todir="${dist}">
<fileset dir="${src}">
@@ -145,10 +231,20 @@ but excludes all <code>*.gif</code> files from the copy.</p>
</fileset>
</copy>
</pre>
<p> The same as the example above, but expressed using nested elements.</p>
<pre>
<delete dir="${dist}">
<include name="**/images/*"/>
<exclude name="**/*.gif"/>
</delete>
</pre>
<p>Deleting the original set of files, the <code>delete</code> task can act
as an implicit fileset.</p>
<h3><a name="defaultexcludes">Default Excludes</a></h3>
<p>There are a set of definitions that are excluded by default from all directory-based tasks.
They are:</p>
<p>There are a set of definitions that are excluded by default from all
directory-based tasks. They are:</p>
<pre>
**/*~
**/#*#
@@ -165,11 +261,11 @@ They are:</p>
**/.svn/**
**/.DS_Store
</pre>
<p>If you do not want these default excludes applied, you may disable them with the
<code>defaultexcludes="no"</code> attribute.</p>
<p>If you do not want these default excludes applied, you may disable them
with the <code>defaultexcludes="no"</code> attribute.</p>
<hr>
<p align="center">Copyright © 2000-2003 Apache Software Foundation. All rights
Reserved.</p>
<p align="center">Copyright © 2000-2003 Apache Software Foundation. All
rights Reserved.</p>
</body>
</html>
Bruce Atherton