|
|
@@ -0,0 +1,258 @@ |
|
|
|
|
|
<document> |
|
|
|
|
|
|
|
|
|
|
|
<properties> |
|
|
|
|
|
<author email="adammurdoch@apache.org">Adam Murdoch</author> |
|
|
|
|
|
<title>User Guide</title> |
|
|
|
|
|
</properties> |
|
|
|
|
|
|
|
|
|
|
|
<body> |
|
|
|
|
|
|
|
|
|
|
|
<section name="Project File"> |
|
|
|
|
|
|
|
|
|
|
|
<p> |
|
|
|
|
|
The project file format is very similar to that of Ant 1. The root element of |
|
|
|
|
|
the project file must be a <code><project></code> element. It can |
|
|
|
|
|
take the following attributes: |
|
|
|
|
|
</p> |
|
|
|
|
|
|
|
|
|
|
|
<table> |
|
|
|
|
|
<tr><th>Attribute</th><th>Description</th><th>Default Value</th></tr> |
|
|
|
|
|
<tr> |
|
|
|
|
|
<td>name</td> |
|
|
|
|
|
<td>The project name.</td> |
|
|
|
|
|
<td>The base-name of the project file, with the extension removed.</td> |
|
|
|
|
|
</tr> |
|
|
|
|
|
<tr> |
|
|
|
|
|
<td>basedir</td> |
|
|
|
|
|
<td>The base directory for the project. The base directory is used |
|
|
|
|
|
to resolve all relative file names used in the project file. |
|
|
|
|
|
</td> |
|
|
|
|
|
<td>The directory containing the project file.</td> |
|
|
|
|
|
</tr> |
|
|
|
|
|
<tr> |
|
|
|
|
|
<td>default</td> |
|
|
|
|
|
<td>The name of the default target.</td> |
|
|
|
|
|
<td><code>main</code></td> |
|
|
|
|
|
</tr> |
|
|
|
|
|
<tr> |
|
|
|
|
|
<td>version</td> |
|
|
|
|
|
<td>The project file version that the project is written for.</td> |
|
|
|
|
|
<td>None, must be <code>2.0</code></td> |
|
|
|
|
|
</tr> |
|
|
|
|
|
</table> |
|
|
|
|
|
|
|
|
|
|
|
<p> |
|
|
|
|
|
A <code><project></code> element can contain the following elements, |
|
|
|
|
|
in the order given below: |
|
|
|
|
|
</p> |
|
|
|
|
|
|
|
|
|
|
|
<ul> |
|
|
|
|
|
<li><a href="#Project References"><code><projectref></code></a></li> |
|
|
|
|
|
<li><a href="#Library Imports"><code><import></code></a></li> |
|
|
|
|
|
<li><a href="#Implicit Tasks">Implicit tasks</a></li> |
|
|
|
|
|
<li><a href="#Targets"><code><target></code></a></li> |
|
|
|
|
|
</ul> |
|
|
|
|
|
|
|
|
|
|
|
<subsection name="Project References"> |
|
|
|
|
|
|
|
|
|
|
|
<p>Project references allow the project to import, or reference, other projects. |
|
|
|
|
|
A <code><projectref></code> element takes the following attributes:</p> |
|
|
|
|
|
|
|
|
|
|
|
<table> |
|
|
|
|
|
<tr><th>Attribute</th><th>Description</th><th>Default Value</th></tr> |
|
|
|
|
|
<tr> |
|
|
|
|
|
<td>name</td> |
|
|
|
|
|
<td>The name to use to identify the referenced project.</td> |
|
|
|
|
|
<td>Required</td> |
|
|
|
|
|
</tr> |
|
|
|
|
|
<tr> |
|
|
|
|
|
<td>location</td> |
|
|
|
|
|
<td>The path to the project file to reference.</td> |
|
|
|
|
|
<td>Required</td> |
|
|
|
|
|
</tr> |
|
|
|
|
|
</table> |
|
|
|
|
|
|
|
|
|
|
|
<p> |
|
|
|
|
|
The targets of a referenced project can be used in the <code>depends</code> list |
|
|
|
|
|
of a target in the referencing project, using the following syntax: |
|
|
|
|
|
<code><i>project-name</i>-><i>target-name</i></code>. Here is a simple example:</p> |
|
|
|
|
|
|
|
|
|
|
|
<source><![CDATA[ |
|
|
|
|
|
|
|
|
|
|
|
<project version="2.0"> |
|
|
|
|
|
<!-- Reference another project --> |
|
|
|
|
|
<projectref name="subproject" location="subproject/build.xml"/> |
|
|
|
|
|
|
|
|
|
|
|
<!-- Use the "compile" target from the referenced project --> |
|
|
|
|
|
<target name="main" depends="subproject->compile"> |
|
|
|
|
|
.. do some stuff .. |
|
|
|
|
|
</target> |
|
|
|
|
|
</project> |
|
|
|
|
|
]]></source> |
|
|
|
|
|
|
|
|
|
|
|
</subsection> |
|
|
|
|
|
|
|
|
|
|
|
<subsection name="Library Imports"> |
|
|
|
|
|
|
|
|
|
|
|
<p>Library imports allow the project to import the tasks and data-types from an |
|
|
|
|
|
antlib. An <code><import></code> element takes the following attributes:</p> |
|
|
|
|
|
|
|
|
|
|
|
<table> |
|
|
|
|
|
<tr><th>Attribute</th><th>Description</th><th>Default Value</th></tr> |
|
|
|
|
|
<tr> |
|
|
|
|
|
<td>library</td> |
|
|
|
|
|
<td>The name of the library to import. The <code>ext</code> directory |
|
|
|
|
|
of the Myrmidon distribution is searched for a library file with |
|
|
|
|
|
the given name, and an <code>atl</code> extension.</td> |
|
|
|
|
|
<td>Required</td> |
|
|
|
|
|
</tr> |
|
|
|
|
|
<tr> |
|
|
|
|
|
<td>type</td> |
|
|
|
|
|
<td>The type of definition to import. Values include <code>task</code>, |
|
|
|
|
|
and <code>data-type</code>.</td> |
|
|
|
|
|
<td>None</td> |
|
|
|
|
|
</tr> |
|
|
|
|
|
<tr> |
|
|
|
|
|
<td>name</td> |
|
|
|
|
|
<td>The name of the type to import.</td> |
|
|
|
|
|
<td>None</td> |
|
|
|
|
|
</tr> |
|
|
|
|
|
</table> |
|
|
|
|
|
|
|
|
|
|
|
<p> |
|
|
|
|
|
If the <code>type</code> and <code>name</code> attributes are not provided, |
|
|
|
|
|
the entire contents of the antlib are imported. |
|
|
|
|
|
</p> |
|
|
|
|
|
|
|
|
|
|
|
<p>The following example import the <code><my-task></code> task from |
|
|
|
|
|
the <code>my-tasks</code> antlib.</p> |
|
|
|
|
|
|
|
|
|
|
|
<source><![CDATA[ |
|
|
|
|
|
|
|
|
|
|
|
<project version="2.0"> |
|
|
|
|
|
<!-- Import task <my-task> from the 'my-tasks' antlib. --> |
|
|
|
|
|
<import library="my-tasks" type="task" name="my-task"/> |
|
|
|
|
|
|
|
|
|
|
|
<target name="main"> |
|
|
|
|
|
<my-task some-prop=".."/> |
|
|
|
|
|
</target> |
|
|
|
|
|
</project> |
|
|
|
|
|
]]></source> |
|
|
|
|
|
|
|
|
|
|
|
</subsection> |
|
|
|
|
|
|
|
|
|
|
|
<subsection name="Implicit Tasks"> |
|
|
|
|
|
|
|
|
|
|
|
<p>Implicit tasks are run before any of the project's targets are run. Any task |
|
|
|
|
|
can be used, including <code><property></code> and data-type instances. |
|
|
|
|
|
Implicit tasks can be used to initialise the project. For example:</p> |
|
|
|
|
|
|
|
|
|
|
|
<source><![CDATA[ |
|
|
|
|
|
|
|
|
|
|
|
<project version="2.0"> |
|
|
|
|
|
|
|
|
|
|
|
<property name="some-property" value="some value"/> |
|
|
|
|
|
<path id="classpath"> |
|
|
|
|
|
<fileset dir="lib"/> |
|
|
|
|
|
</path> |
|
|
|
|
|
<log>Set classpath to ${classpath}</log> |
|
|
|
|
|
|
|
|
|
|
|
<target name="main"> |
|
|
|
|
|
.. do some stuff .. |
|
|
|
|
|
</target> |
|
|
|
|
|
|
|
|
|
|
|
</project> |
|
|
|
|
|
]]></source> |
|
|
|
|
|
|
|
|
|
|
|
</subsection> |
|
|
|
|
|
|
|
|
|
|
|
<subsection name="Targets"> |
|
|
|
|
|
|
|
|
|
|
|
<p>Targets have the same format as in Ant 1.x, though some of the behaviour |
|
|
|
|
|
is different. A <code><target></code> element takes the following |
|
|
|
|
|
attributes:</p> |
|
|
|
|
|
|
|
|
|
|
|
<table> |
|
|
|
|
|
<tr><th>Attribute</th><th>Description</th><th>Default Value</th></tr> |
|
|
|
|
|
<tr> |
|
|
|
|
|
<td>name</td> |
|
|
|
|
|
<td>The name of the target.</td> |
|
|
|
|
|
<td>Required</td> |
|
|
|
|
|
</tr> |
|
|
|
|
|
<tr> |
|
|
|
|
|
<td>depends</td> |
|
|
|
|
|
<td>A comma-separated list of targets that this target depends on. |
|
|
|
|
|
This list can contain targets from referenced projects.</td> |
|
|
|
|
|
<td>None</td> |
|
|
|
|
|
</tr> |
|
|
|
|
|
<tr> |
|
|
|
|
|
<td>if</td> |
|
|
|
|
|
<td>Only execute this target if the specified property is set, and not |
|
|
|
|
|
equal to <code>false</code>.</td> |
|
|
|
|
|
<td>None</td> |
|
|
|
|
|
</tr> |
|
|
|
|
|
<tr> |
|
|
|
|
|
<td>unless</td> |
|
|
|
|
|
<td>Do not execute this target if the specified property is set, and not |
|
|
|
|
|
equal to <code>false</code>.</td> |
|
|
|
|
|
<td>None</td> |
|
|
|
|
|
</tr> |
|
|
|
|
|
</table> |
|
|
|
|
|
|
|
|
|
|
|
</subsection> |
|
|
|
|
|
|
|
|
|
|
|
</section> |
|
|
|
|
|
|
|
|
|
|
|
<section name="Tasks"> |
|
|
|
|
|
|
|
|
|
|
|
<p> |
|
|
|
|
|
The following table lists some of the current set of tasks. You can find |
|
|
|
|
|
example usages of these tasks in the sample project file |
|
|
|
|
|
<code>src/make/sample.ant</code>. |
|
|
|
|
|
</p> |
|
|
|
|
|
|
|
|
|
|
|
<table> |
|
|
|
|
|
<tr><th>Task</th><th>Description</th></tr> |
|
|
|
|
|
<tr> |
|
|
|
|
|
<td>fail</td> |
|
|
|
|
|
<td>Causes the build to fail.</td> |
|
|
|
|
|
</tr> |
|
|
|
|
|
<tr> |
|
|
|
|
|
<td>if</td> |
|
|
|
|
|
<td>Conditionally executes a set of tasks.</td> |
|
|
|
|
|
</tr> |
|
|
|
|
|
<tr> |
|
|
|
|
|
<td>load-properties</td> |
|
|
|
|
|
<td>Loads a set of properties from a file.</td> |
|
|
|
|
|
</tr> |
|
|
|
|
|
<tr> |
|
|
|
|
|
<td>log</td> |
|
|
|
|
|
<td>Writes a log message.</td> |
|
|
|
|
|
</tr> |
|
|
|
|
|
<tr> |
|
|
|
|
|
<td>property</td> |
|
|
|
|
|
<td>Sets a property.</td> |
|
|
|
|
|
</tr> |
|
|
|
|
|
<tr> |
|
|
|
|
|
<td>try-catch</td> |
|
|
|
|
|
<td>Runs a set of tasks, with a provided error and clean-up handler.</td> |
|
|
|
|
|
</tr> |
|
|
|
|
|
<tr> |
|
|
|
|
|
<td>converter-def</td> |
|
|
|
|
|
<td>Register a type converter. These are used when configuring a task |
|
|
|
|
|
or data-type from attributes.</td> |
|
|
|
|
|
</tr> |
|
|
|
|
|
<tr> |
|
|
|
|
|
<td>type-def</td> |
|
|
|
|
|
<td>Register a task or data-type.</td> |
|
|
|
|
|
</tr> |
|
|
|
|
|
<tr> |
|
|
|
|
|
<td>import</td> |
|
|
|
|
|
<td>Register the contents of an antlib.</td> |
|
|
|
|
|
</tr> |
|
|
|
|
|
</table> |
|
|
|
|
|
|
|
|
|
|
|
</section> |
|
|
|
|
|
</body> |
|
|
|
|
|
|
|
|
|
|
|
</document> |
Peter Donald