diff options
| author | mattinger <[email protected]> | 2006-07-06 21:53:00 +0000 |
|---|---|---|
| committer | mattinger <[email protected]> | 2006-07-06 21:53:00 +0000 |
| commit | 1159111b7a71b72eb04326df33211e1733f7e742 (patch) | |
| tree | f0a80c384f633e521649654ab78e6239cf5e0d6f /docs | |
Initial addition into subversion with build script changes
git-svn-id: file:///home/sven/projects/JOGL/temp/ant-contrib/svn/ant-contrib-code/trunk/ant-contrib@5 32d7a393-a5a9-423c-abd3-5d954feb1f2f
Diffstat (limited to 'docs')
39 files changed, 5896 insertions, 0 deletions
diff --git a/docs/LICENSE.txt b/docs/LICENSE.txt new file mode 100644 index 0000000..4d8c2fb --- /dev/null +++ b/docs/LICENSE.txt @@ -0,0 +1,47 @@ +/* + * The Apache Software License, Version 1.1 + * + * Copyright (c) 2001-2003 Ant-Contrib project. All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * + * 2. Redistributions in binary form must reproduce the above copyright + * notice, this list of conditions and the following disclaimer in + * the documentation and/or other materials provided with the + * distribution. + * + * 3. The end-user documentation included with the redistribution, if + * any, must include the following acknowlegement: + * "This product includes software developed by the + * Ant-Contrib project (http://sourceforge.net/projects/ant-contrib)." + * Alternately, this acknowlegement may appear in the software itself, + * if and wherever such third-party acknowlegements normally appear. + * + * 4. The name Ant-Contrib must not be used to endorse or promote products + * derived from this software without prior written permission. For + * written permission, please contact + * [email protected]. + * + * 5. Products derived from this software may not be called "Ant-Contrib" + * nor may "Ant-Contrib" appear in their names without prior written + * permission of the Ant-Contrib project. + * + * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED + * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + * DISCLAIMED. IN NO EVENT SHALL THE ANT-CONTRIB PROJECT OR ITS + * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, + * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT + * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF + * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND + * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, + * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT + * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF + * SUCH DAMAGE. + * ==================================================================== + */ diff --git a/docs/manual/index.html b/docs/manual/index.html new file mode 100644 index 0000000..a5ab022 --- /dev/null +++ b/docs/manual/index.html @@ -0,0 +1,91 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Ant-Contrib Tasks</title> + </head> + + <body> + <h1>Ant-Contrib Tasks</h1> + + <h2>Contents</h2> + + <ul> + <li><a href="#intro">What's this?</a></li> + <li><a href="#install">Installation</a></li> + <li><a href="tasks/index.html">Tasks</a></li> + </ul> + + <h2><a name="intro">What's this?</a></h2> + + <p>The Ant-Contrib project is a collection of tasks (and at one + point maybe types and other tools) for <a + href="http://ant.apache.org/">Apache Ant</a>.</p> + + <p>This Software is distributed under the <a + href="LICENSE.txt">Apache Software License</a>.</p> + + <h2><a name="install">Installation</a></h2> + + <p>First you must install Apache Ant itself, most of the + Ant-Contrib tasks require Ant 1.5 or higher to work properly, + however, there are some tasks, specifically <for> which + require Ant 1.6. You can download Ant <a + href="http://ant.apache.org/bindownload.cgi">from + Apache</a>.</p> + + <p>Then you need the Ant-Contrib tasks themselves. As there is no + release of these tasks yet, you have to build them from sources. + Fortunately this is easy, check out the sources (grab the + <code>ant-contrib</code> module from <a + href="http://sourceforge.net/cvs/?group_id=36177">CVS</a>), change + into the source directory of ant-contrib and type + <code>ant</code>. After Ant has completed, you'll find + <code>ant-contrib-version.jar</code> in the <code>lib</code> + subdirectory.</p> + + <p>You now have the choice:</p> + + <ol> + <li>Copy <code>ant-contrib-version.jar</code> to the + <code>lib</code> directory of your Ant installation, or on + your CLASSPATH environment variable. If you + want to use one of the tasks in your project, add the line +<pre> +<taskdef resource="net/sf/antcontrib/antlib.xml"/> +</pre> + to your build file.</li> + +<br /> +<br /> + + <li>Keep <code>ant-contrib-version.jar</code> in a separate + location. You now have to tell Ant explicitly where to find it + (say in <code>/usr/share/java/lib</code>): +<pre> +<taskdef resource="net/sf/antcontrib/antlib.xml"> + <classpath> + <pathelement location="/usr/share/java/lib/ant-contrib-version.jar"/> + </classpath> +</taskdef> +</pre> + </li> + + <li>If you would like to use run with Ant Version 1.5 you must use the + the .properties file instead. Keep in mind that some tasks will not + be available to you , such as the <for> task: + +<pre> +<taskdef resource="net/sf/antcontrib/antcontrib.properties"> + <classpath> + <pathelement location="/usr/share/java/lib/ant-contrib-version.jar"/> + </classpath> +</taskdef> +</pre> + + + <hr> + <p align="center">Copyright © 2002-2004 Ant-Contrib Project. All + rights Reserved.</p> + + </body> +</html> diff --git a/docs/manual/tasks/antcallback_task.html b/docs/manual/tasks/antcallback_task.html new file mode 100644 index 0000000..731e7c4 --- /dev/null +++ b/docs/manual/tasks/antcallback_task.html @@ -0,0 +1,177 @@ +<html> +<head> +<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> + +<title> +AntCallBack</title> + +<meta content="DocBook XSL Stylesheets V1.60.1" name="generator"> + +<link rel="home" href="index.html" title="Antelope Users Guide"> + +<link rel="up" href="bk03.html" title="Additional Ant Tasks"> + +<link rel="previous" href="bk03ch14.html" title="Chapter 14. AntFetch"> + +<link rel="next" href="bk03ch16.html" title="Chapter 16. Call Task"> + +</head> + +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> + +<div class="chapter" lang="en"> +<div class="titlepage"> +<div> +<div> +<h2 class="title"> +<a name="antcallback"> +</a> +AntCallBack</h2> +</div> +</div> +<div> +</div> +</div> +<p> + +AntCallBack is identical to the standard 'antcall' task, except that it allows properties set in the called target to be available in the calling target. +</p> +<p> + +</p> +<p> + +Some background may be in order: When the <antcall> task is used, in actuality, a new Ant project is created, and depending on the inheritAll property, it is populated with properties from the original project. Then the requested target in this new project is executed. Any properties set in the new project remain with that project, they do not get "passed back" to the original project. So, for example, if the target in the new project sets a property named "image.directory", there is no reference to that property in the original. Here's an example of what I mean: +</p> +<p> + +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + + <target name="testCallback" description="Test CallBack"> + <antcallback target="-testcb" return="a, b"/> + <echo>a = ${a}</echo> + <echo>b = ${b}</echo> + </target> + + <target name="-testcb"> + <property name="a" value="A"/> + <property name="b" value="B"/> + </target> + +</pre> +</td> +</tr> +</table> + +The output from executing "testCallback" looks like this: +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + +a = A +b = B +</pre> +</td> +</tr> +</table> + +Contrast with this output from "antcall": +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + +a = ${a} +b = ${b} +</pre> +</td> +</tr> +</table> + +</p> +<p> + +This is an often requested feature for Ant, at least judging from the Ant mailing lists. I assume this is because it allows a more functional programming style than Ant natively supports. The proper Ant way of doing the above is like this: +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + + <target name="testCallback" description="Test CallBack" depends="-testcb"> + <echo>a = ${a}</echo> + <echo>b = ${b}</echo> + </target> + + <target name="-testcb"> + <property name="a" value="A"/> + <property name="b" value="B"/> + </target> + +</pre> +</td> +</tr> +</table> + +This is actually looks cleaner in this situation, and is faster, too. There is significant overhead in using both "antcall" and "antcallback" in that they both require a lot of object instantiation and property copying. That said, many people prefer to use "antcall" and "antcallback" as it better fits their logic and style. +</p> +<p> + +The attributes for AntCallBack are identical to the 'antcall' task, with one additional, optional attibute. This attribute is named "return" and can be either a single property name or a comma separated list of property names. +<div class="table"> +<a name="N10B76"> +</a> +<p class="title"> +<b> +Table 15.1. AntCallBack Attributes</b> +</p> +<table summary="AntCallBack Attributes" border="1"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead> +<tr> +<th> +Attribute</th> +<th> +Description</th> +<th> +Default</th> +<th> +Required</th> +</tr> +</thead> +<tbody> +<tr> +<td> +return</td> +<td> +A comma separated list of property names. Whitespace is allowed, so either "a,b" or "a, b" are acceptable.</td> +<td> +None</td> +<td> +No</td> +</tr> +</tbody> +</table> +</div> + +</p> +<p> + +For other attribute and nested element information and more examples, see the documentation for the "antcall" task in the Ant documentation. +</p> +</div> + <hr> + <p align="center">Copyright © 2003 Ant-Contrib Project. All + rights Reserved.</p> +</body> +</html> diff --git a/docs/manual/tasks/antclipse_task.html b/docs/manual/tasks/antclipse_task.html new file mode 100644 index 0000000..8ac5667 --- /dev/null +++ b/docs/manual/tasks/antclipse_task.html @@ -0,0 +1,139 @@ +<html lang="en-us"> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<title>Antclipse Task</title> +</head> + +<body> + +<h2>Antclipse Task</h2> +<p>Creator: Adrian Spinei (<a href="mailto:[email protected]">[email protected]</a>)</p> +<h3>Description</h3> +<p>UNSTABLE CODE, some parameters are supposed to change</p> +<p>This task creates classpaths or filesets based on your current .classpath file generated by Eclipse</p> +<p>Classpath creation is simple, it just produces a classpath that you can subsequently retrieve by its refid. +The filesets are a little trickier, because the task is producing a fileset per directory in the case of sources and another separate fileset for the +output file. Which is not necessarily bad, since the content of each directory usually serves a different purpose. Now, in order to avoit conflicting +refids each fileset has a name composed by the idcontainer, followed by a dash and postfixed by the path. Supposing that your output path is +<b>bin/classes</b> and the idcontainer is default, the task will create a fileset with refid "<b>antclipse-bin/classes</b>". The fileset will include all the files contained in +your output directory, but without the trailing path bin/classes (as you usually strip it when creating the distribution jar).</p> +<p>If you have two source directories, called src and test, you'll be provided with two filesets, with refids like <b>antclipse-src<b> and </b>antclipse-test</b>. +However, you don't have to code manually the path since some properties are created as a "byproduct" each time you execute the task. Their name is "<b>idref</b>" +postfixed by "<b>outpath</b>" and "<b>srcpath</b>" (in the case of the source, you'll find the location of the first source directory).</p> + +<h3>Parameters</h3> +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td>Attribute</td> + <td>Description</td> + + <td>Required</td> + </tr> + <tr> + <td><em>produce</em></td> + <td>This parameter tells the task wether to produce a "classpath" or a "fileset" (multiple filesets, as a matter of fact).</td> + <td>Yes</td> + </tr> + + <tr> + <td><em>idcontainer</em></td> + <td>The refid which will serve to identify the deliverables. When multiple filesets are produces, their refid is a concatenation between this value and something else (usually obtained from a path). Default "antclipse"</td> + <td>No</td> + </tr> + <tr> + <td><em>includelibs</em></td> + + <td>Boolean, whether to include or not the project libraries. Default is true.</td> + <td>No</td> + </tr> + <tr> + <td><em>includesource</em></td> + <td>Boolean, whether to include or not the project source directories. Default is false.</td> + <td>No</td> + + </tr> + <tr> + <td><em>includeoutput</em></td> + <td>Boolean, whether to include or not the project output directories. Default is false.</td> + <td>No</td> + </tr> + <tr> + + <td><em>verbose</em></td> + <td>Boolean, telling the app to throw some info during each step. Default is false.</td> + <td>No</td> + </tr> + <tr> + <td><em>includes</em></td> + <td>A regexp for files to include. It is taken into account only when producing a classpath, doesn't work on source or output files. It is a real regexp, not a "*" expression.</td> + + <td>No</td> + </tr> + <tr> + <td><em>excludes</em></td> + <td>A regexp for files to exclude. It is taken into account only when producing a classpath, doesn't work on source or output files. It is a real regexp, not a "*" expression.</td> + <td>No</td> + </tr> + +</table> + +<h3>Parameters specified as nested elements</h3> +<p>None at the moment.</p> + +<h3>TODOS</h3> +<ul> +<li>make "includes" and "excludes" to work on the source and output filesets</li> +<li>maybe find an elegant solution to this multiple fileset/directories issues</li> +<li>work with files referenced in other projects</li> +</ul> + +<h3>Example</h3> + +<p>This is a pretty self-explanatory Ant script, just follow the comments.</p> + +<pre> +<span style='color:#7f0055; '><?</span><span style='color:#7f0055; '>xml</span> <span style='color:#7f0055; '>version</span>="1.0"<span style='color:#7f0055; '>?></span> +<span style='color:#7f0055; '><</span><span style='color:#7f0055; font-weight:bold; '>project</span> default=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>compile</span><span style='color:#2a00ff; '>"</span> name=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>test</span><span style='color:#2a00ff; '>"</span> basedir=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>.</span><span style='color:#2a00ff; '>"</span><span style='color:#7f0055; '>></span> +<span style='color:#7f0055; '><</span><span style='color:#7f0055; font-weight:bold; '>taskdef</span> name=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>antclipse</span><span style='color:#2a00ff; '>"</span> classname=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>net.sf.antcontrib.antclipse.ClassPathTask</span><span style='color:#2a00ff; '>"</span><span style='color:#7f0055; '>/></span> +<span style='color:#7f0055; '><</span><span style='color:#7f0055; font-weight:bold; '>target</span> name=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>make.fs.output</span><span style='color:#2a00ff; '>"</span><span style='color:#7f0055; '>></span> + <span style='color:#3f7f59; '><!--</span><span style='color:#3f7f59; '> creates a fileset including all the files from the output directory, called ecl1-bin if your binary directory is bin/ </span><span style='color:#3f7f59; '>--></span> + <span style='color:#7f0055; '><</span><span style='color:#7f0055; '>antclipse</span> produce=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>fileset</span><span style='color:#2a00ff; '>"</span> idcontainer=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>ecl1</span><span style='color:#2a00ff; '>"</span> includeoutput=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>true</span><span style='color:#2a00ff; '>"</span> includesource=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>false</span><span style='color:#2a00ff; '>"</span> + includelibs=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>false</span><span style='color:#2a00ff; '>"</span> verbose=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>true</span><span style='color:#2a00ff; '>"</span><span style='color:#7f0055; '>/></span> +<span style='color:#7f0055; '></</span><span style='color:#7f0055; font-weight:bold; '>target</span><span style='color:#7f0055; '>></span> +<span style='color:#7f0055; '><</span><span style='color:#7f0055; font-weight:bold; '>target</span> name=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>make.fs.sources</span><span style='color:#2a00ff; '>"</span><span style='color:#7f0055; '>></span> + <span style='color:#3f7f59; '><!--</span><span style='color:#3f7f59; '> creates a fileset for each source directory, called ecl2-*source-dir-name*/ </span><span style='color:#3f7f59; '>--></span> + <span style='color:#7f0055; '><</span><span style='color:#7f0055; '>antclipse</span> produce=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>fileset</span><span style='color:#2a00ff; '>"</span> idcontainer=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>ecl2</span><span style='color:#2a00ff; '>"</span> includeoutput=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>false</span><span style='color:#2a00ff; '>"</span> includesource=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>true</span><span style='color:#2a00ff; '>"</span> + includelibs=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>false</span><span style='color:#2a00ff; '>"</span> verbose=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>true</span><span style='color:#2a00ff; '>"</span><span style='color:#7f0055; '>/></span> +<span style='color:#7f0055; '></</span><span style='color:#7f0055; font-weight:bold; '>target</span><span style='color:#7f0055; '>></span> +<span style='color:#7f0055; '><</span><span style='color:#7f0055; font-weight:bold; '>target</span> name=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>make.fs.libs</span><span style='color:#2a00ff; '>"</span><span style='color:#7f0055; '>></span> + <span style='color:#3f7f59; '><!--</span><span style='color:#3f7f59; '> creates a fileset sontaining all your project libs called ecl3/ </span><span style='color:#3f7f59; '>--></span> + <span style='color:#7f0055; '><</span><span style='color:#7f0055; '>antclipse</span> produce=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>fileset</span><span style='color:#2a00ff; '>"</span> idcontainer=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>ecl3</span><span style='color:#2a00ff; '>"</span> verbose=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>true</span><span style='color:#2a00ff; '>"</span><span style='color:#7f0055; '>/></span> +<span style='color:#7f0055; '></</span><span style='color:#7f0055; font-weight:bold; '>target</span><span style='color:#7f0055; '>></span> +<span style='color:#7f0055; '><</span><span style='color:#7f0055; font-weight:bold; '>target</span> name=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>make.cp</span><span style='color:#2a00ff; '>"</span><span style='color:#7f0055; '>></span> + <span style='color:#3f7f59; '><!--</span><span style='color:#3f7f59; '> creates a fileset sontaining all your project libs called ecl3/ </span><span style='color:#3f7f59; '>--></span> + <span style='color:#7f0055; '><</span><span style='color:#7f0055; '>antclipse</span> produce=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>classpath</span><span style='color:#2a00ff; '>"</span> idcontainer=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>eclp</span><span style='color:#2a00ff; '>"</span> verbose=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>true</span><span style='color:#2a00ff; '>"</span> includeoutput=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>true</span><span style='color:#2a00ff; '>"</span><span style='color:#7f0055; '>/></span> +<span style='color:#7f0055; '></</span><span style='color:#7f0055; font-weight:bold; '>target</span><span style='color:#7f0055; '>></span> +<span style='color:#7f0055; '><</span><span style='color:#7f0055; font-weight:bold; '>target</span> name=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>compile</span><span style='color:#2a00ff; '>"</span> depends=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>make.fs.libs, make.fs.output, make.fs.sources, make.cp</span><span style='color:#2a00ff; '>"</span><span style='color:#7f0055; '>></span> + <span style='color:#7f0055; '><</span><span style='color:#7f0055; font-weight:bold; '>echo</span> message=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>The output path is $</span><span style='color:#2a00ff; '>{ecl1outpath}</span><span style='color:#2a00ff; '>"</span><span style='color:#7f0055; '>/></span> + <span style='color:#7f0055; '><</span><span style='color:#7f0055; font-weight:bold; '>echo</span> message=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>The source path is $</span><span style='color:#2a00ff; '>{ecl2srcpath}</span><span style='color:#2a00ff; '>"</span><span style='color:#7f0055; '>/></span> + <span style='color:#3f7f59; '><!--</span><span style='color:#3f7f59; '> makes a jar file with the content of the output directory </span><span style='color:#3f7f59; '>--></span> + <span style='color:#7f0055; '><</span><span style='color:#7f0055; font-weight:bold; '>zip</span> destfile=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>out.jar</span><span style='color:#2a00ff; '>"</span><span style='color:#7f0055; '>></span><span style='color:#7f0055; '><</span><span style='color:#7f0055; font-weight:bold; '>fileset</span> refid=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>ecl1-${</span><span style='color:#2a00ff; '>ecl1outpath}</span><span style='color:#2a00ff; '>"</span><span style='color:#7f0055; '>/></span><span style='color:#7f0055; '></</span><span style='color:#7f0055; font-weight:bold; '>zip</span><span style='color:#7f0055; '>></span> + <span style='color:#3f7f59; '><!--</span><span style='color:#3f7f59; '> makes a zip file with all your sources (supposing you have only source directory) </span><span style='color:#3f7f59; '>--></span> + <span style='color:#7f0055; '><</span><span style='color:#7f0055; font-weight:bold; '>zip</span> destfile=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>src.zip</span><span style='color:#2a00ff; '>"</span><span style='color:#7f0055; '>></span><span style='color:#7f0055; '><</span><span style='color:#7f0055; font-weight:bold; '>fileset</span> refid=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>ecl2-${</span><span style='color:#2a00ff; '>ecl2srcpath}</span><span style='color:#2a00ff; '>"</span><span style='color:#7f0055; '>/></span><span style='color:#7f0055; '></</span><span style='color:#7f0055; font-weight:bold; '>zip</span><span style='color:#7f0055; '>></span> + <span style='color:#3f7f59; '><!--</span><span style='color:#3f7f59; '> makes a big zip file with all your project libraries </span><span style='color:#3f7f59; '>--></span> + <span style='color:#7f0055; '><</span><span style='color:#7f0055; font-weight:bold; '>zip</span> destfile=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>libs.zip</span><span style='color:#2a00ff; '>"</span><span style='color:#7f0055; '>></span><span style='color:#7f0055; '><</span><span style='color:#7f0055; font-weight:bold; '>fileset</span> refid=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>ecl3</span><span style='color:#2a00ff; '>"</span><span style='color:#7f0055; '>/></span><span style='color:#7f0055; '></</span><span style='color:#7f0055; font-weight:bold; '>zip</span><span style='color:#7f0055; '>></span> + <span style='color:#3f7f59; '><!--</span><span style='color:#3f7f59; '> imports the classpath into a property then echoes the property </span><span style='color:#3f7f59; '>--></span> + <span style='color:#7f0055; '><</span><span style='color:#7f0055; font-weight:bold; '>property</span> name=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>cpcontent</span><span style='color:#2a00ff; '>"</span> refid=<span style='color:#2a00ff; '>"</span><span style='color:#2a00ff; '>eclp</span><span style='color:#2a00ff; '>"</span><span style='color:#7f0055; '>/></span> + <span style='color:#7f0055; '><</span><span style='color:#7f0055; font-weight:bold; '>echo</span><span style='color:#7f0055; '>></span>The newly created classpath is ${cpcontent}<span style='color:#7f0055; '></</span><span style='color:#7f0055; font-weight:bold; '>echo</span><span style='color:#7f0055; '>></span> +<span style='color:#7f0055; '></</span><span style='color:#7f0055; font-weight:bold; '>target</span><span style='color:#7f0055; '>></span> +<span style='color:#7f0055; '></</span><span style='color:#7f0055; font-weight:bold; '>project</span><span style='color:#7f0055; '>></span> +</pre> + +<hr> + <p align="center">Copyright © 2002-2003 Ant-Contrib Project. All + rights Reserved.</p> + +</body> +</html> + diff --git a/docs/manual/tasks/antfetch_task.html b/docs/manual/tasks/antfetch_task.html new file mode 100644 index 0000000..f92e635 --- /dev/null +++ b/docs/manual/tasks/antfetch_task.html @@ -0,0 +1,151 @@ +<html> +<head> +<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title> +AntFetch</title> +<meta content="DocBook XSL Stylesheets V1.60.1" name="generator"> +<link rel="home" href="index.html" title="Antelope Users Guide"> +<link rel="up" href="bk03.html" title="Additional Ant Tasks"> +<link rel="previous" href="bk03ch13.html" title="Chapter 13. SSH and SCP"> +<link rel="next" href="bk03ch15.html" title="Chapter 15. AntCallBack"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="chapter" lang="en"> +<div class="titlepage"> +<div> +<div> +<h2 class="title"> +<a name="antfetch"> +</a> +AntFetch</h2> +</div> +</div> +<div> +</div> +</div> +<p> + +AntFetch is identical to the standard 'Ant' task, except that it allows properties from the new project to be set in the original project. +</p> +<p> + +</p> +<p> + +Some background may be in order: When the <ant> task is used, in actuality, a new Ant project is created, and depending on the inheritAll property, it is populated with properties from the original project. Then the target in this new project is executed. Any properties set in the new project remain with that project, they do not get "passed back" to the original project. So, for example, if the target in the new project sets a property named "image.directory", there is no reference to that property in the original. Here's an example of what I mean: +</p> +<p> + +Suppose that the "fillImageDirectory" target sets a property named "image.directory" and I call the following: +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + + <ant dir="${image.project} target="fillImageDirectory"/> + <echo>${image.directory}</echo> + +</pre> +</td> +</tr> +</table> + +The output of the echo task will be ${image.directory}, not whatever was set in the "fillImageDirectory" target. +</p> +<p> + +The AntFetch task allows that image.directory property to be set in the original project. The attributes for AntFetch are identical to the 'Ant' task, with one additional, optional attibute. This attribute is named "return" and can be either a single property name or a comma separated list of property names. +</p> +<p> + +Assuming that "fillImageDirectory" actually sets a property named "image.directory", the following example will print out the directory name: +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + + <antfetch dir="${image.project} target="fillImageDirectory" return="image.directory"/> + <echo>${image.directory}</echo> + +</pre> +</td> +</tr> +</table> + +</p> +<p> + +And this one will also print out the thumbnail directory: +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + + <antfetch dir="${image.project} target="fillImageDirectory" return="image.directory, thumbnail.directory"/> + <echo>${image.directory}</echo> + <echo>${thumbnail.directory}</echo> + +</pre> +</td> +</tr> +</table> + +</p> +<p> + +The attributes for AntFetch are identical to the 'ant' task, with one additional, optional attibute. This attribute is named "return" and can be either a single property name or a comma separated list of property names. +<div class="table"> +<a name="N10B35"> +</a> +<p class="title"> +<b> +Table 14.1. AntFetch Attributes</b> +</p> +<table summary="AntFetch Attributes" border="1"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead> +<tr> +<th> +Attribute</th> +<th> +Description</th> +<th> +Default</th> +<th> +Required</th> +</tr> +</thead> +<tbody> +<tr> +<td> +return</td> +<td> +A comma separated list of property names. Whitespace is allowed, so either "a,b" or "a, b" are acceptable.</td> +<td> +None</td> +<td> +No</td> +</tr> +</tbody> +</table> +</div> + +</p> +<p> + +For other attribute and nested element information and more examples, see the documentation for the "ant" task in the Ant documentation. +</p> +</div> + <hr> + <p align="center">Copyright © 2003 Ant-Contrib Project. All + rights Reserved.</p> +</body> +</html> diff --git a/docs/manual/tasks/assert_task.html b/docs/manual/tasks/assert_task.html new file mode 100644 index 0000000..7d375ce --- /dev/null +++ b/docs/manual/tasks/assert_task.html @@ -0,0 +1,260 @@ +<html> +<head> +<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title> +Assert Task</title> +<meta content="DocBook XSL Stylesheets V1.60.1" name="generator"> +<link rel="home" href="index.html" title="Antelope Users Guide"> +<link rel="up" href="bk03.html" title="Additional Ant Tasks"> +<link rel="previous" href="bk03ch03.html" title="Chapter 3. Installation"> +<link rel="next" href="bk03ch05.html" title="Chapter 5. If Task"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="chapter" lang="en"> +<div class="titlepage"> +<div> +<div> +<h2 class="title"> +<a name="Assert"> +</a> +Assert Task</h2> +</div> +</div> +<div> +</div> +</div> +<p> + +The Assert task adds an assertion capability to Ant projects. This task works in a manner very similar to the Java <tt class="computeroutput"> +assert</tt> + keyword, and provides a limited "design by contract" facility to Ant. This is very useful for testing build scripts prior to putting them into production. +</p> +<p> + +The Assert task verifies that a given property has a +given value and throws a BuildException if the property value is not as expected +or the property does not exist. +</p> +<p> + +Also like Java's <tt class="computeroutput"> +assert</tt> + keyword, the Assert task must be 'turned on' using the property <tt class="computeroutput"> +ant.enable.asserts</tt> +. If not set, or is set to <tt class="computeroutput"> +false</tt> +, the Assert task works exactly like the Sequential task. If the <a href="variable_task.html" title="Variable Task"> +Variable task</a> + is used to define this property, then it can be turned on and off as needed throughout a build. +</p> +<p> + +This task can hold other tasks including Assert. +</p> +<p> + +The Assert task may contain one 'bool' element. The 'bool' element is identical to the ConditionTask, but unlike the ConditionTask, is actually a Task. The 'bool' element can contain all the conditions permitted by the ConditionTask, plus the <a href="bk03ch05s02.html" title="More Conditions"> +IsPropertyTrue</a> +, <a href="more_conditions.html" title="More Conditions"> +IsPropertyFalse</a> +, +<a href="more_conditions.html" title="More Conditions"> +StartsWith</a> +, +<a href="more_conditions.html" title="More Conditions"> +EndsWith</a> +, +<a href="more_conditions.html" title="More Conditions"> +IsGreaterThan</a> +, +<a href="more_conditions.html" title="More Conditions"> +IsLessThan</a> + and conditions. +See the If task for examples of using these conditionals. +</p> + +<p> + +<div class="table"> +<a name="N10583"> +</a> +<p class="title"> +<b> +Table 4.1. Assert Task Attributes</b> +</p> +<table summary="Assert Task Attributes" border="1"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead> +<tr> +<th> +Attribute</th> +<th> +Description</th> +<th> +Default</th> +<th> +Required</th> +</tr> +</thead> +<tbody> +<tr> +<td> +name</td> +<td> +The name of the property to test for.</td> +<td> +none</td> +<td> +Yes</td> +</tr> +<tr> +<td> +exists</td> +<td> +Test for existence or non-existence of the property.</td> +<td> +True</td> +<td> +No</td> +</tr> +<tr> +<td> +value</td> +<td> +The value to test for, implies 'exists=true'. If the value in the project is different than this value, a BuildException will be thrown and the build will stop.</td> +<td> +none</td> +<td> +No</td> +</tr> +<tr> +<td> +execute</td> +<td> +Should the tasks contained in this task be executed? It may be useful to set this to false when testing build files.</td> +<td> +True</td> +<td> +No</td> +</tr> +<tr> +<td> +failonerror</td> +<td> +Should the build halt if the assertion fails? Setting this to false is contrary to the intented use of assertions, but may be useful in certain situations. </td> +<td> +True</td> +<td> +No</td> +</tr> +</tbody> +</table> +</div> + + +</p> +<p> + +As stated above, the Assert task may contain a nested "bool" task, otherwise, +the Assert task does not support any nested +elements apart from Ant tasks. Any valid Ant task may be embedded within the +assert task. +</p> +<p> + +In the following example, the first <tt class="computeroutput"> +assert</tt> + task checks that the <tt class="computeroutput"> +wait</tt> + property exists and does not execute the <tt class="computeroutput"> +echo</tt> + and <tt class="computeroutput"> +sleep</tt> + tasks. The second <tt class="computeroutput"> +assert</tt> + task checks that the <tt class="computeroutput"> +wait</tt> + property exists, has a value of 2, and executes the <tt class="computeroutput"> +echo</tt> + task. +</p> +<p> + +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + + <property name="wait" value="2"/> + <assert name="wait" execute="false"> + <echo> + Waiting ${wait} seconds... + Click the red button to stop waiting. + </echo> + <sleep seconds="${wait}"/> + </assert> + <assert name="wait" value="2" execute="true"> + <echo>done waiting!</echo> + </assert> + +</pre> +</td> +</tr> +</table> + +</p> +<p> + +The next example shows Assert being used in a unit test for the "limit" task: +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + + <property name="ant.enable.asserts" value="true"/> + <target name="test2"> + <!-- should not stop 'sleep' task, should print out '_passed_' --> + <stopwatch name="timer"/> + <limit maxwait="5"> + <sleep seconds="1"/> + <echo>_passed_</echo> + </limit> + <stopwatch name="timer" action="total"/> + <assert message="Too much time."> + <bool> + <islessthan arg1="${timer}" arg2="2"/> + </bool> + </assert> + </target> + +</pre> +</td> +</tr> +</table> + +</p> +<p> + +If the <tt class="computeroutput"> +ant.enable.asserts</tt> + property is set to false, then in the above example, the <tt class="computeroutput"> +echo</tt> +, <tt class="computeroutput"> +sleep</tt> +, and <tt class="computeroutput"> +echo</tt> + tasks will all execute. +</p> + <hr> + <p align="center">Copyright © 2003 Ant-Contrib Project. All + rights Reserved.</p> +</div> +</body> +</html> diff --git a/docs/manual/tasks/compilewithwalls.html b/docs/manual/tasks/compilewithwalls.html new file mode 100644 index 0000000..c3416cb --- /dev/null +++ b/docs/manual/tasks/compilewithwalls.html @@ -0,0 +1,135 @@ +<html lang="en-us"> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<title>Compile With Walls Task</title> +</head> + +<body> + +<h2><a name="javac">Compile With Walls Task</a></h2> + +<h3>Deprecated: Use <a href="verifydesign.html">verifydesign</a> task instead</h3> +<p>Creator: Dean Hiller (<a href="mailto:[email protected]">[email protected]</a>)</p> +<h3>Description</h3> +<p>Puts up walls in a the same source tree to ensure that designs are not violated</p> +<p>This task helps someone separate out packages and prevent dependencies from occurring on accident. For example, if there are three packages in one source tree +<ul> +<li>biz.xsoftware.mod</li> +<li>biz.xsoftware.modA</li> +<li>biz.xsoftware.modB</li> +</ul> +and modB and modA should be able to compiled independently, you can put a wall up in between the two so that if anyone adds a dependency between modA and modB, the build will break. This is particularly good if the builds are automated.</p> + +<p>This task is for low level design. For architectural walls like client and server, I would suggest using multiple source trees and compiling those source trees independently as two different ant compile targets.</p> + +One pattern I personally like to follow can be seen on the vmaster project on sourceforge. Instructions to check it out and look at are <a href="https://sourceforge.net/cvs/?group_id=46703">HERE.</a> The interesting files in vmaster to look at our here.... +<ul> +<li>vmaster/vmasterdiff/conf/build.xml(ant file using compilewithwalls)</li> +<li>vmaster/vmasterdiff/conf/dependencies.xml(The compilewithwalls task references this file as the walls)</li> +</ul> +Looking at some of the 2nd file(dependencies.xml), one can see apis separated out for many non-GUI and GUI components in these packages +<ul> +<li>api.biz.xsoftware.difflib.file.*</li> +<li>api.biz.xsoftware.difflib.dir.*</li> +<li> more api.* packages</li> +<li>org.vmasterdiff.gui.dirdiff.impl.*</li> +</ul> +Looking closely at the api.* packages, each one has a Factory. This factory uses reflection to create the implementation components. Basically, the api should not know of the implementation so there are walls around the api. Reflection to instantiate the implementation gets around these walls. My bigger components that use the smaller one's use these factories. In my design you are guaranteed these components are replaceable. Feel free to checkout vmaster and look at the factories also. +<p> + +<h3>Parameters</h3> +<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">walls</td> + <td valign="top">Specifies the external dependency file to use(see example below)</td> + <td align="center" valign="top">Either this or a nested walls element is required</td> + </tr> + <tr> + <td valign="top">intermediaryBuildDir</td> + <td valign="top">Specifies scratch area for the compilewithwalls task to do the building and ensure dependencies are not violated</td> + <td align="center" valign="top">required</td> + </tr> +</table> + +<h3>Parameters specified as nested elements</h3> +<p>This task can contain one nested javac task and one nested walls task. See the <a href="PUT JAVAC REF HERE">javac task</a> for it's attributes and nested elements. + +</p> +<h3>Walls element</h3> +<p> +The nested walls element or the walls attribute must be specified. Only one may be used. The walls element contains nested package elements. These nested package elements have the following attributes. If any package depends on another, it must be listed after the package it depends on in the walls element. +</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">name</td> + <td valign="top">A smaller nickname for the package to reference in depends</td> + <td align="center" valign="top">Required</td> + </tr> + <tr> + <td valign="top">package</td> + <td valign="top">The package to compile such as biz.xsoftware.* to + include the immediate package only or + biz.xsoftware.** to include biz.xsoftware and all subpackages.</td> + <td align="center" valign="top">Required</td> + </tr> + <tr> + <td valign="top">depends</td> + <td valign="top">If a package need one of the previously specified packages to compile, it's name would be added here in a comma separated list. For example depends="modA,modB"</td> + <td align="center" valign="top">Optional</td> + </tr> +</table> + +<h3>Examples</h3> + +In the examples, I will show the javac as a null element, because it's use is documented in the <a href="PUT JAVAC REF HERE">javac task</a> documentation. + +<h4>Walls Nested Element....</h4> +<pre> + <compilewithwalls> + <walls> + <package name="modA" package="biz.xsoftware.mod.modA.**"/> + <package name="modB" package="biz.xsoftware.mod.modB.*"/> + <package name="mod" package="biz.xsoftware.mod.modA.*" depends="modA,modB"/> + </walls> + <a href="PUT JAVAC TASK LINK HERE"><javac></javac></a> + </compilewithwalls></pre> +<p> +Notice that the package named mod had to come after the packages it depended on. Now if anybody puts code in modA that uses classes in modB, the build will break telling them they are violating a design constraint. I personally have had many a devoloper accidentally put dependencies in that we agreed in the design should not be there. This includes myself. This prevents this from happening as long as someone doesn't change the ant build file....If someone does though, at least you can view the package dependencies and now what they are. +</p> + +<h4>Walls attribute......</h4> +<pre> +These next lines would be in build.xml..... + <compilewithwalls walls="dependencies.xml"> + <a href="PUT JAVAC TASK LINK HERE"><javac></javac></a> + </compilewithwalls></pre> + +<pre> +These lines would be in dependencies.xml..... + <walls> + <package name="modA" package="biz.xsoftware.mod.modA.**"/> + <package name="modB" package="biz.xsoftware.mod.modB.*"/> + <package name="mod" package="biz.xsoftware.mod.modA.*" depends="modA,modB"/> + </walls></pre> + + + + +<hr> + <p align="center">Copyright © 2002-2004 Ant-Contrib Project. All + rights Reserved.</p> + +</body> +</html> + diff --git a/docs/manual/tasks/for.html b/docs/manual/tasks/for.html new file mode 100644 index 0000000..ecf23fe --- /dev/null +++ b/docs/manual/tasks/for.html @@ -0,0 +1,198 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Ant-contrib Tasks: For</title> + </head> + + <body> + <h1>For</h1> + + <p>The for task iterates over a list, a list of paths, or + any type that has a public iterator() method. + The list will be evaluated first. + Nested paths are evaluated in the order they + appear in the task. + Nested types will then be evalulated. + </p> + <p> + This task is the same as the <foreach> task, except that + <ul> + <li>it uses a nested sequential for each iteration; and + <li>it implements an additional "keepgoing" attribute. + </ul> + <for> makes use of ant's macrodef task, so the @{} notation + is used for parameter substition. + </p> + <p><em> + This task only works for ant version greater than or equal + to ant 1.6.0. + </em> + </p> + + <h2>Parameters</h2> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">list</td> + <td valign="top">The list of values to process, with the + delimiter character, indicated by the "delimiter" + attribute, separating each value.</td> + <td align="center" valign="top">Yes, unless a nested path + has been specified.</td> + </tr> + <tr> + <td valign="top">param</td> + <td valign="top">Name of the parameter to pass the tokens or + files in as to the sequential.</td> + <td align="center" valign="top">Yes</td> + </tr> + <tr> + <td valign="top">delimiter</td> + <td valign="top">The delimiter characters that separates the + values in the "list" attribute. Each character in the + supplied string can act as a delimiter. This follows the semantics + of the StringTokenizer class.</td> + <td align="center" valign="top">No, defaults to ",".</td> + </tr> + <tr> + <td valign="top">parallel</td> + <td valign="top">If <code>true</code>, all iterations of the nested + <sequential> + will execute in parallel. Defaults to <code>false</code>, + which forces sequential execution of the iterations. It is up to + the caller to ensure that parallel execution is safe. + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">keepgoing</td> + <td valign="top">If <code>true</code>, all iterations of the called + <sequential> will be executed, even if a task in one or more of them fails. + Defaults + to <code>false</code>, which forces execution to stop as soon as a + task fails. At the end, if any iterator has failed, the <for> + task will fail, otherwise <for> will succeed. + <p> + Note that execution does not proceed keepgoing from one task + to the next within the <sequential>, but rather from one iteration to the + next. + </p> + <p>It is up to the caller to ensure that keepgoing execution is safe.</p> + </td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">threadCount</td> + <td valign="top">The maximum number of allowable threads when executing + in parallel. + <td align="center" valign="top">No. Defaults to 5.</td> + </tr> + <tr> + <td valign="top">trim</td> + <td valign="top">If <code>true</code>, any leading or trailing + whitespace will be removed from the list item before it is passed + to the sequential. + </td> + <td align="center" valign="top">No. Defaults to false.</td> + </tr> + </table> + + <h2>Parameters specified as nested elements</h2> + + <a name="path"><h3>path</h3></a> + + <p><a href="http://ant.apache.org/manual/using.html#path">Path</a>s + are used to select sets of files or directories to iterate over.</p> + + <p>Using a path allows you to determine the order by which files + are considered by using + <a href="http://ant.apache.org/manual/CoreTypes/filelist.html">filelist</a>s + or explicit <code>pathelements</code>. You also can specify + whether you want to iterate over files or directories by chosing + either filesets or + <a href="http://ant.apache.org/manual/CoreTypes/dirset.html">dirset</a>s.</p> + <a name="fileset"><h3>fileset</h3></a> + <p><a href="http://ant.apache.org/manual/CoreTypes/fileset.html">FileSet</a>s + are used to select sets of files to iterate over. + </p> + <a name="fileset"><h3>dirset</h3></a> + <p><a href="http://ant.apache.org/manual/CoreTypes/dirset.html">DirSet</a>s + are used to select sets of directories to iterate over. + </p> + + <a name="seqential"><h3>sequential</h3></a> + This is the list of tasks to be run for each iteration of + the list. + <h3>Example</h3> + <p> + To print out the first five letters of the latin alphabet: + </p> + <blockquote> + <pre> +<echo message="The first five letters of the alphabet are:"/> +<for list="a,b,c,d,e" param="letter"> + <sequential> + <echo>Letter @{letter}</echo> + </sequential> +</for> + </pre> + </blockquote> + <p> + A more complicated example to to iterate over a set + of c++ source files and invoke the <cc> task on them: + </p> + <blockquote> + <pre> +<for param="file"> + <path> + <fileset dir="${test.dir}/mains" includes="*.cpp"/> + </path> + <sequential> + <propertyregex override="yes" + property="program" input="@{file}" + regexp=".*/([^\.]*)\.cpp" replace="\1"/> + <mkdir dir="${obj.dir}/${program}"/> + <mkdir dir="${build.bin.dir}"/> + <cc link="executable" objdir="${obj.dir}/${program}" + outfile="${build.bin.dir}/${program}"> + <compiler refid="compiler.options"/> + <fileset file="@{file}"/> + <linker refid="linker-libs"/> + </cc> + </sequential> +</for> + </pre> + </blockquote> + The preceding example will stop as soon as one of the <cc> tasks fails. + If you change the first line of the example to + <pre> <for param="file" keepgoing="true"></pre> + All iterations will be executed, and then <for> will fail if any one + or more of the <cc> tasks failed. + <p> + The following example embeds an outofdate type and iterates over + the sources that are newer than their corresponding targets. + </p> + + <pre> + <ac:for param="xmlfile" xmlns:ac="antlib:net.sf.antcontrib"> + <ac:outofdate> + <ac:sourcefiles> + <ac:fileset dir="${basedir}/xdocs" includes="**/*.xml"/> + </ac:sourcefiles> + <ac:mapper dir="${basedir}/xdocs" + type="glob" from="*.xml" to="${basedir}/docs/*.html"/> + </ac:outofdate> + <ac:sequential> + <echo>Need to generate a target html file from source file @{xmlfile}</echo> + </ac:sequential> + </ac:for> + </pre> + <hr> + <p align="center">Copyright © 2003-2005 Ant-Contrib Project. All + rights Reserved.</p> + + </body> +</html> diff --git a/docs/manual/tasks/foreach.html b/docs/manual/tasks/foreach.html new file mode 100644 index 0000000..d3f6b0b --- /dev/null +++ b/docs/manual/tasks/foreach.html @@ -0,0 +1,145 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Ant-contrib Tasks: Foreach</title> + </head> + + <body> + <h1>Foreach</h1> + + <p>The foreach task iterates over a list, a list of paths, or + both. If both, list and paths, are specified, the list will be + evaluated first. Nested paths are evaluated in the order they + appear in the task.</p> + + <h2>Parameters</h2> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">list</td> + <td valign="top">The list of values to process, with the + delimiter character, indicated by the "delimiter" + attribute, separating each value.</td> + <td align="center" valign="top">Yes, unless a nested Fileset + has been specified.</td> + </tr> + <tr> + <td valign="top">target</td> + <td valign="top">Name of the target to call for each token or + matched file.</td> + <td align="center" valign="top">Yes</td> + </tr> + <tr> + <td valign="top">param</td> + <td valign="top">Name of the parameter to pass the tokens or + files in as to the target.</td> + <td align="center" valign="top">Yes</td> + </tr> + <tr> + <td valign="top">delimiter</td> + <td valign="top">The delimiter characters that separates the + values in the "list" attribute. Each character in the + supplied string can act as a delimiter. This follows the semantics + of the StringTokenizer class.</td> + <td align="center" valign="top">No, defaults to ",".</td> + </tr> + <tr> + <td valign="top">inheritall</td> + <td valign="top">If <code>true</code>, pass all properties to + the called target. Defaults to <code>false</code>.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">inheritrefs</td> + <td valign="top">If <code>true</code>, pass all references to the + the called target. Defaults to <code>false</code>.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">parallel</td> + <td valign="top">If <code>true</code>, all instances of the called + target will execute in parallel. Defaults to <code>false</code>, + which forces sequential execution of the targets. It is up to + the caller to ensure that parallel execution is safe. This is + accomplished through the means of the "parallel" task contained + in the ANT core.</td> + <td align="center" valign="top">No</td> + </tr> + <tr> + <td valign="top">maxThreads</td> + <td valign="top">The maximum number of allowable threads when executing + in parallel.</td> + <td align="center" valign="top">No. Defaults to 5.</td> + </tr> + <tr> + <td valign="top">trim</td> + <td valign="top">If <code>true</code>, any leading or trailing + whitespace will be removed from the list item before it is passed + to the requested target + </td> + <td align="center" valign="top">No. Defaults to false.</td> + </tr> + </table> + + <h2>Parameters specified as nested elements</h2> + + <a name="path"><h3>path</h3></a> + + <p><a href="http://ant.apache.org/manual/using.html#path">Path</a>s + are used to select sets of files or directories to iterate over.</p> + + <p>Using a path allows you to determine the order by which files + are considered by using + <a href="http://ant.apache.org/manual/CoreTypes/filelist.html">filelist</a>s + or explicit <code>pathelements</code>. You also can specify + whether you want to iterate over files or directories by chosing + either filesets or + <a href="http://ant.apache.org/manual/CoreTypes/dirset.html">dirset</a>s.</p> + + <a name="fileset"><h3>fileset</h3></a> + + <p><a href="http://ant.apache.org/manual/CoreTypes/fileset.html">FileSet</a>s + are used to select sets of files to iterate over. <strong>This + element is deprecated, use <a href="#path">nested path elements</a> + instead.</strong></p> + + <h3>param</h3> + + <p>Specifies the properties to set before running the specified + target. See <a href="http://ant.apache.org/manual/CoreTasks/property.html">property</a> + for usage guidelines.</p> + + <h3><a name="reference">reference</a></h3> + + <p>Used to chose references that shall be copied into the new + project, optionally changing their id.</p> + + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">refid</td> + <td valign="top">The id of the reference in the calling project.</td> + <td valign="top" align="center">Yes</td> + </tr> + <tr> + <td valign="top">torefid</td> + <td valign="top">The id of the reference in the called project.</td> + <td valign="top" align="center">No, defaults to the value of + refid.</td> + </tr> + </table> + + <hr> + <p align="center">Copyright © 2002-2004 Ant-Contrib Project. All + rights Reserved.</p> + + </body> +</html> diff --git a/docs/manual/tasks/forget.html b/docs/manual/tasks/forget.html new file mode 100644 index 0000000..59b5d46 --- /dev/null +++ b/docs/manual/tasks/forget.html @@ -0,0 +1,62 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Ant-contrib Tasks: Forget</title> + </head> + + <body> + <h1>Forget</h1> + + <p>The Forget task will execute a set of tasks sequentially as a background + thread. Once the thread is started, control is returned to the calling + target. This is useful in being able to kick off a background server process, + such as a webserver. This allows you to not have to use the <code>parallel</code> + task to start server processes.</p> + + <h2>Parameters</h2> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">daemon</td> + <td valign="top">Should the created thread be a daemon thread. That is, + should the ANT program be allowed to exit if the thread is still + running.</td> + <td align="center" valign="top">No. Defaults to true.</td> + </tr> + </table> + + + <h2>Example</h2> + + + The following code + + <pre> + <code> + <forget> + <exec executeable="${env.CATALINA_HOME}/bin/catalina.bat}"> + <arg line="start -security" /> + </exec> + </forget> + + <waitfor maxwait="1" maxwaitunit="minute" + checkevery="100" checkeveryunit="millisecond"> + <http url="http://localhost:8080" /> + </waitfor> + + </code> + </pre> + + Would start the Tomcat webserver as a background process, then waiting + for the server to become available. + + <hr> + <p align="center">Copyright © 2002-2003 Ant-Contrib Project. All + rights Reserved.</p> + + </body> +</html> diff --git a/docs/manual/tasks/if.html b/docs/manual/tasks/if.html new file mode 100644 index 0000000..e080d22 --- /dev/null +++ b/docs/manual/tasks/if.html @@ -0,0 +1,94 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Ant-contrib Tasks: If</title> + </head> + + <body> + <h1>If</h1> + + <p>Perform some tasks based on whether a given condition holds + true or not.</p> + + <p>This task is heavily based on the Condition framework that can + be found in Ant 1.4 and later, therefore it cannot be used + inconjunction with versions of Ant prior to 1.4. Due to numeruos + bugs in Ant 1.4(.1) that affect this task, we recommend to use Ant + 1.5 or later.</p> + + <h2>Parameters</h2> + + <p>This task doesn't have any attributes, the condition to test is + specified by a nested element - see the documentation of your + <code><condition></code> task (see <a + href="http://ant.apache.org/manual/CoreTasks/condition.html">the + online documentation</a> for example) for a complete list of + nested elements.</p> + + <p>Just like the <code><condition></code> task, only a + single condition can be specified - you combine them using + <code><and></code> or <code><or></code> + conditions.</p> + + <p>In addition to the condition, you can specify three different + child elements, <code><elseif></code>, <code><then></code> and + <code><else></code>. All three subelements are optional. + + Both <code><then></code> and <code><else></code> must not be + used more than once inside the if task. Both are + containers for Ant tasks, just like Ant's + <code><parallel></code> and <code><sequential></code> + tasks - in fact they are implemented using the same class as Ant's + <code><sequential></code> task.</p> + + The <code><elseif></code> behaves exactly like an <code><if></code> + except that it cannot contain the <code><else></code> element + inside of it. You may specify as may of these as you like, and the + order they are specified is the order they are evaluated in. If the + condition on the <code><if></code> is false, then the first + <code><elseif></code> who's conditional evaluates to true + will be executed. The <code><else></code> will be executed + only if the <code><if></code> and all <code><elseif></code> + conditions are false. + + <h2>Example</h2> + +<pre><code> +<if> + <equals arg1="${foo}" arg2="bar" /> + <then> + <echo message="The value of property foo is bar" /> + </then> + <else> + <echo message="The value of property foo is not bar" /> + </else> +</if> +</code></pre> + +<pre><code> +<if> + <equals arg1="${foo}" arg2="bar" /> + <then> + <echo message="The value of property foo is 'bar'" /> + </then> + + <elseif> + <equals arg1="${foo}" arg2="foo" /> + <then> + <echo message="The value of property foo is 'foo'" /> + </then> + </elseif> + + + <else> + <echo message="The value of property foo is not 'foo' or 'bar'" /> + </else> +</if> +</code></pre> + + <hr> + <p align="center">Copyright © 2002-2003 Ant-Contrib Project. All + rights Reserved.</p> + + </body> +</html> diff --git a/docs/manual/tasks/index.html b/docs/manual/tasks/index.html new file mode 100644 index 0000000..8da6784 --- /dev/null +++ b/docs/manual/tasks/index.html @@ -0,0 +1,16 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Ant-Contrib Tasks</title> + </head> + + <frameset cols="25%,75%"> + <frame src="toc.html" name="navFrame"> + <frame src="foreach.html" name="mainFrame"> + </frameset> + <noframes> + <h2>Ant-Contrib Tasks</h2> + + <a href="toc.html">Task List</a> + </noframes> +</html> diff --git a/docs/manual/tasks/inifile.html b/docs/manual/tasks/inifile.html new file mode 100644 index 0000000..d5722a9 --- /dev/null +++ b/docs/manual/tasks/inifile.html @@ -0,0 +1,110 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Ant-contrib Tasks: IniFile</title> + </head> + + <body> + <h1>IniFile</h1> + + <p>Build and Edit Windows .ini files. Only the simple edits, + <code>remove</code> and <code>set</code> are allowed. Set + has limited computation capability which is described later.</p> + + <h2>Parameters</h2> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">source</td> + <td valign="top">The name source .ini file to read in.</td> + <td align="center" valign="top">No.</td> + </tr> + <tr> + <td valign="top">dest</td> + <td valign="top">The name destination .ini file to write.</td> + <td align="center" valign="top">Yes.</td> + </tr> + </table> + + + <h2>Parameters specified as nested elements</h2> + + <code>remove</code> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">section</td> + <td valign="top">The name of the section</td> + <td align="center" valign="top">Yes.</td> + </tr> + <tr> + <td valign="top">property</td> + <td valign="top">The name property.</td> + <td align="center" valign="top">No. If not supplied, the entire + section will be removed</td> + </tr> + </table> + + <code>set</code> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">section</td> + <td valign="top">The name of the section</td> + <td align="center" valign="top">Yes.</td> + </tr> + <tr> + <td valign="top">property</td> + <td valign="top">The name property.</td> + <td align="center" valign="top">Yes.</td> + </tr> + <tr> + <td valign="top">value</td> + <td valign="top">The value to set the property to.</td> + <td align="center" valign="top">No, if + <code>operation</code> is specified.</td> + </tr> + <tr> + <td valign="top">operation</td> + <td valign="top">The operation to perform on the existing value. + Possible values are "+" and "-", which add and subtract 1, + respectively from the existing value. If the value doesn't + already exist, the set is not performed.</td> + <td align="center" valign="top">No, if <code>value</code> + is specified.</td> + </tr> + </table> + + <h2>Example</h2> + + + +<pre><code> + +<inifile source="myprog.ini" dest="myprog.new.ini"> + <set section="Section1" property="release-date" value="${todays.date}" /> + <set section="Section1" property="build-number" operation="+" /> + <remove section="Section2" property="useless" /> + <remove section="OutdatedSection" /> +</inifile> +</code></pre> + + + <hr> + <p align="center">Copyright © 2002-2003 Ant-Contrib Project. All + rights Reserved.</p> + + </body> +</html> diff --git a/docs/manual/tasks/limit_task.html b/docs/manual/tasks/limit_task.html new file mode 100644 index 0000000..fb8f305 --- /dev/null +++ b/docs/manual/tasks/limit_task.html @@ -0,0 +1,280 @@ +<html> +<head> +<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title> +Chapter 10. Limit</title> +<meta content="DocBook XSL Stylesheets V1.60.1" name="generator"> +<link rel="home" href="index.html" title="Antelope Users Guide"> +<link rel="up" href="bk03.html" title="Additional Ant Tasks"> +<link rel="previous" href="bk03ch09.html" title="Chapter 9. Stopwatch"> +<link rel="next" href="bk03ch11.html" title="Chapter 11. Math"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="chapter" lang="en"> +<div class="titlepage"> +<div> +<div> +<h2 class="title"> +<a name="Limit"> +</a> +Limit</h2> +</div> +</div> +<div> +</div> +</div> +<p> + +The Limit task is a task container (that is, it holds other tasks) and sets a time limit on how long the nested tasks are allowed to run. This is useful for unit tests that go awry, hung socket connections, or other potentially long running tasks that need to be shut off without stopping the build. +</p> + +<p> + +<div class="table"> +<a name="N1096A"> +</a> +<p class="title"> +<b> +Table 10.1. Limit Task Attributes</b> +</p> +<table summary="Limit Task Attributes" border="1"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead> +<tr> +<th> +Attribute</th> +<th> +Description</th> +<th> +Default</th> +<th> +Required</th> +</tr> +</thead> +<tbody> +<tr> +<td> +maxwait</td> +<td> +How long to wait for nested tasks to finish.</td> +<td> +180 seconds (3 minutes)</td> +<td> +No</td> +</tr> + +<tr> +<td> +maxwaitunit</td> +<td> +The unit for maxwait. Valid values are "millisecond", "second", "minute", "hour", "day", "week".</td> +<td> +seconds</td> +<td> +No</td> +</tr> + +<tr> +<td> +failonerror</td> +<td> +Should the build fail if the time limit has been exceeded?</td> +<td> +false</td> +<td> +No</td> +</tr> + +<tr> +<td> +property</td> +<td> +The name of a property to set if the max wait time is exceeded.</td> +<td> +none</td> +<td> +No</td> +</tr> + +<tr> +<td> +value</td> +<td> +The value to set for the property if the max wait time is exceeded.</td> +<td> +true</td> +<td> +No</td> +</tr> + +<tr> +<td> +milliseconds</td> +<td> +How long to wait in milliseconds.</td> +<td> +3 minutes</td> +<td> +No</td> +</tr> + +<tr> +<td> +seconds</td> +<td> +How long to wait in seconds.</td> +<td> +3 minutes</td> +<td> +No</td> +</tr> + +<tr> +<td> +minutes</td> +<td> +How long to wait in minutes.</td> +<td> +3 minutes</td> +<td> +No</td> +</tr> + +<tr> +<td> +hours</td> +<td> +How long to wait in hours.</td> +<td> +3 minutes</td> +<td> +No</td> +</tr> + +<tr> +<td> +days</td> +<td> +How long to wait in days.</td> +<td> +3 minutes</td> +<td> +No</td> +</tr> + +<tr> +<td> +weeks</td> +<td> +How long to wait in weeks.</td> +<td> +3 minutes</td> +<td> +No</td> +</tr> + + +</tbody> +</table> +</div> + +</p> +<p> + +Examples: +</p> +<p> + +Neither the echo nor the fail will happen in this example. The build will continue once the time has expired. +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + +<limit maxwait="3"> + <sleep seconds="10"/> + <echo>This won't happen...</echo> + <fail>This won't happen either...</fail> +</limit> + +</pre> +</td> +</tr> +</table> + +</p> +<p> + +This is identical to the above example, but uses the convenience "seconds" attribute: +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + +<limit seconds="3"> + <sleep seconds="10"/> + <echo>This won't happen...</echo> + <fail>This won't happen either...</fail> +</limit> + +</pre> +</td> +</tr> +</table> + +</p> +<p> + +Neither the echo nor the fail will happen in this example. The build will not continue once the time has expired. +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + +<limit maxwait="3" failonerror="true"> + <sleep seconds="10"/> + <echo>This won't happen...</echo> + <fail>This won't happen either...</fail> +</limit> + +</pre> +</td> +</tr> +</table> + +</p> +<p> + +The limit will be reached and a property will be set indicating so. +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + +<limit minutes="3" property="limit_reached"> + <sleep minutes="10"/> + <echo>This won't happen...</echo> + <fail>This won't happen either...</fail> +</limit> +<echo>limit_reached = ${limit_reached)</echo> +</pre> +</td> +</tr> +</table> + +</p> +</div> + <hr> + <p align="center">Copyright © 2003-2004 Ant-Contrib Project. All + rights Reserved.</p> +</body> +</html> diff --git a/docs/manual/tasks/math_task.html b/docs/manual/tasks/math_task.html new file mode 100644 index 0000000..bac6e04 --- /dev/null +++ b/docs/manual/tasks/math_task.html @@ -0,0 +1,405 @@ +<html> +<head> +<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title> +Math</title> +<meta content="DocBook XSL Stylesheets V1.60.1" name="generator"> +<link rel="home" href="index.html" title="Antelope Users Guide"> +<link rel="up" href="bk03.html" title="Additional Ant Tasks"> +<link rel="previous" href="bk03ch10.html" title="Chapter 10. Limit"> +<link rel="next" href="bk03ch12.html" title="Chapter 12. HTTP Post"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="chapter" lang="en"> +<div class="titlepage"> +<div> +<div> +<h2 class="title"> +<a name="math"> +</a> +Math</h2> +</div> +</div> +<div> +</div> +</div> +<p> + +The Math task provides support for all the basic mathematical operations +provided by the java.lang.Math and java.lang.StrictMath classed. It supports int, long, float and double data types. Nesting of operations is supported to allow computation of formulas like (6 + (7.25 * 3.9))/(2 * 3 * 3) or calculating the area of a circle given a radius (I'm sure this comes up often in builds controlled by Ant!). +</p> +<p> + +In addition to the operations provided by the java.lang.Math and java.lang.StrictMath classes, the Math task provides several additional operations: "add", "subtract", "multiply", "divide", and "mod", which duplicate the basic Java mathematical operations "+", "-", "*", "/", and "%", respectively. In fact, either notation can be used, that is, the operation can be set to "add" or "+", depending only on which you feel is more convenient. +</p> + +<p> + +<div class="table"> +<a name="N109AE"> +</a> +<p class="title"> +<b> +Table 11.1. Math Task Attributes</b> +</p> +<table summary="Math Task Attributes" border="1"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead> +<tr> +<th> +Attribute</th> +<th> +Description</th> +<th> +Default</th> +<th> +Required</th> +</tr> +</thead> +<tbody> +<tr> +<td> +result</td> +<td> +The name of the property to hold the result of the operation.</td> +<td> +None</td> +<td> +Yes</td> +</tr> +<tr> +<td> +datatype</td> +<td> +Sets the datatype of the calculation. Allowed values are +"int", "long", "float", or "double". Optional, if +used, will be applied to all numbers in this math operation.</td> +<td> +double</td> +<td> +No</td> +</tr> +<tr> +<td> +strict</td> +<td> +If true, use the methods in the java.lang.StrictMath class.</td> +<td> +false</td> +<td> +No</td> +</tr> +<tr> +<td> +operation</td> +<td> +If used, any nested Ops will be ignored. This is for convenience for simple calculations.</td> +<td> +None</td> +<td> +No</td> +</tr> +<tr> +<td> +operand1</td> +<td> +A number to use with the operation specified in the 'operation' attribute.</td> +<td> +None</td> +<td> +Depends on the specific operation.</td> +</tr> +<tr> +<td> +operand2</td> +<td> +A number to use with the operation specified in the 'operation' attribute.</td> +<td> +None</td> +<td> +Depends on the specific operation.</td> +</tr> +</tbody> +</table> +</div> + +</p> +<p> + +The 'result' property is reusable. +</p> + + +The Math task supports nested "Op" elements. An Op element represents single mathematical operation, such as "min" or "add". +As an alternate, if using Ant 1.5+, you can specify the operation in the tag name itself. However, you must use the text +name (+,-,/,*,% are not permitted as tag names) + +<code><pre> + <radians> + <num value="90" /> + </radians> +</pre></code> + +instead of + +<code><pre> + <op op="radians"> + <num value="90" /> + </op> +</pre></code> + + +<p> + +<div class="table"> +<a name="N109FB"> +</a> +<p class="title"> +<b> +Table 11.2. Op Attributes</b> +</p> +<table summary="Op Attributes" border="1"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead> +<tr> +<th> +Attribute</th> +<th> +Description</th> +<th> +Default</th> +<th> +Required</th> +</tr> +</thead> +<tbody> +<tr> +<td> +op</td> +<td> +Set the name of this operation. Allowed values are +one of the method names from java.lang.Math or java.lang.StrictMath, or one of +"add", "subtract", "multiply", "divide", or "mod" (or "+", "-", "*", "/", or "%", +respectively). "toRadians" and "toDegrees" can be represented by "radians" and +"degrees", respectively, as a shorthand</td> +<td> +None</td> +<td> +Yes, if not specified in the tag name.</td> +</tr> +<tr> +<td> +datatype</td> +<td> +Sets the datatype of this calculation. Allowed values are +"int", "long", "float", or "double". Optional, default +is "double". If the parent Math task has a datatype set, this value will be ignored and the datatype specifed in the task will be used.</td> +<td> +"int"</td> +<td> +No</td> +</tr> + +<tr> +<td> +arg1, arg2, arg3, arg4, arg5/td> +<td> +The arguments for this operation. This is a shorthand to avoid having to use nested +elements when performing a simple calculation. +</td> +<td> +None</td> +<td> +No. However, these attributes are mutually exclusive with the <op> and <num> subelements.</td> +</tr> + +</tbody> +</table> +</div> + +</p> +<p> + +The Op element supports nested "Op" elements and nested "Num" elements. A Num represents a number. +When an Op is nested in another Op, the result of the Op is treated as a Num. The nested elements +can be any combination of Op (short form included as mentioned above) or Num as appropriate for the +formula being calculated. Most of the +operations provided by java.lang.Math and java.lang.StrictMath operate on one or two numbers. +The "+", "-", "*", "/", and "%" operations can task any number of nested numbers. +</p> +<p> + +<div class="table"> +<a name="N10A23"> +</a> +<p class="title"> +<b> +Table 11.3. Num Attributes</b> +</p> +<table summary="Num Attributes" border="1"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead> +<tr> +<th> +Attribute</th> +<th> +Description</th> +<th> +Default</th> +<th> +Required</th> +</tr> +</thead> +<tbody> +<tr> +<td> +value</td> +<td> +Set the value for this number. Must be able to parse to the datatype set by the parent element or the default datatype set by the task. Two special numbers, pi and e, can be represented by PI and E respectively. ("PI" is the ratio of the diameter of a circle to its radius, "E" is Euler's e, the base for natural logrithms.)</td> +<td> +None</td> +<td> +Yes</td> +</tr> +<tr> +<td> +datatype</td> +<td> +Sets the datatype of this number. Allowed values are +"int", "long", "float", or "double". Optional, default +is "double". If the parent Math task has a datatype set, this value will be ignored and the datatype specifed in the task will be used.</td> +<td> +double</td> +<td> +No</td> +</tr> +</tbody> +</table> +</div> + +</p> +<p> + +Some examples: +</p> +<p> + +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + + <var name="op1" value="12"/> + <var name="op2" value="6"/> + <var name="op" value="+"/> + + <!-- demo plus --> + <math result="result" operand1="${op1}" operation="${op}" operand2="${op2}" datatype="int"/> + <echo>${op1} ${op} ${op2} = ${result}</echo> + <assert name="result" value="18"/> + + <!-- demo reusing result --> + <math result="result" operand1="${result}" operation="${op}" operand2="${op2}" datatype="int"/> + <echo>${op1} ${op} ${op2} = ${result}</echo> + <assert name="result" value="24"/> + + <!-- demo minus --> + <var name="op" value="-"/> + <math result="result" operand1="${op1}" operation="${op}" operand2="${op2}" datatype="int"/> + <echo>${op1} ${op} ${op2} = ${result}</echo> + <assert name="result" value="6"/> + + <!-- demo multiply --> + <var name="op" value="*"/> + <math result="result" operand1="${op1}" operation="${op}" operand2="${op2}" datatype="int"/> + <echo>${op1} ${op} ${op2} = ${result}</echo> + <assert name="result" value="72"/> + + <!-- demo divide --> + <var name="op" value="/"/> + <math result="result" operand1="${op1}" operation="${op}" operand2="${op2}" datatype="int"/> + <echo>${op1} ${op} ${op2} = ${result}</echo> + <assert name="result" value="2"/> + + <!-- demo modulo --> + <var name="op" value="%"/> + <math result="result" operand1="${op1}" operation="${op}" operand2="${op2}" datatype="int"/> + <echo>${op1} ${op} ${op2} = ${result}</echo> + <assert name="result" value="0"/> + + <!-- demo calculating the area of a circle --> + <!-- first, calculate the radius --> + <math result="radius"> <!-- defaults to double datatype --> + <op type="*"> + <num value="1"/> + <num value="2"/> + <num value="3"/> + <num value="4"/> + <num value="5"/> + </op> + </math> + <echo> 1 * 2 * 3 * 4 * 5 = ${radius}</echo> + + <!-- now calculate the area --> + <math result="area" precision="float"> + <op type="*"> + <num value="PI"/> + <op type="pow"> + <num value="${radius}"/> + <num value="2"/> + </op> + </op> + </math> + <echo>area = PI * radius ^ 2 = ${area}</echo> + + <!-- demo calculating a random number between 0 and 100 --> + <math result="result"> + <op op="rint"> + <op op="*"> + <num value="100"/> + <op op="random"/> + </op> + </op> + </math> + <echo>a random number between 0 and 100: ${result}</echo> + + <!-- demo another multiplication --> + <math result="result" operation="multiply" operand1="17" operand2="13"/> + <echo>${result}</echo> + + <!-- demo shorthand notation for calculating sin of an angle, which is degrees --> + <math result="sin"> + <sin> + <radians arg1="${angle_in_degrees}" /> + </sin> + </math> + <echo>${sin}</echo> + +</pre> +</td> +</tr> +</table> + +</p> +</div> + <hr> + <p align="center">Copyright © 2003 Ant-Contrib Project. All + rights Reserved.</p> +</body> +</html> diff --git a/docs/manual/tasks/more_conditions.html b/docs/manual/tasks/more_conditions.html new file mode 100644 index 0000000..5c64602 --- /dev/null +++ b/docs/manual/tasks/more_conditions.html @@ -0,0 +1,461 @@ +<html> +<head> +<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title> +More Conditions</title> +<meta content="DocBook XSL Stylesheets V1.60.1" name="generator"> +<link rel="home" href="index.html" title="Antelope Users Guide"> +<link rel="up" href="bk03ch05.html" title="Chapter 5. If Task"> +<link rel="previous" href="bk03ch05.html" title="Chapter 5. If Task"> +<link rel="next" href="bk03ch06.html" title="Chapter 6. SwitchTask"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="section" lang="en"> +<div class="titlepage"> +<div> +<div> +<h2 class="title" style="clear: both"> +<a name="conditionals"> +</a> +More Conditions</h2> +</div> +</div> +<div> +</div> +</div> +<p> + +These conditions are suitable for use in the <bool> element. Unfortunately, they cannot be used in the <condition> task, although all conditions for the <condition> task can be used with the <bool> and the <bool> can be used anywhere that <condition> can be used. +</p> +<h4> +<a name="N10708"> +</a> +IfPropertyTrue</h4> +<p> + +Given a property name, tests whether the value for that property equals "true" (or "yes" or "on"). +</p> +<p> + +<div class="table"> +<a name="N1070F"> +</a> +<p class="title"> +<b> +Table 5.2. IfPropertyTrue Attributes</b> +</p> +<table summary="IfPropertyTrue Attributes" border="1"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead> +<tr> +<th> +Attribute</th> +<th> +Description</th> +<th> +Required</th> +</tr> +</thead> +<tbody> +<tr> +<td> +property</td> +<td> +The name of a property to test the value of.</td> +<td> +Yes</td> +</tr> +</tbody> +</table> +</div> + +</p> +<p> + +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + +<ispropertytrue property="myprop"/> +<ispropertytrue property="${someprop}"/> + +</pre> +</td> +</tr> +</table> + +</p> +<h4> +<a name="N1072C"> +</a> +IfPropertyFalse</h4> +<p> + +Given a property name, tests whether the value for that property equals "false" (or "no" or "off"). +</p> +<p> + +<div class="table"> +<a name="N10733"> +</a> +<p class="title"> +<b> +Table 5.3. IfPropertyFalse Attributes</b> +</p> +<table summary="IfPropertyFalse Attributes" border="1"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead> +<tr> +<th> +Attribute</th> +<th> +Description</th> +<th> +Required</th> +</tr> +</thead> +<tbody> +<tr> +<td> +property</td> +<td> +The name of a property to test the value of.</td> +<td> +Yes</td> +</tr> +</tbody> +</table> +</div> + +</p> +<p> + +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + +<ispropertyfalse property="myprop"/> +<ispropertyfalse property="${someprop}"/> + +</pre> +</td> +</tr> +</table> + +</p> +<h4> +<a name="N10750"> +</a> +StartsWith</h4> +<p> + +Given a property name, tests whether the value for that property starts with a specified string. +</p> +<p> + +<div class="table"> +<a name="N10757"> +</a> +<p class="title"> +<b> +Table 5.4. StartsWith Attributes</b> +</p> +<table summary="StartsWith Attributes" border="1"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead> +<tr> +<th> +Attribute</th> +<th> +Description</th> +<th> +Required</th> +</tr> +</thead> +<tbody> +<tr> +<td> +string</td> +<td> +The string to test.</td> +<td> +Yes</td> +</tr> +<tr> +<td> +with</td> +<td> +Check if 'string' starts with this value.</td> +<td> +Yes</td> +</tr> +</tbody> +</table> +</div> + +</p> +<p> + +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + +<startswith string="abcdefg" with="abc"/> +<startswith string="${myprop}" with="foo"/> + +</pre> +</td> +</tr> +</table> + +</p> +<h4> +<a name="N1077B"> +</a> +EndsWith</h4> +<p> + +Given a property name, tests whether the value for that ends with with a specified string. +</p> +<p> + +<div class="table"> +<a name="N10782"> +</a> +<p class="title"> +<b> +Table 5.5. EndsWith Attributes</b> +</p> +<table summary="EndsWith Attributes" border="1"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead> +<tr> +<th> +Attribute</th> +<th> +Description</th> +<th> +Required</th> +</tr> +</thead> +<tbody> +<tr> +<td> +string</td> +<td> +The string to test.</td> +<td> +Yes</td> +</tr> +<tr> +<td> +with</td> +<td> +Check if 'string' ends with this value.</td> +<td> +Yes</td> +</tr> +</tbody> +</table> +</div> + +</p> +<p> + +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + +<endswith string="abcdefg" with="efg"/> +<endswith string="${myprop}" with="bar"/> + +</pre> +</td> +</tr> +</table> + +</p> +<h4> +<a name="N107A6"> +</a> +IsGreaterThan</h4> +<p> + +Tests whether the first argument is greater than the second argument. Will +automatically treat the arguments as numbers if both arguments consists of only the characters 0 through 9 and optionally a decimal point. Otherwise, a String +comparison is used. +</p> +<p> + +<div class="table"> +<a name="N107AD"> +</a> +<p class="title"> +<b> +Table 5.6. IsGreaterThan Attributes</b> +</p> +<table summary="IsGreaterThan Attributes" border="1"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead> +<tr> +<th> +Attribute</th> +<th> +Description</th> +<th> +Required</th> +</tr> +</thead> +<tbody> +<tr> +<td> +arg1</td> +<td> +The first argument.</td> +<td> +Yes</td> +</tr> +<tr> +<td> +arg2</td> +<td> +The second argument.</td> +<td> +Yes</td> +</tr> +</tbody> +</table> +</div> + +</p> +<p> + +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + +<!-- evaluates to true --> +<isgreaterthan arg1="6.02" arg2="4"/> + +<!-- evaluates to false --> +<isgreaterthan arg1="bar" arg2="foo"/> + +</pre> +</td> +</tr> +</table> + +</p> +<h4> +<a name="N107D1"> +</a> +IsLessThan</h4> +<p> + +Tests whether the first argument is less than the second argument. Will +automatically treat the arguments as numbers if both arguments consists of only the characters 0 through 9 and optionally a decimal point. Otherwise, a String +comparison is used. +</p> +<p> + +<div class="table"> +<a name="N107D8"> +</a> +<p class="title"> +<b> +Table 5.7. IsLessThan Attributes</b> +</p> +<table summary="IsLessThan Attributes" border="1"> +<colgroup> +<col> +<col> +<col> +</colgroup> +<thead> +<tr> +<th> +Attribute</th> +<th> +Description</th> +<th> +Required</th> +</tr> +</thead> +<tbody> +<tr> +<td> +arg1</td> +<td> +The first argument.</td> +<td> +Yes</td> +</tr> +<tr> +<td> +arg2</td> +<td> +The second argument.</td> +<td> +Yes</td> +</tr> +</tbody> +</table> +</div> + +</p> +<p> + +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + +<!-- evaluates to false --> +<islessthan arg1="6.02" arg2="4"/> + +<!-- evaluates to true --> +<islessthan arg1="bar" arg2="foo"/> + +</pre> +</td> +</tr> +</table> + +</p> +</div> + <hr> + <p align="center">Copyright © 2003 Ant-Contrib Project. All + rights Reserved.</p> +</body> +</html> diff --git a/docs/manual/tasks/osfamily.html b/docs/manual/tasks/osfamily.html new file mode 100644 index 0000000..e56bdaf --- /dev/null +++ b/docs/manual/tasks/osfamily.html @@ -0,0 +1,36 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Ant-contrib Tasks: Osfamily</title> + </head> + + <body> + <h1>Osfamily</h1> + + <p>Task definition for the <code>OsFamily</code> task. This task + sets the property indicated in the "property" attribute + with the string representing the operating system family. + Possible values include "unix", "dos", + "mac", "os/2", "os/400", + "z/os", "tandem" and "windows".</p> + + <h2>Parameters</h2> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">property</td> + <td valign="top">The name of the property to set with the OS + family name.</td> + <td align="center" valign="top">Yes.</td> + </tr> + </table> + <hr> + <p align="center">Copyright © 2002-2003 Ant-Contrib Project. All + rights Reserved.</p> + + </body> +</html> diff --git a/docs/manual/tasks/outofdate.html b/docs/manual/tasks/outofdate.html new file mode 100644 index 0000000..adffa19 --- /dev/null +++ b/docs/manual/tasks/outofdate.html @@ -0,0 +1,326 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8"> + <TITLE>Ant-contrib Tasks: OutOfDate</TITLE> + <META NAME="GENERATOR" CONTENT="OpenOffice.org 644 (Linux)"> + <META NAME="CREATED" CONTENT="20030314;12023500"> + <META NAME="CHANGED" CONTENT="20030319;15211400"> +</HEAD> +<BODY LANG="en-US" DIR="LTR"> +<H1>OutOfDate</H1> +<P>Task definition for the <CODE>outofdate</CODE> task. This is an +extension of uptodate which allows multible targets and contains an +embedded <parallel> or <sequential> element. If any of +the target file's dates are earlier than any of the source file's +dates, then the specified <parallel> or <sequential> +block is executed. The task may also contain mappers to map source +files to corresponding target files. +</P> +<H2>Parameters</H2> +<TABLE WIDTH=100% BORDER=1 CELLPADDING=2 CELLSPACING=0> + <COL WIDTH=0> + <COL WIDTH=0> + <COL WIDTH=0> + <TR> + <TH> + <P>Attribute</P> + </TH> + <TH> + <P>Description</P> + </TH> + <TH> + <P>Required</P> + </TH> + </TR> + <TR VALIGN=TOP> + <TD> + <P>property</P> + </TD> + <TD> + <P>The name of the property to set to the contents of the <CODE>value</CODE> + parameter if any of the target files are out of date</P> + </TD> + <TD> + <P ALIGN=LEFT>No</P> + </TD> + </TR> + <TR VALIGN=TOP> + <TD> + <P>value</P> + </TD> + <TD> + <P>The value to set the property specified by the parameter + <CODE>property</CODE> to, if any of the target files are out of + date</P> + </TD> + <TD> + <P ALIGN=LEFT>No, defaults to "true"</P> + </TD> + </TR> + <tr> + <td valign="top">force</td> + <td valign="top"> + Force outofdate ("true"/"false"). Default is "false". + </td> + <td valign="top">No</td> + </tr> + <tr> + <td valign="top">verbose</td> + <td valign="top"> + Set vebose logging level for this task ("true"/"false"). + Default is "false". + </td> + <td valign="top">No</td> + </tr> + <TR VALIGN=TOP> + <TD> + <P>outputsources</P> + </TD> + <TD> + <P>The name of a property to set containing the sources that are + newer that their corresponding targets.</P> + </TD> + <TD> + <P ALIGN=LEFT>No</P> + </TD> + </TR> + <TR VALIGN=TOP> + <TD> + <P>outputtargets</P> + </TD> + <TD> + <P>The name of a property to set containing the targets that are + outofDate with respect to their corresponding sources.</P> + </TD> + <TD> + <P ALIGN=LEFT>No</P> + </TD> + </TR> + <TR VALIGN=TOP> + <TD> + <P>alltargets</P> + </TD> + <TD> + <P>The name of a property to set containing all the targets. This + is usefull for debugging mapper nested elements.</P> + </TD> + <TD> + <P ALIGN=LEFT>No</P> + </TD> + </TR> + <TR VALIGN=TOP> + <TD> + <P>separator</P> + </TD> + <TD> + <P>The separator used to separate the files in the properties + above. If a filename contains the separator, double quotes will be + placed aroudnd the filename.</P> + </TD> + <TD> + <P ALIGN=LEFT>No, defaults to “ “</P> + </TD> + </TR> + <TR VALIGN=TOP> + <TD> + <P>outputsourcespath</P> + </TD> + <TD> + <P>The id of a path to create containing the source files that are + outofdate.</P> + </TD> + <TD> + <P ALIGN=LEFT>No</P> + </TD> + </TR> + <TR VALIGN=TOP> + <TD> + <P>outputtargetspath</P> + </TD> + <TD> + <P>The id of a path to create containing the target files that + need to be updated.</P> + </TD> + <TD> + <P ALIGN=LEFT>No</P> + </TD> + </TR> + <TR VALIGN=TOP> + <TD> + <P>alltargetspath</P> + </TD> + <TD> + <P>The id of a path to create containing all the target files. + </P> + </TD> + <TD> + <P ALIGN=LEFT>No</P> + </TD> + </TR> +</TABLE> +<H2>Attributes specified as nested elements</H2> + +<P><B>sourcefiles</B> - The list of files which are source files. +This element is required. +<BR><BR><B>targetfiles</B> - The list of +files which are target files. +</P> +<P>Both of these nested elements are <A HREF="http://ant.apache.org/manual/using.html#path">Path</A> +elements which are are used to select sets or lists of files or +directories</P> + <p>The <i>sourcefiles</i> may contain no files. In this case, outofdate will + check the existance of the <i>targetfiles</i>.</p> +<P><B>mapper –</B> This is used to map source files to target +files.</P> +As well as the regular attributes for mapper, there is a extra attribute to specify + the relative directory of the sources.<p> + <table cellspacing="0" cellpadding="2" border="1"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">dir</td> + <td valign="top"> + The directory to the sources are relative to for the mapper. + Default is ${base.dir}. + </td> + <td valign="top">No</td> + </tr> + </table> + +<P>There may be a number of mapper nested elements. +<P><B>deletetargets –</B> This is used to delete targets if the +corresponding sources are outofdate. +</P> + <table cellspacing="0" cellpadding="2" border="1"> + <tr> + <td valign="top"><b>Attribute</b></td> + <td valign="top"><b>Description</b></td> + <td valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">all</td> + <td valign="top"> + Whether to delete all the targets ("true"/"false"). Defaults to + "false". + </td> + <td valign="top">No</td> + </tr> + <tr> + <td valign="top">quiet</td> + <td valign="top"> + Do not display diagnostic messages when deleting targets + ("true"/ "false"). Defaults to false. + When set to "true", if a file or directory cannot be deleted, + no error is reported. This setting emulates the -f option to + the Unix rm command. Default is "false". + Setting this to "true" implies setting failonerror to "false" + </td> + <td valign="top">No</td> + </tr> + <tr> + <td valign="top">failonerror</td> + <td valign="top"> + Controls whether an error (such as a failure to delete a file) + stops the build or is merely reported to the screen. + Only relevant if quiet is "false". + Default is "true". + Controls whether a failure to delete a target stops + the build or is merely reported to the screen. + </td> + <td valign="top">No</td> + </tr> + </table> + +</P> +<H2>Examples</H2> +<P>The following example creates the file ${jrun.file} if is older +that build.xml, or any file in ${lib.dir}.</P> +<PRE> <outofdate> + <sourcefiles> + <pathelement path="build.xml"/> + <fileset dir="${lib.dir}"/> + </sourcefiles> + <targetfiles path="${jrun.file}"/> + <sequential> + <mkdir dir="${build.bin.dir}"/> + <echo file="${jrun.file}" message="java -cp ${jrun.path} $*"/> + <chmod file="${jrun.file}" perm="ugo+rx"/> + </sequential> + </outofdate> </PRE><P> +The following example check the generated files, MODULE.IDS, +acme_agent_mib.h, acme_agent_mib.cpp are older that miblist.txt, or +any file in ${mib.src}, and if so an embedded shellScript is invoked +to update the files.</P> +<PRE> <outofdate> + <sourcefiles> + <pathelement path="${agent.src}/miblist.txt"/> + <fileset dir="${mib.src}"/> + </sourcefiles> + <targetfiles> + <pathelement path="${rep}/MODULE.IDS"/> + <pathelement path="${gen-agent}/acme_agent_mib.h"/> + <pathelement path="${gen-agent}/acme_agent_mib.cpp"/> + </targetfiles> + <sequential> + <shellscript shell="bash" dir="${agent.src}"> + classname=com.agentpp.agentgen.AgentGenConsole + h1=${gen-agent}/acme_agent_mib.x + ag() { + java -cp ${lib.dir}/agentgen.jar $classname ${rep} $@ + } + ag initialize + ag load miblist.txt + ag generate ACME-AGENT-MIB h > $h1 + (head -16 $h1; echo "using namespace Agentpp;"; + tail +16 $h1) > ${gen-agent}/acme_agent_mib.h + ag generate ACME-AGENT-MIB c >\ + ${gen-agent}/acme_agent_mib.cpp + </shellscript> + </sequential> + </outofdate></PRE><P> +The following example sets the project <I>manual.outofdate</I> if any +of the xml files are newer than index.html, or if any of the xml +files are newer than their corresponding .html file. A path +identified by <I>sources.path</I>, is created which contains the +sources that fullfilled these conditions.</P> +<PRE> + <outofdate property="manual.outofdate" outputsourcespath="sources.path"> + <sourcefiles> + <fileset dir="${src.manual}" includes="**/*.xml"/> + </sourcefiles> + <targetfiles path="${doc.manual}/index.html"/> + <mapper type="glob" dir="${src.manual}" from="*.xml" to="${doc.manual}/*.html"/> + </outofdate> +</PRE> +<P> +The following assumes that there is a program called <I>gengrammer</I> +that takes a grammer file as an input and generates a .h and a .c +file in the current directory.</P> +<PRE> + <outofdate property="manual.outofdate" + outputsources="grammer.sources"> + <sourcefiles> + <fileset dir="${src.grammer}" includes="**/*.y"/> + </sourcefiles> + <mapper type="glob" dir="${src.grammer}" from="*.y" to="${gen.grammer}/*.c"/> + <mapper type="glob" dir="${src.grammer}" from="*.y" to="${gen.grammer}/*.h"/> + <sequential> + <shellscript shell="bash"> + cd ${gen.grammer} + for g in ${grammer.sources} + do + gengrammer $g + done + </shellscript> + </sequential> + </outofdate> +</PRE> +<HR> +<P ALIGN=CENTER>Copyright © 2003 Ant-Contrib Project. All rights +Reserved.</P> +</BODY> +</HTML>
\ No newline at end of file diff --git a/docs/manual/tasks/pathtofileset.html b/docs/manual/tasks/pathtofileset.html new file mode 100644 index 0000000..52e9cb7 --- /dev/null +++ b/docs/manual/tasks/pathtofileset.html @@ -0,0 +1,73 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Ant-contrib Tasks: Pathtofileset</title> + </head> + + <body> + <h1>Pathtofileset</h1> + + <p>Coverts a path to a fileset. This is usefull if you have + a path but need to use a fileset as input in a ant task. + </p> + + <h2>Parameters</h2> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">dir</td> + <td valign="top">The root of the directory tree of this FileSet</td> + <td align="center" valign="top">Yes</td> + </tr> + <tr> + <td valign="top">pathrefid</td> + <td valign="top">The reference to the path to convert from</td> + <td align="center" valign="top">Yes</td> + </tr> + <tr> + <td valign="top">ignorenonrelative</td> + <td valign="top">This boolean controls what will happen if any of the + files in the path are not in the directory for the fileset. If this + is "true" the files are ignored, if this is "false" a build exception + is thrown. (Note: if files are not present no check is made). + </td> + <td align="center" valign="top">No, default is "false"</td> + </tr> + <tr> + <td valign="top">name</td> + <td valign="top">This is the identifier of the fileset to create. This + fileset will contain the files that are relative to the directory root. + Any files that are not present will not be placed in the set. + </td> + <td align="center" valign="top">Yes</td> + </tr> + </table> + </body> + <h2>Example</h2> + <pre> + <outofdate outputsourcespath="modified.sources.path"> + <sourcefiles> + <fileset dir="a/b/c" includes="**/*.java"/> + </sourcefiles> + <mapper dir="a/b/c" type="glob" from="*.java" to="output/*.xml"/> + <sequential> + <pathtofileset name="modified.sources.fileset" + pathrefid="modified.sources.path" + dir="a/b/c"/> + <copy todir="output"> + <fileset refid="modified.sources.fileset"/> + <mapper type="glob" from="*.java" to="*.xml"/> + </copy> + </sequential> + </outofdate> + </pre> + + <hr> + <p align="center">Copyright © 2003 Ant-Contrib Project. All + rights Reserved.</p> + +</html> diff --git a/docs/manual/tasks/performance_monitor.html b/docs/manual/tasks/performance_monitor.html new file mode 100644 index 0000000..3f92c80 --- /dev/null +++ b/docs/manual/tasks/performance_monitor.html @@ -0,0 +1,159 @@ +<html> +<head> +<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title> +Performance Monitoring</title> +<meta content="DocBook XSL Stylesheets V1.60.1" name="generator"> +<link rel="home" href="index.html" title="Antelope Users Guide"> +<link rel="up" href="bk03.html" title="Additional Ant Tasks"> +<link rel="previous" href="bk03ch16.html" title="Chapter 16. Call Task"> +<link rel="next" href="bk03ch18.html" title="Chapter 18. Feedback"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="chapter" lang="en"> +<div class="titlepage"> +<div> +<div> +<h2 class="title"> +<a name="performance"> +</a> +Performance Monitoring</h2> +</div> +</div> +<div> +</div> +</div> +<p> + +The "Performance Monitor" is +a special Ant listener than can keep track of the amount of time that each target +and task takes to execute. At the end of the build, these times will be sorted +from fastest to slowest and displayed following the build output. This can be +useful to pinpoint slow and/or inefficient spots in the build process and +identify those areas that could benefit from optimization. +</p> +<p> + +The performance listener can be used by passing a parameter +to the command line for Ant: +</p> +<p> + +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + + ant -listener net.sf.antcontrib.perf.AntPerformanceListener target + +</pre> +</td> +</tr> +</table> + +</p> +<p> + +Following is an example of the results from using the listener. The result format is projectname.targetname for targets and projectname.targetname.taskname for tasks. All times are shown to the nearest millisecond. +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + +[danson@blackdog antelope]$ ant -listener net.sf.antcontrib.perf.AntPerformanceListener dist +Buildfile: build.xml + +init: + +clean: + [delete] Deleting 170 files from /home/danson/apps/antelope/build + +compile: + [javac] Compiling 61 source files to /home/danson/apps/antelope/build + +all: + +-build_number: + +prep_files: + [delete] Deleting 3 files from /home/danson/apps/antelope/config + [copy] Copying 3 files to /home/danson/apps/antelope/config + +combined: + [echo] basedir = /home/danson/apps/antelope + [jar] Building jar: /home/danson/apps/antelope/Antelope_1.208.jar + +dist: + [delete] Deleting 4 files from /home/danson/apps/antelope/dist + [zip] Building zip: /home/danson/apps/antelope/dist/Antelope_1.208.zip + [echo] Created zip file. + +-zip_docs: + [zip] Building zip: /home/danson/apps/antelope/dist/Antelope_docs_1.208.zip + [echo] Zipped docs to Antelope_docs_1.208.zip. + +-zip_tasks: + [jar] Building jar: /tmp/Antelope_tasks_1.208.jar + [zip] Building zip: /home/danson/apps/antelope/dist/Antelope_tasks_1.208.zip + [delete] Deleting: /tmp/Antelope_tasks_1.208.jar + [echo] Zipped tasks to Antelope_tasks_1.208.zip. + [copy] Copying 1 file to /home/danson/apps/antelope/dist + +BUILD SUCCESSFUL +Total time: 8 seconds + +-------------- Target Results ----------------------- +Antelope.all: 0.000 sec +Antelope.init: 0.011 sec +Antelope.-build_number: 0.014 sec +Antelope.clean: 0.233 sec +Antelope.-zip_tasks: 0.297 sec +Antelope.prep_files: 0.311 sec +Antelope.-zip_docs: 0.546 sec +Antelope.combined: 1.290 sec +Antelope.compile: 1.724 sec +Antelope.dist: 2.162 sec + +-------------- Task Results ----------------------- +Antelope.init.mkdir: 0.000 sec +Antelope.init.mkdir: 0.001 sec +Antelope.dist.echo: 0.002 sec +Antelope.prep_files.delete: 0.004 sec +Antelope.combined.echo: 0.005 sec +Antelope.dist.delete: 0.006 sec +Antelope.-zip_tasks.echo: 0.007 sec +Antelope.dist.copy: 0.011 sec +Antelope.-build_number.buildnumber: 0.014 sec +Antelope.compile.copy: 0.016 sec +Antelope.prep_files.copy: 0.020 sec +Antelope.prep_files.replace: 0.071 sec +Antelope.-zip_tasks.zip: 0.122 sec +Antelope.-zip_tasks.jar: 0.161 sec +Antelope.prep_files.replace: 0.216 sec +Antelope.clean.delete: 0.233 sec +Antelope.dist.antcall: 0.421 sec +Antelope.-zip_docs.zip: 0.540 sec +Antelope.dist.antcall: 0.685 sec +Antelope.dist.zip: 1.036 sec +Antelope.combined.jar: 1.284 sec +Antelope.compile.javac: 1.708 sec + +-------------- Totals ----------------------- +Start time: Thu, 5 Dec 2002 17:18:30 +Stop time: Thu, 5 Dec 2002 17:18:39 +Total time: 8.476 sec + +</pre> +</td> +</tr> +</table> + +</p> +</div> + <hr> + <p align="center">Copyright © 2003 Ant-Contrib Project. All + rights Reserved.</p> +</body> +</html> diff --git a/docs/manual/tasks/post_task.html b/docs/manual/tasks/post_task.html new file mode 100644 index 0000000..3be383c --- /dev/null +++ b/docs/manual/tasks/post_task.html @@ -0,0 +1,366 @@ +<html> +<head> +<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title> +HTTP Post</title> +<meta content="DocBook XSL Stylesheets V1.60.1" name="generator"> +<link rel="home" href="index.html" title="Antelope Users Guide"> +<link rel="up" href="bk03.html" title="Additional Ant Tasks"> +<link rel="previous" href="bk03ch11.html" title="Chapter 11. Math"> +<link rel="next" href="bk03ch13.html" title="Chapter 13. SSH and SCP"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="chapter" lang="en"> +<div class="titlepage"> +<div> +<div> +<h2 class="title"> +<a name="post"> +</a> +HTTP Post</h2> +</div> +</div> +<div> +</div> +</div> +<p> +The Post task is a companion to the standard Ant "Get" task. This task does a post and does not necessarily expect anything in return. Almost always, there will be some sort of returned data, this can be logged or written to a file if needed. +</p> +<p> +Basically, an HTTP POST sends name/value pairs to a web server. A very common usage is for html forms for submitting data. A typical use of this task is to send data to a servlet for updating a web page with the status of a build. +</p> +<p> +This task handles cookies correctly, which is useful for websites that set a session id to track logins or whatever. This means that if you do several posts in a row, cookies gathered from the first post will be returned with subsequent posts. +</p> +<p> +The Post task has three ways of specifying the data to be posted. Nested "prop" elements can be used. A "prop" element represents a single name/value pair. The second way is to specify a property file as an attribute to the Post. All properties from the file will be sent as part of the Post data. The third way is to just type in some defined Ant properties. Is it allowed to use all three ways at once, that is, read some properties from a file, specify others via "prop" elements, and just type in some Ant properties. +</p> +<p> + +<div class="table"> +<a name="N10A61"> +</a> +<p class="title"> +<b> +Table 12.1. Post Task Attributes</b> +</p> +<table summary="Post Task Attributes" border="1"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead> +<tr> +<th> +Attribute</th> +<th> +Description</th> +<th> +Default</th> +<th> +Required</th> +</tr> +</thead> +<tbody> +<tr> +<td> +to</td> +<td> +The URL of the remote server to send the post.</td> +<td> +None</td> +<td> +Yes</td> +</tr> +<tr> +<td> +encoding</td> +<td> +Character encoding for the name/value pairs.</td> +<td> +UTF-8</td> +<td> +No</td> +</tr> +<tr> +<td> +logfile</td> +<td> +The name of a file to write any response to. Ignored if wantresponse is set to false.</td> +<td> +None</td> +<td> +No</td> +</tr> +<tr> +<td> +property</td> +<td> +The name of a property to write any response to. Ignored if wantresponse is set to false. +</td> +<td> +None</td> +<td> +No</td> +</tr> +<tr> +<td> +append</td> +<td> +Should an existing log file be appended to or overwritten?</td> +<td> +True, append to an existing file.</td> +<td> +No</td> +</tr> +<tr> +<td> +file</td> +<td> +A file to read POST data from. All Ant properties contained in this file will be resolved (that is, ${} syntax will be expanded to their values) prior to sending the file contents.</td> +<td> +None</td> +<td> +No</td> +</tr> +<tr> +<td> +rawFile</td> +<td> +Should the file be trated as raw file instead of property-like file. True - send the content of the file directly to http-post, all properties set by 'property' are ignored!<br/> +Has only impact when the property 'file' is specified.</td> +<td> +False, treat file as property-like</td> +<td> +No</td> +</tr> +<tr> +<tr> +<td> +rawFileNoEncoding</td> +<td> +Don't encode the raw file prior to sending http post request.<br/> +Has only impact when the property 'rawFile' is specified.</td> +<td> +False, http-encode the content of the file</td> +<td> +No</td> +</tr> +<tr> +<td> +maxwait</td> +<td> +The maximum amount of time in seconds to wait for the data to be sent or for a response from the remote server. Setting this to zero means wait forever.</td> +<td> +180 (3 minutes)</td> +<td> +No</td> +</tr> +<tr> +<td> +wantresponse</td> +<td> +Whether to wait for a response from the remote server or not. In many cases this can greatly improve the performance of the build script as the server response may be large and useless to the script. Use this with caution - while the response from the server may not be required for the client, the server may require that the client accept the response prior to processing the post data.</td> +<td> +true</td> +<td> +No</td> +</tr> +<tr> +<td> +failonerror</td> +<td> +Whether the build should fail if the post fails.</td> +<td> +false</td> +<td> +No</td> +</tr> +</tbody> +</table> +</div> + +</p> +<p> + +Post supports nested "prop" elements. As an HTTP POST basically sends a list of names and values, the "prop" element represents one name/value pair. A Post may contain any number of "prop" elements. +</p> +<p> + +<div class="table"> +<a name="N10ABF"> +</a> +<p class="title"> +<b> +Table 12.2. Prop Attributes</b> +</p> +<table summary="Prop Attributes" border="1"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead> +<tr> +<th> +Attribute</th> +<th> +Description</th> +<th> +Default</th> +<th> +Required</th> +</tr> +</thead> +<tbody> +<tr> +<td> +name</td> +<td> +The name of a property to post.</td> +<td> +None</td> +<td> +Yes</td> +</tr> +<tr> +<td> +value</td> +<td> +The value associated with the name.</td> +<td> +None</td> +<td> +No</td> +</tr> +</tbody> +</table> +</div> + +</p> +<p> + +The "value" attribute is not strictly required. This provides a short-cut method in cases where the property data is an already-defined Ant property. Suppose the build file has this property defined: +</p> +<p> + +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + + <property name="src.dir" value="/home/user/project/src"/> + +</pre> +</td> +</tr> +</table> + +</p> +<p> + +Then the following are equivalent: +</p> +<p> + +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + + <prop name="src.dir"/> + <prop name="src.dir" value="${src.dir}"/> + <prop name="src.dir" value="/home/user/project/src"/> + +</pre> +</td> +</tr> +</table> + +</p> +<p> + +Defined Ant properties can be entered directly into the post element. Again, suppose the build file has this property defined: +</p> +<p> + +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + + <property name="src.dir" value="/home/user/project/src"/> + +</pre> +</td> +</tr> +</table> + +</p> +<p> + +Then the following are equivalent: +</p> +<p> + +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + + ${src.dir} + <prop name="src.dir"/> + <prop name="src.dir" value="${src.dir}"/> + <prop name="src.dir" value="/home/user/project/src"/> + +</pre> +</td> +</tr> +</table> + +</p> +<p> + +I googled for the URL in the following example. +</p> +<p> + +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + + <property name="test.val" value="here's my test value"/> + <property name="test.val2" value="second test value"/> + <post to="http://wwwj.cs.unc.edu:8888/tang/servlet/tangGetPostServlet" + verbose="true"> + <prop name="prop1" value="val1 ${test.val}"/> + <prop name="prop2" value="val1 value 2"/> + <prop name="prop3" value="val got some spaces %funky ^$* chars"/> + <prop name="prop4" value="&amp; do an ampersand like this &amp;amp; or + Ant will whine"/> + <prop name="thanks" value="dude, thanks for the echo server!"/> + <prop name="test.val"/> + ${test.val2} + </post> + +</pre> +</td> +</tr> +</table> + +</p> +</div> + <hr> + <p align="center">Copyright © 2003 Ant-Contrib Project. All + rights Reserved.</p> +</body> +</html> diff --git a/docs/manual/tasks/propertycopy.html b/docs/manual/tasks/propertycopy.html new file mode 100644 index 0000000..e24358a --- /dev/null +++ b/docs/manual/tasks/propertycopy.html @@ -0,0 +1,69 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Ant-contrib Tasks: Propertycopy</title> + </head> + + <body> + <h1>Propertycopy</h1> + + <p>Copies the value of a named property to another property. This + is useful when you need to plug in the value of another property + in order to get a property name and then want to get the value of + that property name.</p> + + <h2>Parameters</h2> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">property</td> + <td valign="top">The name of the property to set.</td> + <td align="center" valign="top">Yes.</td> + </tr> + <tr> + <td valign="top">override</td> + <td valign="top">If the property is already set, should we change it's value. + Can be <code>true</code> or <code>false</code></td> + <td align="center" valign="top">No. Defaults to <code>false</code></td> + </tr> + <tr> + <td valign="top">name <i>Deprecated</i></td> + <td valign="top">The name of the property to set.</td> + <td align="center" valign="top">No. Use the <code>property</code> attribute + instead</td> + </tr> + <tr> + <td valign="top">from</td> + <td valign="top">The name of the property you wish to copy the + value from.</td> + <td align="center" valign="top">Yes.</td> + </tr> + <tr> + <td valign="top">silent</td> + <td valign="top">Do you want to suppress the error if the + "from" property does not exist, and just not set the + property "name".</td> + <td align="center" valign="top">No, default is "false".</td> + </tr> + </table> + + <h2>Example</h2> +<pre> +<property name="org" value="MyOrg" /> +<property name="org.MyOrg.DisplayName" value="My Organiziation" /> +<propertycopy name="displayName" from="org.${org}.DisplayName" /> +</pre> + + <p>Sets <code>displayName</code> to "My + Organiziation".</p> + + <hr> + <p align="center">Copyright © 2002 Ant-Contrib Project. All + rights Reserved.</p> + + </body> +</html> diff --git a/docs/manual/tasks/propertyregex.html b/docs/manual/tasks/propertyregex.html new file mode 100644 index 0000000..33b855e --- /dev/null +++ b/docs/manual/tasks/propertyregex.html @@ -0,0 +1,133 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Ant-contrib Tasks: PropertyRegex</title> + </head> + + <body> + <h1>PropertyRegex</h1> + + <p>Performs regular expression operations on an input string, and sets + the results to a property. There are two different operations that + can be performed: + <ol type="1"> + <li>Replacement - The matched regular expression is replaced with + a substitition pattern</li> + <li>Selection - Groupings within the regular expression are selected + via a selection expression. + </ol> + </p> + + <h2>Parameters</h2> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">property</td> + <td valign="top">The name of the property to set.</td> + <td align="center" valign="top">Yes.</td> + </tr> + <tr> + <td valign="top">override</td> + <td valign="top">If the property is already set, should we change it's value. + Can be <code>true</code> or <code>false</code></td> + <td align="center" valign="top">No. Defaults to <code>false</code></td> + </tr> + <tr> + <td valign="top">input</td> + <td valign="top">The input string to be processed</td> + <td align="center" valign="top">Yes.</td> + </tr> + </tr> + <tr> + <td valign="top">regexp</td> + <td valign="top">The regular expression which is matched in + the input string.</td> + <td align="center" valign="top">Yes (can be specified in a + <code><regexp></code> subelement). + </td> + </tr> + <tr> + <td valign="top">select</td> + <td valign="top">A pattern which indicates what selection pattern you want + in the returned value. This uses the substitution pattern + syntax to indicate where to insert groupings created as a result + of the regular expression match.</td> + <td align="center" valign="top">Yes, unless a replace is specified</td> + </tr> + <tr> + <td valign="top">replace</td> + <td valign="top">A regular expression substitition pattern, which will be used + to replace the given regular expression in the input string.</td> + <td align="center" valign="top">Yes, unless a select is specified</td> + </tr> + <tr> + <td valign="top">casesensitive</td> + <td valign="top">Should the match be case sensitive</td> + <td align="center" valign="top">No. default is "true".</td> + </tr> + <tr> + <td valign="top">global</td> + <td valign="top">Should a replacement operation be performed on the entire + string, rather than just the first occurance</td> + <td align="center" valign="top">No. default is <code>false</code>.</td> + </tr> + <tr> + <td valign="top">defaultValue</td> + <td valign="top">The value to set the output property to, if the + input string does not match the specific regular expression.</td> + <td align="center" valign="top">No.</td> + </table> + + <h2>Select expressions</h2> + + Expressions are selected in a the same syntax as a regular expression + substitution pattern. + + <ul type="o"> + <li><code>\0</code> indicates the entire property name (default). + <li><code>\1</code> indicates the first grouping + <li><code>\2</code> indicates the second grouping + <li>etc... + </ul> + + <h2>Replacement</h2> + It is important to note that when doing a "replace" operation, + if the input string does not match the regular expression, then + the property is not set. You can change this behavior by supplying + the "defaultValue" attribute. This attribute should contain the value + to set the property to in this case. + + <h2>Example</h2> + + <pre> + <code> + <propertyregex property="pack.name" + input="package.ABC.name" + regexp="package\.([^\.]*)\.name" + select="\1" + casesensitive="false" /> + </code> + yields <code>ABC</code> + </pre> + + <pre> + <code> + <propertyregex property="pack.name" + input="package.ABC.name" + regexp="(package)\.[^\.]*\.(name)" + replace="\1.DEF.\2" + casesensitive="false" /> + </code> + yields <code>package.DEF.name</code> + </pre> + + <hr> + <p align="center">Copyright © 2003 Ant-Contrib Project. All + rights Reserved.</p> + + </body> +</html> diff --git a/docs/manual/tasks/propertyselector.html b/docs/manual/tasks/propertyselector.html new file mode 100644 index 0000000..4e5102e --- /dev/null +++ b/docs/manual/tasks/propertyselector.html @@ -0,0 +1,139 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Ant-contrib Tasks: PropertySelector</title> + </head> + + <body> + <h1>PropertySelector</h1> + + <p>Selects property names that match a given regular expression and + returns them in a delimited list</p> + + <h2>Parameters</h2> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">property</td> + <td valign="top">The name of the property you wish to set.</td> + <td align="center" valign="top">Yes.</td> + </tr> + <tr> + <td valign="top">override</td> + <td valign="top">If the property is already set, should we change it's value. + Can be <code>true</code> or <code>false</code></td> + <td align="center" valign="top">No. Defaults to <code>false</code></td> + </tr> + <tr> + <td valign="top">match</td> + <td valign="top">The regular expression which is used to select + property names for inclusion in the list. This follows + the standard regular expression syntax accepted by ant's + regular expression tasks.</td> + <td align="center" valign="top">Yes.</td> + </tr> + <tr> + <td valign="top">select</td> + <td valign="top">A pattern which indicates what selection pattern you want + in the returned list. This used the substitution pattern + syntax to indicate where to insert groupings created as a result + of the regular expression match.</td> + <td align="center" valign="top">No. default is "\0".</td> + </tr> + <tr> + <td valign="top">casesensitive</td> + <td valign="top">Should the match be case sensitive</td> + <td align="center" valign="top">No. default is "true".</td> + </tr> + <tr> + <td valign="top">delimiter</td> + <td valign="top">The delimiter used to seperate entries in the resulting + property</td> + <td align="center" valign="top">No. default is ",".</td> + </tr> + <tr> + <td valign="top">distinct</td> + <td valign="top">Should the returned entries be a distinct set (no duplicate + entries)</td> + <td align="center" valign="top">No. default is "false".</td> + </tr> + </table> + + <h2>Select expressions</h2> + + Expressions are selected in a the same syntax as a regular expression + substitution pattern. + + <ul type="o"> + <li><code>\0</code> indicates the entire property name (default). + <li><code>\1</code> indicates the first grouping + <li><code>\2</code> indicates the second grouping + <li>etc... + </ul> + + <h2>Example</h2> + + The following code + + <pre> + <code> + <property name="package.ABC.name" value="abc pack name" /> + <property name="package.DEF.name" value="def pack name" /> + <property name="package.GHI.name" value="ghi pack name" /> + <property name="package.JKL.name" value="jkl pack name" /> + + <propertyselector property="pack.list" + delimiter="," + match="package\.([^\.]*)\.name" + select="\1" + casesensitive="false" /> + + </code> + </pre> + + would yield the results + + <pre> + <code> + ABC,DEF,GHI,JKL + </code> + </pre> + + You could then iterate through this list using the <a href="foreach.html" + >ForEach Task</a> as follows: + + <pre> + <code> + <foreach list="${pack.list}" + delimiter="," + target="print.name" + param="pack.id" /> + + <target name="print.name" > + <propertycopy name="pack.name" value="package.${pack.id}.name" /> + <echo message="${pack.name}" /> + </target> + </code> + </pre> + + Would print + + <pre> + <code> + [echo] abc pack name + [echo] def pack name + [echo] ghi pack name + [echo] jkl pack name + </code> + </pre> + + <hr> + <p align="center">Copyright © 2003 Ant-Contrib Project. All + rights Reserved.</p> + + </body> +</html> diff --git a/docs/manual/tasks/runtarget.html b/docs/manual/tasks/runtarget.html new file mode 100644 index 0000000..c2af7da --- /dev/null +++ b/docs/manual/tasks/runtarget.html @@ -0,0 +1,38 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Ant-contrib Tasks: RunTarget</title> + </head> + + <body> + <h1>RunTarget</h1> + <p> + Ant task that runs a target without creating a new project. + </p> + <h2>Parameters</h2> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">target</td> + <td valign="top">The name of the target to run.</td> + <td align="center" valign="top">Yes.</td> + </tr> + </table> + + <hr /> + + <h2>Example</h2> + <pre> + <code> + TO BE DONE + </code> + </pre> + <p align="center">Copyright © 2003 Ant-Contrib Project. All + rights Reserved.</p> + + </body> +</html> diff --git a/docs/manual/tasks/server_tasks.html b/docs/manual/tasks/server_tasks.html new file mode 100644 index 0000000..5122be0 --- /dev/null +++ b/docs/manual/tasks/server_tasks.html @@ -0,0 +1,260 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Ant-contrib Server Tasks</title> + </head> + + <body> + <h1>Ant-Contrib Server Tasks</h1> + + <p>The following tasks exist for running Ant server on one machine, and + calling that server from another (or possibly the same) machine, to + execute tasks.</p> + + + <hr width="100%" /> + + <h1>AntServer</h1> + + <p> + Starts an ANT server in current process. This server will wait for + client connections, and when received, it will execute the commands + that the client has sent. NOTE: This is a blocking call, and this + task will not return until someone sends the server a shutdown command. + </p> + + <h2>Parameters</h2> + + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">port</td> + <td valign="top">The port on which the server will listen.</td> + <td align="center" valign="top">No. Defaults to 17000</td> + </tr> + </table> + + <h2>Example:</h2> + + <pre> + <code> + <antserver port="12345" /> + </code> + </pre> + + + <h1>RemoteAnt</h1> + + <p> + Sends command requests to a running instance of an AntServer which + was started using the <antserver> task. + These commands are executed in the space of the server, and therefore + have no access to any variables or references in the currently executing + project. + </p> + + <h2>Parameters</h2> + + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">machine</td> + <td valign="top">The machine name on which the server is running.</td> + <td align="center" valign="top">No. Defaults to "localhost"</td> + </tr> + <tr> + <td valign="top">port</td> + <td valign="top">The port on which the server is listening.</td> + <td align="center" valign="top">No. Defaults to 17000</td> + </tr> + <tr> + <td valign="top">persistant</td> + <td valign="top">Should we execute all commands, regardless of whether + or not one of them fails. If false, as soon as a failure is encountered, + we will stop execution.</td> + <td align="center" valign="top">No. Defaults to false</td> + </tr> + <tr> + <td valign="top">failonerror</td> + <td valign="top">If any of the sent commands encounters a build failure on + the server, should we fail this task.</td> + <td align="center" valign="top">No. Defaults to true.</td> + </tr> + </table> + + <h2>Parameters Specified as Nested Elements</h2> + + <p> + The commands to send are represented as nested elements as described + below + </p> + + + <h3>runtarget</h3> + + <p>Runs a target which is contained in the same buildfile where the + <antserver> task was called. This element may contain nested + <property> elements for sending parameters to the target, and + nested <reference> elements for sending references to the target.</p> + + <h4>Parameters</h4> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">target</td> + <td valign="top">The name of the target to run.</td> + <td align="center" valign="top">Yes.</td> + </tr> + </table> + + <h3>runant</h3> + + <p>Runs a target in an arbitrary buildfile on the machine where the + <antserver> task was called. If a relative pathname is given, + then the path of the buildfile is relative to the base directory of + the project where the <antserver> task was called. This element + may contain nested <property> elements for sending text parameters + to the target, and nested <reference> elements for sending references + to the target.</p> + + <h4>Parameters</h4> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">antfile</td> + <td valign="top">The path of the ant file to run (if relative, then + the filename is computed relative to the buildfile of the server + task's base directory</td> + <td align="center" valign="top">No. Defaults to "build.xml" in the + directory where the buildfile is to execute (specified by the dir + attribute)</td> + </tr> + <tr> + <td valign="top">target</td> + <td valign="top">The name of the target to run.</td> + <td align="center" valign="top">No. Defaults to the default target of + the specified antfile.</td> + </tr> + <tr> + <td valign="top">dir</td> + <td valign="top">the directory to use as a basedir for the new Ant project. Defaults to + the server project's basedir, unless inheritall has been set to false, in which + case it doesn't have a default value. This will override the basedir setting of + the called project.</td> + <td align="center" valign="top">No.</td> + </tr> + <tr> + <td valign="top">inheritall</td> + <td valign="top">Should the target task inherit all of + the server's properties. This is equivalent to the flag of + the same name on the <ant> task.</td> + <td align="center" valign="top">No. Defaults to false</td> + </tr> + <tr> + <td valign="top">inheritrefs</td> + <td valign="top">Should the target task inherit all of + the server's references. This is equivalent to the flag of + the same name on the <ant> task.</td> + <td align="center" valign="top">No. Defaults to false</td> + </tr> + </table> + + + <h3>shutdown</h3> + + <p>Instructs the <antserver> task to shut itself down. Control + will return to the ANT engine and will procede as necessary in the + server's buildfile.</p> + + + <h2>Example:</h2> + + <pre> + <code> + <remoteant machine="localhost" port="12345"> + <runtarget target="execute.build"> + <property name="build.type" value="full" /> + </runtarget> + <runant dir="tests" target="build.tests"> + <property name="build.type" value="full" /> + <reference refid="my.ref" torefid="inherited.ref" /> + </runtarget> + </remoteant> + </code> + </pre> + + + <p> + would be the equivalent of running the following directly on + the server machine, from within the same buildfile where the + <antserver> task was run + </p> + + + <pre> + <code> + <antcall target="execute.build"> + <param name="build.type" value="full" /> + </antcall> + <ant dir="tests"> + <property name="build.type" value="full" /> + <reference refid="my.ref" torefid="inherited.ref" /> + </antcall> + </code> + </pre> + + <h3>sendfile</h3> + + <p>Sends a file from the client to the server</p> + + <h4>Parameters</h4> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">file</td> + <td valign="top">The path of the file to send.</td> + <td align="center" valign="top">Yes.</td> + </tr> + <tr> + <td valign="top">tofile</td> + <td valign="top">The filename where the file is to be stored + on the server, if a relative path, then it is stored relative + to the server project's base directory.</td> + <td align="center" valign="top">No. If todir is specified</td> + </tr> + <tr> + <td valign="top">tofile</td> + <td valign="top">The directory where the file is to be stored + on the server, if a relative path, then it is stored relative + to the server project's base directory. The name of the file + will be the same name as the source file</td> + <td align="center" valign="top">No. If tofile is specified</td> + </tr> + </table> + + <hr> + <p align="center">Copyright © 2003 Ant-Contrib Project. All + rights Reserved.</p> + + </body> +</html>
\ No newline at end of file diff --git a/docs/manual/tasks/shellscript.html b/docs/manual/tasks/shellscript.html new file mode 100644 index 0000000..34c4112 --- /dev/null +++ b/docs/manual/tasks/shellscript.html @@ -0,0 +1,140 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> +<HTML> +<HEAD> + <META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=utf-8"> + <TITLE>Ant-contrib Tasks: ShellScript</TITLE> + <META NAME="GENERATOR" CONTENT="OpenOffice.org 644 (Linux)"> + <META NAME="CREATED" CONTENT="20030313;10303100"> + <META NAME="CHANGED" CONTENT="20030318;15221000"> +</HEAD> +<BODY LANG="en-US" DIR="LTR"> +<H1>ShellScript</H1> +<P>Task definition for the <CODE>shellscript</CODE> task. This task +allows the user to execute a script against a particular shell +program on a machine. It is an extension of the "exec" +task, and as such, supports the same attributes. One can however use +"shell" instead of "executable". Also the +"command" attribute is not allowed. See the ANT +documentation for a description of the <exec> task parameters.</P> +<H2>Parameters</H2> +<TABLE WIDTH=854 BORDER=1 CELLPADDING=2 CELLSPACING=0> + <COL WIDTH=84> + <COL WIDTH=670> + <COL WIDTH=86> + <TR> + <TH WIDTH=84> + <P>Attribute</P> + </TH> + <TH WIDTH=670> + <P>Description</P> + </TH> + <TH WIDTH=86> + <P>Required</P> + </TH> + </TR> + <TR> + <TD WIDTH=84 VALIGN=TOP> + <P>shell</P> + </TD> + <TD WIDTH=670 VALIGN=TOP> + <P>The name of the shell executable which is to be executed. This + shell must support taking a single parameter whose value is a + script file which is to be executed. + </P> + </TD> + <TD WIDTH=86> + <P>Yes</P> + </TD> + </TR> + <TR> + <TD WIDTH=84 VALIGN=TOP> + <P>executable</P> + </TD> + <TD WIDTH=670 VALIGN=TOP> + <P>Same as “shell”</P> + </TD> + <TD WIDTH=86> + <P><BR> + </P> + </TD> + </TR> + <TR VALIGN=TOP> + <TD WIDTH=84> + <P>tmpsuffix</P> + </TD> + <TD WIDTH=670> + <P>The contents of the script are placed in a temporary file. This + attribute is the extension to use. <B>note: </B>The value must + contain any dots required. This attribute is usefull for using + script files with windows + </P> + </TD> + <TD WIDTH=86> + <P>No</P> + </TD> + </TR> + <TR VALIGN=TOP> + <TD WIDTH=84> + <P>inputstring</P> + </TD> + <TD WIDTH=670> + <P>This is placed in the script file.</P> + </TD> + <TD WIDTH=86> + <P>No</P> + </TD> + </TR> +</TABLE> +<H2>Nested Text</H2> +<P>Any nested text is treated as the contents of the script that is +to be executed within the shell. Embedded ant properties will be +converted.</P> +<H2>Examples</H2> +<PRE> <shellscript shell="bash" dir="${src.mib.dir}"> + mibgen -i ../include mib.mib -c ${build.gen.dir}/generated.cpp + mibgen -i ../include mib.mib -h ${build.gen.dir}/generated.h + </shellscript> + + <shellscript shell="sed" outputproperty="sed.output"> + <arg value="-e"/> + <arg value="s/FOO/BAR/g"/> + FOO bar bar bar FOO bar bar + </shellscript> + + <shellscript shell="cmd.exe" tmpsuffix=".bat"> + <arg value="/c"/> + <arg value="call"/> + echo hello world + </shellscript> + + <shellscript shell="bash" + dir="${build.bin.dir}" + inputstring="ls -rt | tail -n 1" + outputproperty="last.bin.file"/> + + <shellscript executable="perl"> + print STDOUT "Hello World!\n"; + </shellscript> + + <shellscript shell="sh" dir="${thirdparty.dist.dir}/lib"> + rm *.so + for file in *.0 + do + x=`echo $file | sed -e's/.0.1.0//'` + ln -s $file $x + done + </shellscript></PRE><P> +<BR><BR> +</P> +<P><B>Warning:</B></P> +<P STYLE="margin-left: 0.79in">One should be carefull in using +<I>shellscript</I>, as overuse will make your build files difficult +to understand, to maintain and to support multiplatform builds. Use +of <I>cygwin</I> in a windows environment will help. However one +should strive to use the java tasks whereever possible.</P> +<PRE STYLE="margin-bottom: 0.2in"> </PRE> +<HR> +<P ALIGN=CENTER>Copyright © 2003 Ant-Contrib Project. All rights +Reserved.</P> +</BODY> +</HTML>
\ No newline at end of file diff --git a/docs/manual/tasks/sortlist.html b/docs/manual/tasks/sortlist.html new file mode 100644 index 0000000..5af5d41 --- /dev/null +++ b/docs/manual/tasks/sortlist.html @@ -0,0 +1,145 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Ant-contrib Tasks: SortList</title> + </head> + + <body> + <h1>SortList</h1> + + <p>Sort a delimited list of items in their natural string order. Note that + the <code>value</code> and <code>refid</code> attributes are mutually exclusive, + and the <code>value</code> attribute takes precedence if both are specified.</p> + + <h2>Parameters</h2> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">property</td> + <td valign="top">The name of the property to set.</td> + <td align="center" valign="top">Yes.</td> + </tr> + <tr> + <td valign="top">override</td> + <td valign="top">If the property is already set, should we change it's value. + Can be <code>true</code> or <code>false</code></td> + <td align="center" valign="top">No. Defaults to <code>false</code></td> + </tr> + <tr> + <td valign="top">value</td> + <td valign="top">The list of values to process, with the + delimiter character, indicated by the "delimiter" + attribute, separating each value.</td> + <td align="center" valign="top">Yes, unless "refid" is + specified.</td> + </tr> + <tr> + <td valign="top">refid</td> + <td valign="top">The id of where the list of values to sort is + stored.</td> + <td align="center" valign="top">Yes, unless "value" is + specified.</td> + </tr> + <tr> + <td valign="top">delimiter</td> + <td valign="top">The delimiter string that separates the + values in the "list" attribute.</td> + <td align="center" valign="top">No, defaults to ",".</td> + </tr> + <tr> + <td valign="top">casesensitive</td> + <td valign="top">If <code>true</code>, does a case sensitive sorting + of the strings. If <code>false</code> does case insensitive sorting. + </td> + <td align="center" valign="top">No. Defaults to true.</td> + </tr> + <tr> + <td valign="top">numeric</td> + <td valign="top">If <code>true</code>, does a numeric sorting, treating + all list entries as if they were numbers. + </td> + <td align="center" valign="top">No. Defaults to false.</td> + </tr> + + <tr> + <td valign="top">orderPropertyFile</td> + <td valign="top">If specified, the list will sorted as if they were property + names, and will be sorted in the order those properties appear + in the given property file. Any properties in the + <code>value</code> attribute which do not appear in the properties file + will be inserted at the end of the list. This property is most useful + when used in conjunction with the <code><propertyselector></code> + task (see Example 2). + </td> + <td align="center" valign="top">No.</td> + </tr> + + <tr> + <td valign="top">orderPropertyFilePrefix</td> + <td valign="top">If <code>orderPropertyFile</code> is specified, this + value (with a trailing '.') will be prefixed to each property in the + specified <code>orderPropertyFile</code> to determine sorting order + </td> + <td align="center" valign="top">No.</td> + </tr> + + </table> + + <hr /> + + <h2>Example 1</h2> + <pre> + <code> + <property name="my.list" value="z,y,x,w,v,u,t" /> + <sortlist property="my.sorted.list" value="${my.list}" + delimiter="," /> + <echo message="${my.sorted.list}" /> + </code> + + prints + + <code> + [echo] t,u,v,w,x,y,z + </code> + + <h2>Example 2</h2> + <pre> + test.properties + --------------- + a.name=a + c.name=c + b.name=b + + <code> + <property file="test.properties" prefix="test" /> + <propertyselector property="my.list" + delimiter="," + match="test\..*\.name" + select="\0" /> + <sortlist property="my.sorted.list" + value="${my.list}" + delimiter="," + orderPropertyFile="test.properties" + orderPropertyFilePrefix="test" /> + + <echo message="${my.sorted.list}" /> + + prints + + <code> + [echo] test.a.name,test.c.name,test.b.name + </code> + + Notice that the <code>test.properties</code> file did not have "test." + prefixing all the properties. The <code>orderPropertyFilePrefix</code> was + used to do that. + <hr> + <p align="center">Copyright © 2002-2003 Ant-Contrib Project. All + rights Reserved.</p> + + </body> +</html> diff --git a/docs/manual/tasks/stopwatch_task.html b/docs/manual/tasks/stopwatch_task.html new file mode 100644 index 0000000..8520c78 --- /dev/null +++ b/docs/manual/tasks/stopwatch_task.html @@ -0,0 +1,115 @@ +<html> +<head> +<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title> +Stopwatch</title> +<meta content="DocBook XSL Stylesheets V1.60.1" name="generator"> +<link rel="home" href="index.html" title="Antelope Users Guide"> +<link rel="up" href="bk03.html" title="Additional Ant Tasks"> +<link rel="previous" href="bk03ch08.html" title="Chapter 8. Variable Task"> +<link rel="next" href="bk03ch10.html" title="Chapter 10. Limit"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="chapter" lang="en"> +<div class="titlepage"> +<div> +<div> +<h2 class="title"> +<a name="stopwatch"> +</a> +Stopwatch</h2> +</div> +</div> +<div> +</div> +</div> +<p> + +The Stopwatch task makes it easy to add performance timing to Ant targets. Stopwatches are named so that multiple watches can run simultaneously. +</p> + +<p> + +<div class="table"> +<a name="N1092E"> +</a> +<p class="title"> +<b> +Table 9.1. Stopwatch Task Attributes</b> +</p> +<table summary="Stopwatch Task Attributes" border="1"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead> +<tr> +<th> +Attribute</th> +<th> +Description</th> +<th> +Default</th> +<th> +Required</th> +</tr> +</thead> +<tbody> +<tr> +<td> +name</td> +<td> +The name for the stopwatch. The elapsed time or total time will be stored as an Ant property with this name.</td> +<td> +None</td> +<td> +Yes</td> +</tr> +<tr> +<td> +action</td> +<td> +Valid values are "start", "stop", "elapsed", and "total".</td> +<td> +"start"</td> +<td> +No</td> +</tr> +</tbody> +</table> +</div> + +</p> +<p> + +The stopwatch is started with the "start" action. When the action is "elapsed" or "total", the running time of the stopwatch is printed out. Both "stop" and "total" stop the stopwatch and reset it to zero. "elapsed" prints out the current running time of the stopwatch without stopping it. +</p> +<p> + +Example: +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + +<stopwatch name="timer1"/> +<!-- do some tasks here... --> +<stopwatch name="timer1" action="elapsed"/> <!-- print the elapsed time --> +<!-- do some more tasks here... --> +<stopwatch name="timer1" action="total"/> <!-- print out the total time --> + +</pre> +</td> +</tr> +</table> + +</p> +</div> + <hr> + <p align="center">Copyright © 2003 Ant-Contrib Project. All + rights Reserved.</p> +</body> +</html> diff --git a/docs/manual/tasks/switch.html b/docs/manual/tasks/switch.html new file mode 100644 index 0000000..837c701 --- /dev/null +++ b/docs/manual/tasks/switch.html @@ -0,0 +1,82 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Ant-contrib Tasks: Switch</title> + </head> + + <body> + <h1>Switch</h1> + + <p>Task definition for the ANT task to switch on a particular value.</p> + + <h2>Parameters</h2> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">value</td> + <td valign="top">The value to switch on.</td> + <td align="center" valign="top">Yes.</td> + </tr> + <tr> + <td valign="top">caseinsensitive</td> + <td valign="top">Should we do case insensitive comparisons?</td> + <td align="center" valign="top">No, default is "false"</td> + </tr> + </table> + + <h2>Parameters specified as nested elements</h2> + + <p>At least one <code><case></code> or + <code><default></code> is required.</p> + + <h3>case</h3> + + <p>An individual case to consider, if the value that is being + switched on matches to value attribute of the case, then the + nested tasks will be executed.</p> + + <h4>Parameters</h4> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">value</td> + <td valign="top">The value to match against the tasks value attribute.</td> + <td align="center" valign="top">Yes.</td> + </tr> + </table> + + <h3>default</h3> + + <p>The default case for when no match is found. Must not appear + more than once per task.</p> + + <h2>Example</h2> + +<pre> +<switch value="${foo}"> + <case value="bar"> + <echo message="The value of property foo is bar" /> + </case> + <case value="baz"> + <echo message="The value of property foo is baz" /> + </case> + <default> + <echo message="The value of property foo is not sensible" /> + </default> +</switch> +</pre> + + <hr> + <p align="center">Copyright © 2002 Ant-Contrib Project. All + rights Reserved.</p> + + </body> +</html> diff --git a/docs/manual/tasks/throw.html b/docs/manual/tasks/throw.html new file mode 100644 index 0000000..0aeb0e8 --- /dev/null +++ b/docs/manual/tasks/throw.html @@ -0,0 +1,39 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Ant-contrib Tasks: Throw</title> + </head> + + <body> + <h1>Throw</h1> + + <p>Extension of Ant's built-in <code><fail></code> task that + can throw an exception that is given by a reference. This may be + useful if you want to rethrow the exception that has been caught + by a <code><trycatch></code> task in the + <code><catch></code> block.</p> + + <h2>Parameters</h2> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">refid</td> + <td valign="top">Id of the referenced exception.</td> + <td align="center" valign="top">No.</td> + </tr> + </table> + + <p>In addition, all attributes of the <a + href="http://jakarta.apache.org/ant/manual/CoreTasks/fail.html"><code><fail></code> + task</a> are supported.</p> + + <hr> + <p align="center">Copyright © 2002 Ant-Contrib Project. All + rights Reserved.</p> + + </body> +</html> diff --git a/docs/manual/tasks/timestampselector.html b/docs/manual/tasks/timestampselector.html new file mode 100644 index 0000000..c4186d1 --- /dev/null +++ b/docs/manual/tasks/timestampselector.html @@ -0,0 +1,132 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Ant-contrib Tasks: TimestampSelector</title> + </head> + + <body> + <h1>TimestampSelector</h1> + + <p>The TimestampSelector task takes either a nested <path> element, + or a path reference, and sets either a named property, or a <code>path</code> + instance to absolute pathnames of the files with either the N latest or earliest + modification dates (based on the <code>age</code> attribute)</p> + + <h2>Parameters</h2> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">property</td> + <td valign="top">The property to set with the most recently modified file. Mutually + exclusive with the <code>outputsetid</code> attribute.</td> + <td align="center" valign="top">Yes, if <code>outputsetid</code> is not specified.</td> + </tr> + <tr> + <td valign="top">outputsetid</td> + <td valign="top">The id of a <code>path</code> instance which will contain the + resulting list of files. This id should not already exist. Mutually exclusive + with the <code>property</code> attribute</td> + <td align="center" valign="top">Yes, if <code>property</code> is note specified.</td> + </tr> + <tr> + <td valign="top">count</td> + <td valign="top">The number of files to find. If more than 1, than the + files in the output appear in the order indicated by the <code>age</code> + attribute.</td> + <td align="center" valign="top">No. Defaults to <code>1<code></td> + </tr> + <tr> + <td valign="top">age</td> + <td valign="top">The age of the files to retrieve, either <code>eldest</code> + or <code>youngest</code>. Defaults to <code>youngest</code>.</td> + <td align="center" valign="top">No. Defaults to <code>1<code></td> + </tr> + <tr> + <td valign="top">pathSep</td> + <td valign="top">The path separator to separate paths with when using the + <code>property</code> attribute in conjunction with the <code>count</code> + attribute</td> + <td align="center" valign="top">No. Defaults to <code>,<code></td> + </tr> + <tr> + <td valign="top">pathref</td> + <td valign="top">Id of the path to find the most recently modified file in.</td> + <td align="center" valign="top">No, if a <code>path</code> subelement is + specified.</td> + </tr> + </table> + + <h2>Parameters specified as nested elements</h2> + + <a name="path"><h3>path</h3></a> + + <p><a href="http://ant.apache.org/manual/using.html#path">Path</a> + is used to select sets of files or directories in which to find the + most recently modified file</p> + + <h2>Example</h2> + + <h3>Using a path reference</h3> + <pre> + <code> + + <path id="mypath"> + <fileset dir="${log.dir}"> + <include name="update*.log" /> + </fileset> + <path> + <timestampselector property="most.recent.logs" + pathref="mypath" count="3" + pathsep=";" /> + + <echo message="${most.recent.logs}" /> + </code> + </pre> + + <h3>Using a nested <code>path</code> element</h3> + <pre> + <code> + + <timestampselector property="most.recent.logs" + count="3" + pathsep=";" > + <path> + <fileset dir="${log.dir}"> + <include name="update*.log" /> + </fileset> + <path> + </timestampselector> + + <echo message="${most.recent.logs}" /> + </code> + </pre> + + <h3>Outputing to a <code>path</code> element</h3> + <pre> + <code> + + <timestampselector outputsetref="most.recent.logs" + pathref="mypath" count="3"> + <path> + <fileset dir="${log.dir}"> + <include name="update*.log" /> + </fileset> + <path> + </timestampselector> + + <copy todir="somedir"> + <path refid="most.recent.logs" /> + </copy> + </code> + </pre> + + <hr> + <p align="center">Copyright © 2002-2003 Ant-Contrib Project. All + rights Reserved.</p> + + </body> +</html> diff --git a/docs/manual/tasks/toc.html b/docs/manual/tasks/toc.html new file mode 100644 index 0000000..b1d926f --- /dev/null +++ b/docs/manual/tasks/toc.html @@ -0,0 +1,64 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Task List</title> + </head> + + <body> + <h2>Logic Tasks</h2> + <ul> + <li><a href="antcallback_task.html" target="mainFrame">AntCallBack</a></li> + <li><a href="antfetch_task.html" target="mainFrame">AntFetch</a></li> + <li><a href="assert_task.html" target="mainFrame">Assert</a></li> + <li><a href="foreach.html" target="mainFrame">Foreach</a></li> + <li><a href="for.html" target="mainFrame">For</a></li> + <li><a href="if.html" target="mainFrame">If</a></li> + <li><a href="outofdate.html" target="mainFrame">Outoutdate</a></li> + <li><a href="runtarget.html" target="mainFrame">RunTarget</a></li> + <li><a href="switch.html" target="mainFrame">Switch</a></li> + <li><a href="throw.html" target="mainFrame">Throw</a></li> + <li><a href="timestampselector.html" target="mainFrame">TimestampSelector</a></li> + <li><a href="trycatch.html" target="mainFrame">Trycatch</a></li> + </ul> + <h2>Network Tasks</h2> + <ul> + <li><a href="post_task.html" target="mainFrame">HTTP Post</a></li> + <li><a href="server_tasks.html" target="mainFrame">AntServer / RemoteAnt</a></li> + </ul> + <h2>Performance Monitoring and Tasks</h2> + <ul> + <li><a href="performance_monitor.html" target="mainFrame">Performance Monitor</a></li> + <li><a href="stopwatch_task.html" target="mainFrame">Stopwatch</a></li> + </ul> + <h2>Platform Tasks</h2> + <ul> + <li><a href="osfamily.html" target="mainFrame">Osfamily</a></li> + <li><a href="shellscript.html" target="mainFrame">Shellscript</a></li> + </ul> + <h2>Property Tasks</h2> + <ul> + <li><a href="math_task.html" target="mainFrame">Math</a></li> + <li><a href="propertycopy.html" target="mainFrame">Propertycopy</a></li> + <li><a href="propertyselector.html" target="mainFrame">PropertySelector</a></li> + <li><a href="pathtofileset.html" target="mainFrame">Pathtofileset</a></li> + <li><a href="propertyregex.html" target="mainFrame">PropertyRegex</a></li> + <li><a href="sortlist.html" target="mainFrame">SortList</a></li> + <li><a href="urlencode.html" target="mainFrame">URLEncode</a></li> + <li><a href="variable_task.html" target="mainFrame">Variable</a></li> + </ul> + + <h2>Process Tasks</h2> + <ul> + <li><a href="forget.html" target="mainFrame">Forget</a></li> + <li><a href="limit_task.html" target="mainFrame">Limit</a></li> + </ul> + + <h2>Other Tasks</h2> + <ul> + <li><a href="antclipse_task.html" target="mainFrame">antclipse</a></li> + <li><a href="compilewithwalls.html" target="mainFrame">CompileWithWalls</a></li> + <li><a href="inifile.html" target="mainFrame">IniFile</a></li> + <li><a href="verifydesign.html" target="mainFrame">VerifyDesign</a></li> + </ul> + </body> +</html> diff --git a/docs/manual/tasks/trycatch.html b/docs/manual/tasks/trycatch.html new file mode 100644 index 0000000..7eb38a8 --- /dev/null +++ b/docs/manual/tasks/trycatch.html @@ -0,0 +1,96 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Ant-contrib Tasks: Trycatch</title> + </head> + + <body> + <h1>Trycatch</h1> + + <p>A wrapper that lets you run a set of tasks and optionally run a + different set of tasks if the first set fails and yet another set + after the first one has finished.</p> + + <p>This mirrors Java's try/catch/finally.</p> + + <p>The tasks inside of the required <code><try></code> + element will be run. If one of them should throw a BuildException + several things can happen:</p> + + <ul> + <li>If there is no <code><catch></code> block, the + exception will be passed through to Ant.</li> + + <li>If the property attribute has been set, a property of the + given name will be set to the message of the exception.</li> + + <li>If the reference attribute has been set, a reference of the + given id will be created and point to the exception object.</li> + + <li>If there is a <code><catch></code> block, the tasks + nested into it will be run.</li> + </ul> + + <p>If a <code><finally></code> block is present, the task + nested into it will be run, no matter whether the first tasks have + thrown an exception or not.</p> + + <h2>Parameters</h2> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">property</td> + <td valign="top">Name of a property that will receive the + message of the exception that has been caught (if any)</td> + <td align="center" valign="top">No.</td> + </tr> + <tr> + <td valign="top">reference</td> + <td valign="top">Id of a reference that will point to the + exception object that has been caught (if any)</td> + <td align="center" valign="top">No</td> + </tr> + </table> + + <h2>Example</h2> + +<pre> +<trycatch property="foo" reference="bar"> + <try> + <fail>Tada!</fail> + </try> + + <catch> + <echo>In &lt;catch&gt;.</echo> + </catch> + + <finally> + <echo>In &lt;finally&gt;.</echo> + </finally> +</trycatch> + +<echo>As property: ${foo}</echo> +<property name="baz" refid="bar" /> +<echo>From reference: ${baz}</echo> +</pre> + + <p>results in</p> + +<pre> + [trycatch] Caught exception: Tada! + [echo] In <catch>. + [echo] In <finally>. + [echo] As property: Tada! + [echo] From reference: Tada! +</pre> + + <hr> + <p align="center">Copyright © 2002-2003 Ant-Contrib Project. All + rights Reserved.</p> + + </body> +</html> diff --git a/docs/manual/tasks/urlencode.html b/docs/manual/tasks/urlencode.html new file mode 100644 index 0000000..be6a322 --- /dev/null +++ b/docs/manual/tasks/urlencode.html @@ -0,0 +1,78 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> + <head> + <title>Ant-contrib Tasks: URLEncode</title> + </head> + + <body> + <h1>Foreach</h1> + + <p>The URLEncode task will encode a given property for use within a + a URL string. This value which is actually set will be encoded + via the <code>java.net.URLEncoder.encode()</code> method. + Typically, you must do this for all parameter values within a URL.</p> + + <h2>Parameters</h2> + <table border="1" cellpadding="2" cellspacing="0"> + <tr> + <th>Attribute</th> + <th>Description</th> + <th>Required</th> + </tr> + <tr> + <td valign="top">property</td> + <td valign="top">The name of the property to set.</td> + <td align="center" valign="top">Yes.</td> + </tr> + <tr> + <td valign="top">override</td> + <td valign="top">If the property is already set, should we change it's value. + Can be <code>true</code> or <code>false</code></td> + <td align="center" valign="top">No. Defaults to <code>false</code></td> + </tr> + <tr> + <td valign="top">name <i>Deprecated</i></td> + <td valign="top">The name of the property to set.</td> + <td align="center" valign="top">No. Use the <code>property</code> attribute + instead</td> + </tr> + <tr> + <td valign="top">value</td> + <td valign="top">The value of the property.</td> + <td align="center" valign="top">No, if refid or location is specified</td> + </tr> + <tr> + <td valign="top">location</td> + <td valign="top">The location of a file whose absolute path will be the value + of the property.</td> + <td align="center" valign="top">No, if value or refid is specified.</td> + </tr> + <tr> + <td valign="top">refid</td> + <td valign="top">The id of a saved reference whose value will be the value + of the property.</td> + <td align="center" valign="top">No, defaults to ",".</td> + </tr> + </table> + + + <h2>Example</h2> + + + The following code + + <pre> + <code> + <urlencode name="file.location" location="C:\\wwwhome\\my reports\\report.xml" /> + </code> + </pre> + + would set the "file.location" property to the value: <code> C%3A%5Cwwwhome%5Cmy+reports%5Creport.xml</code> + which could then be used in a URL. + + <hr> + <p align="center">Copyright © 2002-2003 Ant-Contrib Project. All + rights Reserved.</p> + + </body> +</html> diff --git a/docs/manual/tasks/variable_task.html b/docs/manual/tasks/variable_task.html new file mode 100644 index 0000000..7e16ab9 --- /dev/null +++ b/docs/manual/tasks/variable_task.html @@ -0,0 +1,261 @@ +<html> +<head> +<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> +<title> +Variable Task</title> +<meta content="DocBook XSL Stylesheets V1.60.1" name="generator"> +<link rel="home" href="index.html" title="Antelope Users Guide"> +<link rel="up" href="bk03.html" title="Additional Ant Tasks"> +<link rel="previous" href="bk03ch07.html" title="Chapter 7. Try Task"> +<link rel="next" href="bk03ch09.html" title="Chapter 9. Stopwatch"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<div class="chapter" lang="en"> +<div class="titlepage"> +<div> +<div> +<h2 class="title"> +<a name="Variable"> +</a> +Chapter 8. Variable Task</h2> +</div> +</div> +<div> +</div> +</div> +<p> + +The Variable task provides a mutable property to Ant and works much like variable assignment in Java. This task is similar to the standard Ant Property task, except that THESE PROPERTIES ARE MUTABLE. While this goes against the standard Ant use of properties, occasionally it is useful to be able to change a property value within the build. <span class="bold"> +<b> +In general, use of this task is DISCOURAGED, and the standard Ant Property should be used if possible.</b> +</span> + Having said that, in real life I use this a lot. +</p> + +<p> + +Variables can be set individually or loaded from a standard properties file. A 'feature' of variables is that they can override properties, but properties cannot override variables. So if an already established property exists, its value can be reassigned by use of this task. +</p> +<p> + +<div class="table"> +<a name="N108CD"> +</a> +<p class="title"> +<b> +Table 8.1. Variable Task Attributes</b> +</p> +<table summary="Variable Task Attributes" border="1"> +<colgroup> +<col> +<col> +<col> +<col> +</colgroup> +<thead> +<tr> +<th> +Attribute</th> +<th> +Description</th> +<th> +Default</th> +<th> +Required</th> +</tr> +</thead> +<tbody> +<tr> +<td> +name</td> +<td> +The name of the property to set.</td> +<td> +None</td> +<td> +Yes, unless 'file' is used.</td> +</tr> +<tr> +<td> +value</td> +<td> +The value of the property.</td> +<td> +""</td> +<td> +No</td> +</tr> +<tr> +<td> +unset</td> +<td> +Removes the property from the project as if it had never been set.</td> +<td> +false +</td> +<td> +No +</td> +</tr> +<tr> +<td> +file</td> +<td> +The name of a standard properties file to load variables from.</td> +<td> +None</td> +<td> +No</td> +</tr> +</tbody> +</table> +</div> + +</p> +<p> + +In the following example, the property <tt class="computeroutput"> +x</tt> + is first set to "6", then evaluated by the <tt class="computeroutput"> +if</tt> +, and reassigned the value "12". The <tt class="computeroutput"> +echo</tt> + task will print out 12. +</p> +<p> + +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + + <var name="x" value="6"/> + <if> + <equals arg1="${x}" arg2="6" /> + <then> + <var name="x" value="12"/> + </then> + </if> + <echo>${x}</echo> <!-- will print 12 --> + +</pre> +</td> +</tr> +</table> + +</p> + +<p> +The next example shows a property being set, echoed, unset, then reset: +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + + <property name="x" value="6"/> + <echo>${x}</echo> <!-- will print 6 --> + <var name="x" unset="true"/> + <property name="x" value="12"/> + <echo>${x}</echo> <!-- will print 12 --> + + +</pre> +</td> +</tr> +</table> + +</p> + +<p> + +The following shows some more uses of the Variable task. It is especially handy for property appending. Notice a couple of things: the property task can't override a var value, in general, you should use var with the unset attribute to change the value of a property. +</p> +<p> + +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + + <var name="x" value="6"/> + <echo>x = ${x}</echo> <!-- print: 6 --> + + <var name="x" value="12"/> + <echo>x = ${x}</echo> <!-- print: 12 --> + + <var name="x" value="6 + ${x}"/> + <echo>x = ${x}</echo> <!-- print: 6 + 12 --> + + <var name="str" value="I "/> + <var name="str" value="${str} am "/> + <var name="str" value="${str} a "/> + <var name="str" value="${str} string."/> + <echo>${str}</echo> <!-- print: I am a string. --> + + <var name="x" value="6"/> + <echo>x = ${x}</echo> <!-- print: 6 --> + + <property name="x" value="12"/> + <echo>x = ${x}</echo> <!-- print: 6 (property can't override) --> + + <var name="x" value="blue"/> + <tstamp> + <format property="x" pattern="EEEE"/> + </tstamp> + <echo>Today is ${x}.</echo> <!-- print: Today is blue. --> + + <var name="x" value="" unset="true"/> + <tstamp> + <format property="x" pattern="EEEE"/> + </tstamp> + <echo>Today is ${x}.</echo> <!-- print: Today is Friday. --> + + +</pre> +</td> +</tr> +</table> + +</p> +<p> + +<!-- +The next example shows Variable, If, Assert, and Try working together to make sure e-mail is sent from the right address and that if the mail fails to be sent for any reason, the build will not fail. +</p> +<p> + +<table border="0" bgcolor="#E0E0E0"> +<tr> +<td> +<pre class="programlisting"> + + + <var name="valid_email" value="false"/> + <if name="email_from" value="[email protected]"> + <var name="valid_email" value="true"/> + </if> + <if name="email_from" value="[email protected]"> + <var name="valid_email" value="true"/> + </if> + <assert name="valid_email" value="true" failonerror="false"> + <try> + <mail from="${email_from}" tolist="${email_to}" + message="New release available"/> + </try> + </assert> + +</pre> +</td> +</tr> +</table> +--> +</p> +</div> + <hr> + <p align="center">Copyright © 2003-2004 Ant-Contrib Project. All + rights Reserved.</p> +</body> +</html> diff --git a/docs/manual/tasks/verifydesign.html b/docs/manual/tasks/verifydesign.html new file mode 100644 index 0000000..80f1588 --- /dev/null +++ b/docs/manual/tasks/verifydesign.html @@ -0,0 +1,264 @@ +<html lang="en-us"> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<title>VerifyDesign Ant Task</title> +</head> + +<body> + +<h2>VerifyDesign Ant Task</h2> +<ul> + <li>Creator: Dean Hiller (<a href="mailto:[email protected]">[email protected]</a>)</li> + <li>Contributor: Matt Inger (thanks for some really awesome changes)</li> + <li>Contributor: Anthony Y Robins</li> +</ul> +<p>Feedback on task and documentation are welcome!</p> +<h3>Description</h3> +<p>Describe your design dependencies in an xml file, and this task will enforce them so they are not violated</p> +<p>For example, if there are three packages in one source tree +<ul> +<li>biz.xsoftware.presentation</li> +<li>biz.xsoftware.business</li> +<li>biz.xsoftware.dataaccess</li> +</ul> +and naturally presentation should only depend on business package, and business should depend on dataaccess. If you define your design this way and it is violated the build will fail when the verifydesign ant task is called. For example, if I created a class in biz.xsoftware.presentation and that class depended on a class in biz.xsoftware.dataaccess, the build would fail. This ensures the design actually follows what is documented(to some degree at least). This is especially nice with automated builds</p> + +<h3>Getting Started</h3> +Download bcel jar from this link <a href="http://jakarta.apache.org/site/binindex.cgi#bcel">Bcel download</a> as this ant task uses the jar built from the <a href="http://jakarta.apache.org/bcel/">bcel project</a> on jakarta. Choose a directory to put in place of the XXXXXX below and add the ant-contrib jar as well as the bcel jar to that directory. You should now be all set to use the verifydesign element in your build.xml file as well as any other ant-contrib tasks. If you want to use this with 5.0jdk, you must download the bcel from the head of cvs until something better than 5.1 is released. This version of ant-contrib will work with both 5.0jdk and 1.4 jdk. 1.3 and before is not tested. +<pre> + <taskdef resource="net/sf/antcontrib/antlib.xml"> + <classpath> + <fileset dir="XXXXXX"> + <include name="**/*.jar"/> + </fileset> + </classpath> + </taskdef> +</pre> + +Now, you can skip to the <a href="verifylegacytutorial.html">VerifyDesign Legacy Project Tutorial</a> which guides you through how to use this task if you already have alot of existing code, or you can start with the <a href="verifynewprojtutorial.html">VerifyDesign New Project Tutorial</a> where you don't have much code or any at all. + +<h3>Parameters</h3> +<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">design</td> + <td valign="top">The file that specifies the design in xml format(Examples below)</td> + <td align="center" valign="top">required</td> + </tr> + <tr> + <td valign="top">jar</td> + <td valign="top">The jar file of who's design we want to validate</td> + <td align="center" valign="top">required</td> + </tr> + <tr> + <td valign="top">circularDesign</td> + <td valign="top">I strongly encourage you not to use this. This turns on allowing circular dependencies. There is always a way to get around circular dependencies, and I suggest you use it instead of introducing a circular dependency. If you think you have found one you can't work around, send me mail and maybe I can give you some ideas.</td> + <td align="center" valign="top">optional(default=false)</td> + </tr> + <tr> + <td valign="top">deleteFiles</td> + <td valign="top">Deletes jar/class files upon build failure to prevent usage. Use this option for new projects so the binaries are not used without the design being met. </td> + <td align="center" valign="top">optional(default=false)</td> + </tr> + <tr> + <td valign="top">fillInBuildException</td> + <td valign="top">Fills the BuildException with all the same errors reported in the logs. This is for products like cruisecontrol who only see standard ant task logs and would miss reporting these errors otherwise(ie. instead it just reports build failed with look at the design errors)</td> + <td align="center" valign="top">optional(default=false)</td> + </tr> + <tr> + <td valign="top">needDeclarationsDefault</td> + <td valign="top">false is saying that for this particular package, no other package needs to declare that they depend on this package. It is basically saying the needDeclarations attribute in the package element in the design file is whatever the value of this attribute is in the build.xml file if the design file does not override it.</td> + <td align="center" valign="top">optional(default=true)</td> + </tr> + <tr> + <td valign="top">needDependsDefault</td> + <td valign="top">false is saying that by default no package in the design file has to declare it's dependencies. It is basically saying the needDepends attribute in the package element in the design file is whatever the value of this attribute is in the build.xml file if the design file does not override it.</td> + <td align="center" valign="top">optional(default=true)</td> + </tr> +</table> + +<h3>Parameters specified as nested elements</h3> +<p>No nested elements allowed + + +</p> +<h2>Design File</h2> +<p> +The design file is an xml based file specifying dependencies that are ok. Any dependencies not specified will not be allowed and will make sure the build fails. Examples of the contents of the design file can be found below. +</p> + +<h3>design Root Element</h3> +<p>The root element of the design file is 'design'. Here are design's allowed subelements.</p> + +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Subelement</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">package</td> + <td valign="top">subelement representing a package and it's dependencies</td> + <td align="center" valign="top">One or more Required</td> + </tr> +</table> + +<h3>package SubElement</h3> +<p>Here are package elements allowed attributes and subelements</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">name</td> + <td valign="top">A smaller nickname for the package to reference in the depends subelement or attribute</td> + <td align="center" valign="top">Required</td> + </tr> + <tr> + <td valign="top">package</td> + <td valign="top">The package to compile such as biz.xsoftware.presentation</td> + <td align="center" valign="top">Required</td> + </tr> + <tr> + <td valign="top">depends</td> + <td valign="top">Contains one and only one 'name' of a package to depend on(taken from name attribute above). If you want to specify more, use the depends subelement</td> + <td align="center" valign="top">Optional(Default=no dependencies)</td> + </tr> + <tr> + <td valign="top">subpackages</td> + <td valign="top">Can be set to include or exclude. Basically allows classes in subpackages to be part of the package specified.(see examples below)</td> + <td align="center" valign="top">Optional(default=exclude)</td> + </tr> + <tr> + <td valign="top">needdeclarations</td> + <td valign="top">Can be set to true or false. True means if other packages depend on this package, a depends subelement or attribute must exist stating the dependency. False means other packages need not declare they depend on this package. This should be used sparingly for things like java.lang. By default "java" package and all subpackages are set to false. This can be overridden if you need however so you can make sure only certain packages depend on java.util or something if you really need that. (see examples below)</td> + <td align="center" valign="top">Optional(default=true)</td> + </tr> + <tr> + <td valign="top">needdepends</td> + <td valign="top">Can be set to true or false. True means if this package depends on other packages, those dependencies must be defined(unless those other packages have needdeclarations set to false). False means this package must list all the packages it depends on. This is typically for legacy code where you don't want to deal with what this package depends on right now. On a new project, I never use this.</td> + <td align="center" valign="top">Optional(default=true)</td> + </tr> +</table> +<br/> +<table border="1" cellpadding="2" cellspacing="0"> + <tr> + <td valign="top"><b>Subelement</b></td> + <td valign="top"><b>Description</b></td> + <td align="center" valign="top"><b>Required</b></td> + </tr> + <tr> + <td valign="top">depends</td> + <td valign="top">Contains one and only one 'name' of a package to depend on(taken from name attribute above)</td> + <td align="center" valign="top">One or more Optional</td> + </tr> +</table> + +<h3>depends SubElement</h3> +Contents contain the 'name' of a package found in the package element's name attribute + +<h3>Examples</h3> + +<h4>Ant's build.xml File</h4> +<pre> + <verifydesign jar="application.jar" design="design.xml"/> +</pre> +<p> +That is simple enough. application.jar is the jar I am verifying the design of. design.xml contains the design I want the jar file to adhere to. There is no need to include third party jars(unless you want to verify their design which you shouldn't). The design file can still define what your stuff depends on in those third party libraries without requiring those libraries to be present. If it does not adhere to that design, the build fails. Examples of a design.xml can be found further below. +</p> +<p> +Another example equivalent to the above is below. verifydesign takes a path like structure(see ant documentation). <b>I highly advise breaking the design on purpose and verifying that the build fails. This ensures you have the ant task set up correctly.</b> +</p> +<pre> + <verifydesign design="design.xml"> + <path> + <pathelement jar="application.jar"/> + </path> + </verifydesign> +</pre> + +One last example would be like so +<pre> + <verifydesign design="design.xml"> + <path> + <fileset dir="${classesDir}"> + <include name="**/*.class"/> + </fileset> + </path> + </verifydesign> +</pre> + +Now let's move on to define the contents of design.xml file. + +<h4>design.xml File</h4> + +<pre> +These lines would be in dependencies.xml..... + <design> + <package name="alljavax" package="javax" subpackages="include" needdeclarations="false"/> + <package name="util" package="biz.xsoftware.util" subpackages="include"/> + <package name="dataaccess" package="biz.xsoftware.dataaccess"/> + <package name="business" package="biz.xsoftware.business" depends="dataaccess"/> + <package name="presentation" package="biz.xsoftware.presentation"> + <depends>business</depends> + <depends>util</depends> + </package> + </design> +</pre> +<p>Notice in this example, if biz.xsoftware.dataaccess.XYZClass depended on biz.xsoftware.util.Util, the build would fail since that package dependency is not defined. Similarly, any class in biz.xsoftware.presentation cannot depend on any class in biz.xsoftware.dataaccess</p> +<p>Also, notice that biz.xsoftware.presentation.Gui is allowed to depend on biz.xsoftware.util.pres.ClassInSubpackage because subpackages is set to include. This allows subpackages of biz.xsoftware.util to also be included in the design without having to define every subpackage.</p> +<p>Lastly, notice the first line so javax and all javax subpackages can be depended on without declaring them. Use this sparingly though as sometimes you might want to isolate dependencies like depending on JMX to a certain package. For example, you may want only biz.xsoftware.management to depend on JMX and nothing else to depend on it. If you declare the same declaration I declared here for javax, you will not be able to guarantee that.</p> + +<h4>The wad design.xml file</h4> +If you really want to, you could design for a wad. This is not suggested and if you want to do this, don't use this ant task please. +<pre> + <design> + <package name="wad" package="<default package>" subpackages="include"/> + </design> +</pre> + +<h4>Including subpackages design.xml</h4> +<pre> + <design> + <package name="service1" package="biz.xsoftware.service1" subpackages="include"/> + <package name="client1" package="biz.xsoftware.client1" depends="service1"/> + <package name="service2" package="biz.xsoftware.service2"/> + <package name="client2" package="biz.xsoftware.client2" depends="service2" subpackages="include"/> + </design> +</pre> +<p> +Note that here for service 1, classes in package biz.xsoftware.client1 can depend on any classes in biz.xsoftware.service1 and can also depend on classes in subpackages of biz.xsoftware.service1. +</p> +<p> +Note that for service 2, classes in biz.xsoftware.client2 and client2's subpackages are all allowed to depend on classes in biz.xsoftware.service2. +</p> +<h4>One Design Note</h4> +One big note to consider, there is one design dependency that verifydesign cannot see from the class file. This is due to the String constants(This only happens with static final <b>Strings</b> and static final <b>primitives</b> being compiled into the class file. Here is example code demonstrating this task cannot catch these dependencies.... +<pre> +public class Client { + public void fakeMethod() { + String s = Dependency.CONSTANT; //verifydesign task can't tell this depends on + //DependencyClass as that info is lost after compiling + } +} + +public class DependencyClass { + public static final String CONSTANT = "asdf"; +} +</pre> + +<hr> + <p align="center">Copyright © 2002-2004 Ant-Contrib Project. All + rights Reserved.</p> + +</body> +</html> + diff --git a/docs/manual/tasks/verifylegacytutorial.html b/docs/manual/tasks/verifylegacytutorial.html new file mode 100644 index 0000000..6999882 --- /dev/null +++ b/docs/manual/tasks/verifylegacytutorial.html @@ -0,0 +1,71 @@ +<html lang="en-us"> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<title>VerifyDesign Legacy System Tutorial</title> +</head> + +<body> + +<h2>VerifyDesign Legacy System Tutorial</h2> + +<p>If you have a legacy system, it can be overwhelming as a typical system is a mess when it comes to package dependencies. This tutorial shows a way to ease into the verifydesign task instead of fixing everything all at once.</p> + +<p>First, in your build.xml file, use this line to verify your jar(or you can modify it to verify multiple jars)</p> + +<pre> + <verifydesign jar="yourjarname.jar" + design="design.xml" + /> +</pre> + +Now is the hardest part, go ahead and define every package and set the needDepends attribute to false for all of them so your design.xml should look like so + +<pre> + <design> + <package name="first" package="your.first.package" needDepends="false"/> + <package name="second" package="your.second.package" needDepends="false"/> + <package name="third" package="your.third.package" needDepends="false"/> + <package name="fourth" package="your.fourth.package" needDepends="false"/> + <package name="fifth" package="your.fifth.package" needDepends="false"/> + </design> +</pre> + +Please give them better names then first, second, third, etc. You may have 100 packages on some projects and this may take a while to get started, but keep in mind once you are done with this, you are done with the majority of the work and the build will pass once you are done with this too! + +Now comes the fun part, learning about your design. Take a package that you want to start restricting dependencies on and erase the needDepends(by default it's value will be true). Let's take your.first.package and create the new design.xml file like so... + +<pre> + <design> + <package name="first" package="your.first.package"/> + <package name="second" package="your.second.package" needDepends="false"/> + <package name="third" package="your.third.package" needDepends="false"/> + <package name="fourth" package="your.fourth.package" needDepends="false"/> + <package name="fifth" package="your.fifth.package" needDepends="false"/> + </design> +</pre> + +Now we run the build and we get errors that your.first.package depends on second, third, and fourth. Let's pretend we only wanted to depend on second and third. We then change our design file to so... + +<pre> + <design> + <package name="first" package="your.first.package" + <depends>second</depends> + <depends>third</depends> + </package> + <package name="second" package="your.second.package" needDepends="false"/> + <package name="third" package="your.third.package" needDepends="false"/> + <package name="fourth" package="your.fourth.package" needDepends="false"/> + <package name="fifth" package="your.fifth.package" needDepends="false"/> + </design> +</pre> + +Now we run the build and clean up all the code so that first doesn't depend on fourth anymore. This first step can typically take a full release if you are doing this in the margins. That is ok and now forever your.first.package will only depend on second and third until the design file is changed. You have made major progress. I would suggest a package a release. It can clean up dependencies and you will start finding it can be easier to add more and more features and not end up with a wad or mess on your hands. Good luck designing. Refactoring a legacy system can be very challenging and very long with or without this task. This ant task guarantees that you are actually heading in your defined direction. Whether the direction is correct or not is another story :). + +<hr> + <p align="center">Copyright © 2002-2004 Ant-Contrib Project. All + rights Reserved.</p> + +</body> +</html> + diff --git a/docs/manual/tasks/verifynewprojtutorial.html b/docs/manual/tasks/verifynewprojtutorial.html new file mode 100644 index 0000000..96e066d --- /dev/null +++ b/docs/manual/tasks/verifynewprojtutorial.html @@ -0,0 +1,39 @@ +<html lang="en-us"> + +<head> +<meta http-equiv="Content-Language" content="en-us"> +<title>VerifyDesign New Project Tutorial</title> +</head> + +<body> + +<h2>VerifyDesign New Project Tutorial</h2> + +This is by far the easiest tutorial. Before you have any code, add this to your build.xml file. + +<pre> + <verifydesign jar="yourjarname.jar" + design="design.xml" + /> +</pre> + +Create your design.xml file from the design that is in your head or in documentation like so + +<pre> + <design> + <package name="service1" package="biz.xsoftware.service1" subpackages="include"/> + <package name="client1" package="biz.xsoftware.client1" depends="service1"/> + <package name="service2" package="biz.xsoftware.service2"/> + <package name="client2" package="biz.xsoftware.client2" depends="service2" subpackages="include"/> + </design> +</pre> + +From now on, when you run the build, if this is violated like service1 depending on client2 or something, the build will fail and you will catch the errors of violating the design before it is too late. You can then guarantee things like only this package will depend on the JMS technology. This way if you change JMS to something later, you know you only have to change that one package. + +<hr> + <p align="center">Copyright © 2002-2004 Ant-Contrib Project. All + rights Reserved.</p> + +</body> +</html> + |