youys
/
ant

 
			
							<document>

<properties>
<author email="adammurdoch@apache.org">Adam Murdoch</author>
<title>Myrmidon</title>
</properties>

<body>

<section name="What is Myrmidon?">

<p>
Myrmidon is one of the Ant 2 proposals currently in development.  You can
read more about the goals of Ant 2
<a href="http://jakarta.apache.org/ant/ant2/">here</a>.
</p>

<p>
Myrmidon is a general-purpose <i>task engine</i>.  It contains the basic
building blocks for assembling any sort of task-based tool.  Ant 2
is an example of such a tool, which could be assembled using the Myrmidon task
engine, and a library of build related tasks.
</p>

<p>
Currently, Myrmidon is a prototype of what a task engine might look.  It
includes a small set of tasks and data types.  We are currently porting
many of the Ant 1.x tasks to the Myrmidon task engine.
</p>

<p>
</p>

<subsection name="Differences to Ant 1.x">

<p>Some of the differences between Ant 1.x and Myrmidon:</p>

<ul>

<li>
Groups of tasks can be assembled into self-describing <i>antlib</i> task
libraries.  This makes it very easy to distribute and install tasks and data-types.
</li>

<li>
A project can import other projects, and reference their targets.
</li>

<li>
Changes to the property model:
<ul>
    <li>Properties and data type references now share the same namespace.</li>
    <li>Properties are mutable.</li>
    <li>Properties are scoped into global, local, and parent contexts.</li>
</ul>
</li>

<li>
Changes to task and data-type API:
<ul>
    <li>An interface based API, through which a task interacts with the
    task engine, and the services it provides.</li>
    <li>A well-defined object lifecycle.</li>
    <li>Polymorphic types are supported when objects are configured.</li>
    <li>Reference handling is handled automatically when objects are configured.</li>
    <li>Aspects can be used to decorate tasks, to add facilities like logging,
    error handling, or user preferences.</li>
</ul>
</li>

<li>
A set of well-defined services and APIs have been introduced, to allow
tasks to do their work without depending on other tasks:
<ul>
    <li>Execute external commands.</li>
    <li>Execute other tasks.</li>
    <li>Manage ClassLoaders and Class-paths.</li>
    <li>Virtual file system (in progress).</li>
    <li>Execute Java applications (in progress).</li>
    <li>...</li>
</ul>
</li>

</ul>

</subsection>

</section>

<section name="Building Myrmidon">

<p>
First, you will need to fetch the Myrmidon source from CVS.  The source
can be source in the <code>proposal/myrmidon</code> directory of the
Ant source tree.  You should check out the <code>jakarta-ant</code> CVS
module, as described
<a href="http://jakarta.apache.org/site/cvsindex.html">here</a>.
</p>

<p>
To build Myrmidon, use the <code>build.xml</code> build script.  You will need
to use Ant 1.4.1 or later.  The default target builds the Myrmidon distribution
into the <code>dist</code> directory.  The distribution is a ready-to-run
installation of Myrmidon.
</p>

</section>

<section name="Running Myrmidon">

<p>
To run Myrmidon, use one of the following methods:
</p>

<subsection name="Launcher Script">

<p>
On Windows and Unix platforms, you can use the <code>ant</code> script
in the distribution's <code>bin</code> directory.  The following environment
variables can be used, but are not required (except on Windows 9x - see below).
</p>

<p>

</p>

<table>
    <tr><th>Variable</th><th>Description</th></tr>
    <tr>
        <td>JAVA_HOME</td>
        <td>The directory that the JDK is installed in.</td>
    </tr>
    <tr>
        <td>JAVACMD</td>
        <td>The command to use to start the JVM.  Defaults to <code>java</code>.</td>
    </tr>
    <tr>
        <td>ANT_HOME</td>
        <td>
            The directory containing the Myrmidon distribution.  This must be
            set when running on Windows 95, 98 or Me.
        </td>
    </tr>
</table>

</subsection>

<subsection name="Executable Jar File">

<p>
The Myrmidon distribution includes an executable Jar file, which can be used
to run Myrmidon.  Use the following command:
</p>
<pre>
prompt> <i>java</i> -jar <i>ant-home</i>/bin/myrmidon-launcher.jar <i>options</i>
</pre>

</subsection>

<p>
Run Myrmidon with the <code>-h</code> command-line option for a list of
the command-line options that are available.
</p>

</section>

<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>&lt;project&gt;</code> element.  It can
take the following attributes:
</p>

<table>
    <tr><th>Attribute</th><th>Description</th><th>Default Value</th></tr>
    <tr>
        <td>basedir</td>
        <td>The base directory for the project.</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>&lt;project&gt;</code> element can contain the following elements,
in the order given below:
</p>

<ul>
<li><a href="#Project References"><code>&lt;projectref&gt;</code></a></li>
<li><a href="#Library Imports"><code>&lt;import&gt;</code></a></li>
<li><a href="#Implicit Tasks">Implicit tasks</a></li>
<li><a href="#Targets"><code>&lt;target&gt;</code></a></li>
</ul>

<subsection name="Project References">

<p>Project references allow the project to import, or reference, other projects.
A <code>&lt;projectref&gt;</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>.
</p>

</subsection>

<subsection name="Library Imports">

<p>Library imports allow the project to import the tasks and data-types from an
antlib.  An <code>&lt;import&gt;</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>

</subsection>

<subsection name="Implicit Tasks">

<p>Implicit tasks are run before any of the project's targets are run.</p>

</subsection>

<subsection name="Targets">

<p>Targets are the same as Ant 1.x.</p>

</subsection>


</section>

<section name="Tasks">

<p>
The following table lists 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>
    <td><th>Task</th><th>Description</th></td>
    <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>