conor 00/06/27 06:07:40
Modified: docs index.html
Log:
Update documentation
Add section on system requirements
Remove references to xml.jar and replace with JAXP compliant XML parser
Add section on build events. Basic information only
Add an example of nested include and exclude tag usage
Update documentation for Replace task
Revision Changes Path
1.32 +113 -16 jakarta-ant/docs/index.html
Index: index.html
===================================================================
RCS file: /home/cvs/jakarta-ant/docs/index.html,v
retrieving revision 1.31
retrieving revision 1.32
diff -u -r1.31 -r1.32
--- index.html 2000/06/27 10:42:22 1.31
+++ index.html 2000/06/27 13:07:34 1.32
@@ -17,17 +17,19 @@
<li>Tom Dimock (<a href="mailto:[EMAIL PROTECTED]">[EMAIL
PROTECTED]</a>)</li>
<li>Bill Kelly (<a href="mailto:[EMAIL PROTECTED]">[EMAIL
PROTECTED]</a>)</li>
<li>Arnout J. Kuiper (<a href="mailto:[EMAIL PROTECTED]">[EMAIL
PROTECTED]</a>)</li>
+ <li>Conor MacNeill (<a href="mailto:[EMAIL PROTECTED]">[EMAIL
PROTECTED]</a>)</li>
<li>Stefano Mazzocchi (<a href="mailto:[EMAIL PROTECTED]">[EMAIL
PROTECTED]</a>)</li>
<li>Sam Ruby (<a href="mailto:[EMAIL PROTECTED]">[EMAIL
PROTECTED]</a>)</li>
</ul>
-<p>Version 1.0.8.1 - 2000/06/13</p>
+<p>Version 1.0.8.1 - 2000/06/27</p>
<hr>
<h2>Table of Contents</h2>
<ul>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#getting">Getting Ant</a></li>
+ <li><a href="#sysrequirements">System Requirements</a></li>
<li><a href="#buildingant">Building Ant</a></li>
<li><a href="#installing">Installing Ant</a></li>
<li><a href="#running">Running Ant</a></li>
@@ -35,10 +37,12 @@
<li><a href="#directorybasedtasks">Directory based tasks</a></li>
<li><a href="#tasks">Built in Tasks</a>
<li><a href="#optionaltasks">Optional Tasks</a>
+ <li><a href="#buildevents">Build Events</a>
<li><a href="#writingowntask">Writing your own task</a></li>
<li><a href="#license">License</a></li>
<li><a href="#feedback">Feedback</a></li>
</ul>
+
<hr>
<h2><a name="introduction">Introduction</a></h2>
<p>Ant is a Java based build tool. In theory it is kind of like make without
@@ -68,6 +72,7 @@
hey, if you really need to execute a shell command, Ant has an exec rule that
allows different commands to be executed based on the OS that it is executing
on.</p>
+
<hr>
<h2><a name="getting">Getting Ant</a></h2>
<h3>Binary edition</h3>
@@ -82,14 +87,20 @@
href="http://jakarta.apache.org/from-cvs/jakarta-tools/";>http://jakarta.apache.org/from-cvs/jakarta-ant/</a>
(current). See the section <a href="#buildingant">Building Ant</a> on how to
build Ant from the source code.</p>
+
<hr>
-<h2><a name="buildingant">Building Ant</a></h2>
+<h2><a name="sysrequirements">System Requirements</a></h2>
<p>
- Download and install the Java API for XML Parsing kit from
- <a href="http://java.sun.com/xml";>http://java.sun.com/xml</a>.
- Make sure the "jaxp.jar" and "parser.jar" files are in your class
- path.
-</p>
+ To build and use ant you must have a JAXP compilant XML parser installed
and available on your classpath.
+ <p>
+ If you do not have a JAXP compliant XML parse installed, you may use the
reference implementation
+ available from Sun. It is available from <a
href="http://java.sun.com/xml";>http://java.sun.com/xml</a>.
+ Once installed make sure the "jaxp.jar" and "parser.jar" files are in your
classpath.
+ <p>
+ You will also need the JDK installed on your system, version 1.1 or later.
+
+<hr>
+<h2><a name="buildingant">Building Ant</a></h2>
<p>Go to the directory <code>jakarta-ant</code>.</p>
<p>Make sure the JDK is in you path.</p>
<p>Run <code>bootstrap.bat</code> (Windows) or <code>bootstrap.sh</code>
(UNIX)
@@ -131,11 +142,13 @@
<h3>Advanced</h3>
<p>There are lots of variants that can be used to run Ant. What you need is
at
least the following:</p>
-<p>The classpath for Ant must contain <code>ant.jar</code> and
<code>xml.jar</code>.</p>
+<p>The classpath for Ant must contain <code>ant.jar</code> and any
jars/classes
+needed for your chosen JAXP compliant XML parser.</p>
<p>When you need JDK functionality (like a <a href="#javac">javac</a> task,
or a
<a href="#rmic">rmic</a> task), then for JDK 1.1, the
<code>classes.zip</code>
file of the JDK must be added to the classpath; for JDK 1.2,
<code>tools.jar</code>
-must be added.</p>
+must be added. The scripts supplied with ant, in the bin directory, will add
+<code>tools.jar</code> automatically if the JAVA_HOME environment variable
is set.</p>
<p>When you are executing platform specific applications (like the <a
href="#exec">exec</a> task, or the <a href="#cvs">cvs</a> task), the
property <code>ant.home</code>
must be set to the directory containing a bin directory, which contains the
<code>antRun</code> shell script necessary to run execs on Unix.</p>
@@ -163,9 +176,11 @@
<pre>ant [options] [target]
Options:
-help print this message
+-version print the version information and exit
-quiet be extra quiet
-verbose be extra verbose
-logfile <file> use given file for log
+-listener <classname> add an instance of class as a project listener
-buildfile <file> use given buildfile
-D<property>=<value> use value for given property</pre>
<h3>Examples</h3>
@@ -194,12 +209,17 @@
<p>When you have installed Ant in the do-it-yourself way, Ant can be started
with:</p>
<blockquote>
- <pre>set
CLASSPATH=c:\ant\lib\ant.jar;c:\ant\lib\xml.jar;c:\jdk1.2.2\lib\tools.jar
-java -Dant.home=c:\ant org.apache.tools.ant.Main [options] [target]</pre>
+ <pre>java -Dant.home=c:\ant org.apache.tools.ant.Main [options]
[target]</pre>
</blockquote>
+
<p>These instructions actually do exactly the same as the <code>ant</code>
command. The options and target are the same as when running Ant with the
<code>ant</code>
-command.</p>
+command. This example assumes you have set up your classpath to include
+<ul>
+<li>ant.jar
+<li>jars/classes for your XML parser
+<li>the JDK's tools.jar
+</ul>
<hr>
<h2><a name="buildfile">Writing a simple buildfile</a></h2>
<p>The buildfile is written in XML. Each buildfile contains one project.</p>
@@ -359,13 +379,14 @@
</project>
</pre>
</blockquote>
+
<hr>
<h2><a name="directorybasedtasks">Directory based tasks</a></h2>
<p>Some tasks use directory trees for the task they perform. For instance,
the <a
href="#javac">Javac task</a> which works upon a directory tree with .java
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, which both can be used at the
same
+<p>Ant gives you two ways to create a subset, 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
@@ -452,6 +473,14 @@
<p>This copies all files in directories called "images", that are
located in the directory tree "${src}" to the destination
"${dist}",
but excludes all "*.gif" files from the copy.</p>
+<p> This example can also be expressed using nested elements as
+<pre> <copydir src="${src}"
+ dest="${dist}">
+ <include name="**/images/*"/>
+ <exclude name="**/*.gif" />
+ </copydir>
+</pre>
+
<h3>Default Excludes</h3>
<p>There are a set of definitions which are excluded by default from all
directory based tasks.
They are:
@@ -2161,7 +2190,8 @@
<hr>
<h2><a name="replace">Replace</a></h2>
<h3>Description</h3>
-<p>Replaces the occurrence of a given string with another string in a
file.</p>
+<p>Replace is a directory based task for replacing the occurrence of a given
string with another string
+in selected file.</p>
<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
@@ -2171,10 +2201,17 @@
</tr>
<tr>
<td valign="top">file</td>
- <td valign="top">file for which the token should be replaced.</td>
- <td valign="top" align="center">Yes</td>
+ <td valign="top">file for which the token should be replaced. If not
present the dir attribute
+ must be specified</td>
+ <td valign="top" align="center">No</td>
</tr>
<tr>
+ <td valign="top">dir</td>
+ <td valign="top">The base directory to use when replacing a token in
multiple files. If not present the file attribute
+ must be specified</td>
+ <td valign="top" align="center">No</td>
+ </tr>
+ <tr>
<td valign="top">token</td>
<td valign="top">the token which must be replaced.</td>
<td valign="top" align="center">Yes</td>
@@ -2185,6 +2222,36 @@
("") is used.</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>
+ <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>
</table>
<h3>Examples</h3>
<pre> <replace file="${src}/index.html" token="@@@"
value="wombat" /></pre>
@@ -2629,6 +2696,36 @@
<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/directories with the names
<code>mydocs</code>
and <code>todo.html</code> are excluded.</p>
+
+<hr>
+<h2><a name="buildevents">Build Events</a></h2>
+Ant is capable of generating build events as it performs the tasks necessary
to build a project.
+Listeners can be attached to ant to receive these events. This capability
could be used, for example,
+to connect Ant to a GUI or to integrate Ant with an IDE.
+
+<p>To use build events you need to create an ant <code>Project</code>
object. You can then call the
+<code>addBuildListener</code> method to add your listener to the project.
Your listener must implement
+the <code>org.apache.tools.antBuildListener</code> interface. The listener
will receive BuildEvents
+for the following events
+<ul>
+<li>Build started
+<li>Build finished
+<li>Target started
+<li>Target finished
+<li>Task started
+<li>Task finished
+<li>Message logged
+</ul>
+
+If you wish to attach a listener from the command line you may use the
-listener option. For example
+<blockquote>
+ <pre>ant -listener org.apache.tools.ant.XmlLogger</pre>
+</blockquote>
+will run ant with a listener which generates an XML representaion of the
build progress. This
+listener is included with ant as is the default listener which generates the
logging to standard
+output.
+
+
<hr>
<h2><a name="writingowntask">Writing your own task</a></h2>
<p>It is very easy to write your own task:</p>
