youys
/
ant
Not watched
1
0
Fork 1
Code
Releases 0 Wiki Activity
Issues 0 Pull Requests 0 Datasets Model Cloudbrain
Browse Source

Some doco updates. 

git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@271568 13f79535-47bb-0310-9956-ffa450edef68
master
adammurdoch 23 years ago
parent
939efc95cd
commit
abda44570c
7 changed files with 1710 additions and 873 deletions
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. +15
    -624
      proposal/myrmidon/docs/index.html
  2. +262
    -0
      proposal/myrmidon/docs/todo.html
  3. +913
    -0
      proposal/myrmidon/docs/user.html
  4. +7
    -249
      proposal/myrmidon/src/xdocs/index.xml
  5. +3
    -0
      proposal/myrmidon/src/xdocs/stylesheets/project.xml
  6. +164
    -0
      proposal/myrmidon/src/xdocs/todo.xml
  7. +346
    -0
      proposal/myrmidon/src/xdocs/user.xml

+ 15
- 624
proposal/myrmidon/docs/index.html View File

@@ -11,7 +11,7 @@
<meta name="author" value="Adam Murdoch">
<meta name="email" value="adammurdoch@apache.org">
<title>Apache Myrmidon - Myrmidon</title>
<title>Apache Myrmidon - Introduction</title>
</head>
<body bgcolor="#ffffff" text="#000000" link="#525D76">
@@ -34,6 +34,12 @@
<p><strong>Myrmidon</strong></p>
<ul>
<li> <a href="./index.html">Introduction</a>
</li>
<li> <a href="./user.html">User Guide</a>
</li>
<li> <a href="./todo.html">Get Involved</a>
</li>
<li> <a href="./todo.html#Todo List">Todo List</a>
</li>
</ul>
</td>
@@ -64,8 +70,11 @@ many of the Ant 1.x tasks to the Myrmidon task engine.
</p>
<p>
</p>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#828DA6">
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Differences to Ant 1.x"><strong>Differences to Ant 1.x</strong></a>
</font>
@@ -90,6 +99,8 @@ Changes to the property model:
<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>
<li><code>if</code> and <code>unless</code> checks now test the property
value against <code>false</code>, in addition to testing set/not-set.</li>
</ul>
</li>

@@ -120,627 +131,7 @@ tasks to do their work without depending on other tasks:
</li>

</ul>
</blockquote>
</td></tr>
</table>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Building Myrmidon"><strong>Building Myrmidon</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<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>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Running Myrmidon"><strong>Running Myrmidon</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
To run Myrmidon, use one of the following methods:
</p>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#828DA6">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Launcher Script"><strong>Launcher Script</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<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>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Variable
</font>
</td>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Description
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
JAVA_HOME
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The directory that the JDK is installed in.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
JAVACMD
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The command to use to start the JVM. Defaults to <code>java</code>.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
ANT_HOME
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The directory containing the Myrmidon distribution. This must be
set when running on Windows 95, 98 or Me.
</font>
</td>
</tr>
</table>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#828DA6">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Executable Jar File"><strong>Executable Jar File</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
The Myrmidon distribution includes an executable Jar file, which can be used
to run Myrmidon. Use the following command:
</p>
<pre>
prompt&gt; <i>java</i> -jar <i>ant-home</i>/bin/myrmidon-launcher.jar <i>options</i>
</pre>
</blockquote>
</td></tr>
</table>
<p>
Run Myrmidon with the <code>-h</code> command-line option for a list of
the command-line options that are available.
</p>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Project File"><strong>Project File</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<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>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Attribute
</font>
</td>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Description
</font>
</td>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Default Value
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
name
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The project name.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The name of the project file, with the extension removed.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
basedir
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The base directory for the project.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The directory containing the project file.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
default
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The name of the default target.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
<code>main</code>
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
version
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The project file version that the project is written for.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
None, must be <code>2.0</code>
</font>
</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>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#828DA6">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Project References"><strong>Project References</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<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>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Attribute
</font>
</td>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Description
</font>
</td>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Default Value
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
name
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The name to use to identify the referenced project.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Required
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
location
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The path to the project file to reference.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Required
</font>
</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>-&gt;<i>target-name</i></code>.
</p>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#828DA6">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Library Imports"><strong>Library Imports</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<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>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Attribute
</font>
</td>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Description
</font>
</td>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Default Value
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
library
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
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.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Required
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
type
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The type of definition to import. Values include <code>task</code>,
and <code>data-type</code>.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
None
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
name
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The name of the type to import.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
None
</font>
</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>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#828DA6">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Implicit Tasks"><strong>Implicit Tasks</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>Implicit tasks are run before any of the project's targets are run.</p>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#828DA6">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Targets"><strong>Targets</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>Targets are the same as Ant 1.x.</p>
</blockquote>
</td></tr>
</table>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Tasks"><strong>Tasks</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<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>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
fail
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Causes the build to fail.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
if
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Conditionally executes a set of tasks.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
load-properties
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Loads a set of properties from a file.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
log
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Writes a log message.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
property
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Sets a property.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
try-catch
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Runs a set of tasks, with a provided error and clean-up handler.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
converter-def
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Register a type converter. These are used when configuring a task
or data-type from attributes.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
type-def
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Register a task or data-type.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
import
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Register the contents of an antlib.
</font>
</td>
</tr>
</table>
<p>There are plenty more features planned. You can read about them <a href="todo.html">here</a>.</p>
</blockquote>
</td></tr>
</table>


+ 262
- 0
proposal/myrmidon/docs/todo.html View File

@@ -0,0 +1,262 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

<!-- Content Stylesheet for Site -->

<!-- start the processing -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
<meta name="author" value="Adam Murdoch">
<meta name="email" value="adammurdoch@apache.org">
<title>Apache Myrmidon - Get Involved</title>
</head>
<body bgcolor="#ffffff" text="#000000" link="#525D76">
<table border="0" width="100%" cellspacing="0">
<!-- TOP IMAGE -->
<tr>
<td colspan="2">
<a href="http://jakarta.apache.org"><img src="http://jakarta.apache.org/images/jakarta-logo.gif" align="left" border="0"/></a>
</td>
</tr>
</table>
<table border="0" width="100%" cellspacing="4">
<tr><td colspan="2">
<hr noshade="" size="1"/>
</td></tr>
<tr>
<!-- LEFT SIDE NAVIGATION -->
<td valign="top" nowrap="true">
<p><strong>Myrmidon</strong></p>
<ul>
<li> <a href="./index.html">Introduction</a>
</li>
<li> <a href="./user.html">User Guide</a>
</li>
<li> <a href="./todo.html">Get Involved</a>
</li>
<li> <a href="./todo.html#Todo List">Todo List</a>
</li>
</ul>
</td>
<td align="left" valign="top">
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Get Involved"><strong>Get Involved</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>There are plenty of things you can do to help out with Myrmidon. The Todo
list below describes items which still need to be done. Of course, since
this is an open-source project, there's plenty of scope for experimentation,
and you can pretty much make up your own items to work on.</p>
<p>Some things that are worth reading if you do want to get involved:</p>
<ul>
<li>The <a href="http://jakarta.apache.org/ant/ant2/">Ant 2</a> goals and requirements.</li>
<li>The <a href="http://jakarta.apache.org/ant/ant2/actionlist.html">Ant 1.9 Action List</a>.</li>
<li>The Jakarta Project's <a href="http://jakarta.apache.org/site/getinvolved.html">Get Involved</a> page.</li>
</ul>
<p>There is no Ant 2 or Myrmidon mailing list yet, so direct any questions
or comments you have to the ant-dev mailing list.</p>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Todo List"><strong>Todo List</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>The broad goal is to grow Myrmidon from a prototype task engine into a fully
fledged build system, that can serve as the basis for Ant 2. The following
sections describe some of the many things which still need to be done to
achieve that goal. This list is currently under construction.</p>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#828DA6">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Self Hosting"><strong>Self Hosting</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>Myrmidon must be able to build itself. Currently, it is built using
Ant 1.x. Ultimately, Myrmidon should be able to build itself from exactly the
same build file. To start with, however, there is no need for Myrmidon to be
able to do this. Myrmidon should also be able to be bootstrapped (that is, be
able to be built from scratch, without using Ant 1.x at all).</p>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#828DA6">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Ant 1.x Compatibility"><strong>Ant 1.x Compatibility</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>There are 2 parts to this broad topic: Allow Ant 1.x build scripts to be
executed by Myrmidon, and allow Ant 1.x tasks to be executed unmodified
by Myrmidon.</p>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#828DA6">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Virtual File System"><strong>Virtual File System</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>The VFS needs plenty of work:</p>
<ul>
<li>Move and copy files/folders.</li>
<li>Search through a file hierarchy, using Ant-style wildcards.</li>
<li>Search through a file hierarchy, using a Selector interface.</li>
<li>The in-memory caching mechanism is pretty rudimentary at this stage.
It needs work to make it size capped. In addition, some mechanism needs
to be provided to release and refresh cached info.
</li>
<li>Capabilities discovery.</li>
<li>Attributes and attribute schema.</li>
<li>File system layering. That is, the ability for a file system to
sit on top of another file system, or a file from another file system
(e.g. Zip/Jar/Tar file systems, gzip/encoding file systems, virtual file
systems).
</li>
</ul>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#828DA6">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Command-line and Configuration Files"><strong>Command-line and Configuration Files</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>One of the goals of Ant 2 is to allow the user to easily customise and
extend Ant. The command-line and local configuration files, are two places
where this would be done. Currently, Myrmidon some customisation from the
command-line, but does not support configuration files.</p>
<ul>

<li>Load configuration from system (from $ANT_HOME) and user (from $HOME)
configuration files.</li>

<li>Allow the following via config files:
<ul>
<li>Add (or override) the <code>lib</code> and <code>ext</code> directories.</li>
<li>Enable more than one listener, and configure the listeners from
the conents of the config file.</li>
<li>Import libraries, and set properties.</li>
<li>Execute tasks.</li>
<li>Install and configure runtime services.</li>
</ul>
</li>

</ul>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#828DA6">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Documentation"><strong>Documentation</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>Everyone loves writing documentation, and so a goal for Ant 2 is to
generate a lot of reference documentation for tasks and other types directly
from the source. Unfortunately, there's still plenty of tutorial material
to write. In particular we need these:</p>
<ul>
<li>User documentation - describing things like the build file format,
how properties work, how to use references, how sub-builds work, how to customise
Myrmidon, and so on.</li>

<li>Task writer documentation - describing things like an overview the task API,
how configuration works, task lifecycle, how to assemble an antlib, a catalog
of the runtime services, and so on.</li>

<li>Myrmidon developer documentation - a broad outline of the architecture,
how to build, how to test, and so on. Also, this todo list needs plenty
of filling out.</li>

</ul>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#828DA6">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Miscellaneous"><strong>Miscellaneous</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>A completely unordered list of items, big and small:</p>
<ul>
<li>Search through the code for 'TODO' items and fix them.</li>
<li>Add a custom task to the build to generate antlib descriptors from source.
It would wrap XDoclet, and replace <code>antlib.xml</code>.</li>
<li>Tidy-up CLIMain so that it calls System.exit() with a non-zero exit code,
if the build fails.</li>
<li>Tidy-up the 'build failed' message, so that the stack trace is only
printed out if the log level is verbose/debug.</li>
<li>Allow service factories to be configured from the contents of the
<code>ant-services.xml</code> descriptor.</li>
<li>Route external process stdout and stderr through the logger.</li>
<li>Add verbosity level to ProjectListener LogEvent</li>
<li>Fire ProjectListener events taskFinished(), targetFinished() and
projectFinished() events on build failure, adding indicator methods to
ProjectEvent.</li>
<li>Fire ProjectListener events projectStarted() and projectFinished()
events on start and finish of referenced projects, adding indicator methods
to ProjectEvent.</li>
<li>Convert PropertyUtil to a non-static PropertyResolver service.</li>
<li>Validate project and target names in DefaultProjectBuilder - reject dodgy
names like "," or "", or " ". Probably want to exclude names that start or
end with white-space (though internal whitespace is probably fine).</li>
<li>Detect duplicate type names.</li>
<li>Add fully qualified type names, based on antlib name and type shorthand name.
Allow these to be used in build files in addition to the shorthand names.</li>
<li>Unit tests.</li>
</ul>
</blockquote>
</td></tr>
</table>
</blockquote>
</td></tr>
</table>
</td>
</tr>

<!-- FOOTER -->
<tr><td colspan="2">
<hr noshade="" size="1"/>
</td></tr>
<tr><td colspan="2">
<div align="center"><font color="#525D76" size="-1"><em>
Copyright &#169; 2000-2002, Apache Software Foundation
</em></font></div>
</td></tr>
</table>
</body>
</html>
<!-- end the processing -->





+ 913
- 0
proposal/myrmidon/docs/user.html View File

@@ -0,0 +1,913 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">

<!-- Content Stylesheet for Site -->

<!-- start the processing -->
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
<meta name="author" value="Adam Murdoch">
<meta name="email" value="adammurdoch@apache.org">
<title>Apache Myrmidon - User Guide</title>
</head>
<body bgcolor="#ffffff" text="#000000" link="#525D76">
<table border="0" width="100%" cellspacing="0">
<!-- TOP IMAGE -->
<tr>
<td colspan="2">
<a href="http://jakarta.apache.org"><img src="http://jakarta.apache.org/images/jakarta-logo.gif" align="left" border="0"/></a>
</td>
</tr>
</table>
<table border="0" width="100%" cellspacing="4">
<tr><td colspan="2">
<hr noshade="" size="1"/>
</td></tr>
<tr>
<!-- LEFT SIDE NAVIGATION -->
<td valign="top" nowrap="true">
<p><strong>Myrmidon</strong></p>
<ul>
<li> <a href="./index.html">Introduction</a>
</li>
<li> <a href="./user.html">User Guide</a>
</li>
<li> <a href="./todo.html">Get Involved</a>
</li>
<li> <a href="./todo.html#Todo List">Todo List</a>
</li>
</ul>
</td>
<td align="left" valign="top">
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Building Myrmidon"><strong>Building Myrmidon</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<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>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Running Myrmidon"><strong>Running Myrmidon</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
To run Myrmidon, use one of the following methods:
</p>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#828DA6">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Launcher Script"><strong>Launcher Script</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<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>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Variable
</font>
</td>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Description
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
JAVA_HOME
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The directory that the JDK is installed in.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
JAVACMD
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The command to use to start the JVM. Defaults to <code>java</code>.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
ANT_HOME
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The directory containing the Myrmidon distribution. This must be
set when running on Windows 95, 98 or Me.
</font>
</td>
</tr>
</table>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#828DA6">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Executable Jar File"><strong>Executable Jar File</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
The Myrmidon distribution includes an executable Jar file, which can be used
to run Myrmidon. Use the following command:
</p>
<pre>
prompt&gt; <i>java</i> -jar <i>ant-home</i>/bin/myrmidon-launcher.jar <i>options</i>
</pre>
</blockquote>
</td></tr>
</table>
<p>When started, Myrmidon looks for a project file called <code>build.ant</code>
in the current directory. A different project file can be specified using the
<code>-f</code> command-line option. Myrmidon executes the targets given on
the command-line, or the default target if none is given. For example, the
following executes the targets <code>clean</code> and <code>build</code> from
the project file <code>my-project.xml</code>:</p>
<pre>
prompt&gt; ant -f my-project.xml clean build
</pre>
<p>
Run Myrmidon with the <code>-h</code> command-line option for a list of
the command-line options that are available.
</p>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Project File"><strong>Project File</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<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>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Attribute
</font>
</td>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Description
</font>
</td>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Default Value
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
name
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The project name.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The base-name of the project file, with the extension removed.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
basedir
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The base directory for the project. The base directory is used
to resolve all relative file names used in the project file.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The directory containing the project file.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
default
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The name of the default target.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
<code>main</code>
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
version
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The project file version that the project is written for.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
None, must be <code>2.0</code>
</font>
</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>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#828DA6">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Project References"><strong>Project References</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<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>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Attribute
</font>
</td>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Description
</font>
</td>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Default Value
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
name
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The name to use to identify the referenced project.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Required
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
location
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The path to the project file to reference.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Required
</font>
</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>-&gt;<i>target-name</i></code>. Here is a simple example:</p>
<div align="left">
<table cellspacing="4" cellpadding="0" border="0">
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#ffffff"><pre>

&lt;project version=&quot;2.0&quot;&gt;
&lt;!-- Reference another project --&gt;
&lt;projectref name=&quot;subproject&quot; location=&quot;subproject/build.xml&quot;/&gt;

&lt;!-- Use the &quot;compile&quot; target from the referenced project --&gt;
&lt;target name=&quot;main&quot; depends=&quot;subproject-&gt;compile&quot;&gt;
.. do some stuff ..
&lt;/target&gt;
&lt;/project&gt;
</pre></td>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
</table>
</div>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#828DA6">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Library Imports"><strong>Library Imports</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<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>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Attribute
</font>
</td>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Description
</font>
</td>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Default Value
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
library
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
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.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Required
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
type
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The type of definition to import. Values include <code>task</code>,
and <code>data-type</code>.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
None
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
name
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The name of the type to import.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
None
</font>
</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>&lt;my-task&gt;</code> task from
the <code>my-tasks</code> antlib.</p>
<div align="left">
<table cellspacing="4" cellpadding="0" border="0">
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#ffffff"><pre>

&lt;project version=&quot;2.0&quot;&gt;
&lt;!-- Import task &lt;my-task&gt; from the 'my-tasks' antlib. --&gt;
&lt;import library=&quot;my-tasks&quot; type=&quot;task&quot; name=&quot;my-task&quot;/&gt;

&lt;target name=&quot;main&quot;&gt;
&lt;my-task some-prop=&quot;..&quot;/&gt;
&lt;/target&gt;
&lt;/project&gt;
</pre></td>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
</table>
</div>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#828DA6">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Implicit Tasks"><strong>Implicit Tasks</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>Implicit tasks are run before any of the project's targets are run. Any task
can be used, including <code>&lt;property&gt;</code> and data-type instances.
Implicit tasks can be used to initialise the project. For example:</p>
<div align="left">
<table cellspacing="4" cellpadding="0" border="0">
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#ffffff"><pre>

&lt;project version=&quot;2.0&quot;&gt;

&lt;property name=&quot;some-property&quot; value=&quot;some value&quot;/&gt;
&lt;path id=&quot;classpath&quot;&gt;
&lt;fileset dir=&quot;lib&quot;/&gt;
&lt;/path&gt;
&lt;log&gt;Set classpath to ${classpath}&lt;/log&gt;

&lt;target name=&quot;main&quot;&gt;
.. do some stuff ..
&lt;/target&gt;

&lt;/project&gt;
</pre></td>
<td bgcolor="#023264" width="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
<tr>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
<td bgcolor="#023264" width="1" height="1"><img src="/images/void.gif" width="1" height="1" vspace="0" hspace="0" border="0"/></td>
</tr>
</table>
</div>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#828DA6">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Targets"><strong>Targets</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>Targets have the same format as in Ant 1.x, though some of the behaviour
is different. A <code>&lt;target&gt;</code> element takes the following
attributes:</p>
<table>
<tr>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Attribute
</font>
</td>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Description
</font>
</td>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Default Value
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
name
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
The name of the target.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Required
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
depends
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
A comma-separated list of targets that this target depends on.
This list can contain targets from referenced projects.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
None
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
if
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Only execute this target if the specified property is set, and not
equal to <code>false</code>.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
None
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
unless
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Do not execute this target if the specified property is set, and not
equal to <code>false</code>.
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
None
</font>
</td>
</tr>
</table>
</blockquote>
</td></tr>
</table>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#525D76">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Tasks"><strong>Tasks</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<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>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Task
</font>
</td>
<td bgcolor="#039acc" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Description
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
fail
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Causes the build to fail.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
if
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Conditionally executes a set of tasks.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
load-properties
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Loads a set of properties from a file.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
log
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Writes a log message.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
property
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Sets a property.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
try-catch
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Runs a set of tasks, with a provided error and clean-up handler.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
converter-def
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Register a type converter. These are used when configuring a task
or data-type from attributes.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
type-def
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Register a task or data-type.
</font>
</td>
</tr>
<tr>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
import
</font>
</td>
<td bgcolor="#a0ddf0" colspan="" rowspan=""
valign="top" align="left">
<font color="#000000" size="-1" face="arial,helvetica,sanserif">
Register the contents of an antlib.
</font>
</td>
</tr>
</table>
</blockquote>
</td></tr>
</table>
</td>
</tr>

<!-- FOOTER -->
<tr><td colspan="2">
<hr noshade="" size="1"/>
</td></tr>
<tr><td colspan="2">
<div align="center"><font color="#525D76" size="-1"><em>
Copyright &#169; 2000-2002, Apache Software Foundation
</em></font></div>
</td></tr>
</table>
</body>
</html>
<!-- end the processing -->





+ 7
- 249
proposal/myrmidon/src/xdocs/index.xml View File

@@ -2,7 +2,7 @@

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

<body>
@@ -31,7 +31,9 @@ many of the Ant 1.x tasks to the Myrmidon task engine.
<p>
</p>

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

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

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

@@ -52,6 +54,8 @@ Changes to the property model:
<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>
<li><code>if</code> and <code>unless</code> checks now test the property
value against <code>false</code>, in addition to testing set/not-set.</li>
</ul>
</li>

@@ -83,256 +87,10 @@ tasks to do their work without depending on other tasks:

</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>
<p>There are plenty more features planned. You can read about them <a href="todo.html">here</a>.</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>name</td>
<td>The project name.</td>
<td>The name of the project file, with the extension removed.</td>
</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>

+ 3
- 0
proposal/myrmidon/src/xdocs/stylesheets/project.xml View File

@@ -5,6 +5,9 @@
<body>
<menu name="Myrmidon">
<item name="Introduction" href="/index.html"/>
<item name="User Guide" href="/user.html"/>
<item name="Get Involved" href="/todo.html"/>
<item name="Todo List" href="/todo.html#Todo List"/>
</menu>
</body>



+ 164
- 0
proposal/myrmidon/src/xdocs/todo.xml View File

@@ -0,0 +1,164 @@
<document>

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

<body>
<section name="Get Involved">

<p>There are plenty of things you can do to help out with Myrmidon. The Todo
list below describes items which still need to be done. Of course, since
this is an open-source project, there's plenty of scope for experimentation,
and you can pretty much make up your own items to work on.</p>

<p>Some things that are worth reading if you do want to get involved:</p>
<ul>
<li>The <a href="http://jakarta.apache.org/ant/ant2/">Ant 2</a> goals and requirements.</li>
<li>The <a href="http://jakarta.apache.org/ant/ant2/actionlist.html">Ant 1.9 Action List</a>.</li>
<li>The Jakarta Project's <a href="http://jakarta.apache.org/site/getinvolved.html">Get Involved</a> page.</li>
</ul>

<p>There is no Ant 2 or Myrmidon mailing list yet, so direct any questions
or comments you have to the ant-dev mailing list.</p>

</section>

<section name="Todo List">

<p>The broad goal is to grow Myrmidon from a prototype task engine into a fully
fledged build system, that can serve as the basis for Ant 2. The following
sections describe some of the many things which still need to be done to
achieve that goal. This list is currently under construction.</p>

<subsection name="Self Hosting">

<p>Myrmidon must be able to build itself. Currently, it is built using
Ant 1.x. Ultimately, Myrmidon should be able to build itself from exactly the
same build file. To start with, however, there is no need for Myrmidon to be
able to do this. Myrmidon should also be able to be bootstrapped (that is, be
able to be built from scratch, without using Ant 1.x at all).</p>

</subsection>

<subsection name="Ant 1.x Compatibility">

<p>There are 2 parts to this broad topic: Allow Ant 1.x build scripts to be
executed by Myrmidon, and allow Ant 1.x tasks to be executed unmodified
by Myrmidon.</p>

</subsection>

<subsection name="Virtual File System">

<p>The VFS needs plenty of work:</p>

<ul>
<li>Move and copy files/folders.</li>
<li>Search through a file hierarchy, using Ant-style wildcards.</li>
<li>Search through a file hierarchy, using a Selector interface.</li>
<li>The in-memory caching mechanism is pretty rudimentary at this stage.
It needs work to make it size capped. In addition, some mechanism needs
to be provided to release and refresh cached info.
</li>
<li>Capabilities discovery.</li>
<li>Attributes and attribute schema.</li>
<li>File system layering. That is, the ability for a file system to
sit on top of another file system, or a file from another file system
(e.g. Zip/Jar/Tar file systems, gzip/encoding file systems, virtual file
systems).
</li>
</ul>

</subsection>

<subsection name="Command-line and Configuration Files">

<p>One of the goals of Ant 2 is to allow the user to easily customise and
extend Ant. The command-line and local configuration files, are two places
where this would be done. Currently, Myrmidon some customisation from the
command-line, but does not support configuration files.</p>

<ul>

<li>Load configuration from system (from $ANT_HOME) and user (from $HOME)
configuration files.</li>

<li>Allow the following via config files:
<ul>
<li>Add (or override) the <code>lib</code> and <code>ext</code> directories.</li>
<li>Enable more than one listener, and configure the listeners from
the conents of the config file.</li>
<li>Import libraries, and set properties.</li>
<li>Execute tasks.</li>
<li>Install and configure runtime services.</li>
</ul>
</li>

</ul>

</subsection>

<subsection name="Documentation">

<p>Everyone loves writing documentation, and so a goal for Ant 2 is to
generate a lot of reference documentation for tasks and other types directly
from the source. Unfortunately, there's still plenty of tutorial material
to write. In particular we need these:</p>

<ul>
<li>User documentation - describing things like the build file format,
how properties work, how to use references, how sub-builds work, how to customise
Myrmidon, and so on.</li>

<li>Task writer documentation - describing things like an overview the task API,
how configuration works, task lifecycle, how to assemble an antlib, a catalog
of the runtime services, and so on.</li>

<li>Myrmidon developer documentation - a broad outline of the architecture,
how to build, how to test, and so on. Also, this todo list needs plenty
of filling out.</li>

</ul>

</subsection>

<subsection name="Miscellaneous">

<p>A completely unordered list of items, big and small:</p>

<ul>
<li>Search through the code for 'TODO' items and fix them.</li>
<li>Add a custom task to the build to generate antlib descriptors from source.
It would wrap XDoclet, and replace <code>antlib.xml</code>.</li>
<li>Tidy-up CLIMain so that it calls System.exit() with a non-zero exit code,
if the build fails.</li>
<li>Tidy-up the 'build failed' message, so that the stack trace is only
printed out if the log level is verbose/debug.</li>
<li>Allow service factories to be configured from the contents of the
<code>ant-services.xml</code> descriptor.</li>
<li>Route external process stdout and stderr through the logger.</li>
<li>Add verbosity level to ProjectListener LogEvent</li>
<li>Fire ProjectListener events taskFinished(), targetFinished() and
projectFinished() events on build failure, adding indicator methods to
ProjectEvent.</li>
<li>Fire ProjectListener events projectStarted() and projectFinished()
events on start and finish of referenced projects, adding indicator methods
to ProjectEvent.</li>
<li>Convert PropertyUtil to a non-static PropertyResolver service.</li>
<li>Validate project and target names in DefaultProjectBuilder - reject dodgy
names like "," or "", or " ". Probably want to exclude names that start or
end with white-space (though internal whitespace is probably fine).</li>
<li>Detect duplicate type names.</li>
<li>Add fully qualified type names, based on antlib name and type shorthand name.
Allow these to be used in build files in addition to the shorthand names.</li>
<li>Unit tests.</li>
</ul>

</subsection>

</section>

</body>
</document>

+ 346
- 0
proposal/myrmidon/src/xdocs/user.xml View File

@@ -0,0 +1,346 @@
<document>

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

<body>

<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>When started, Myrmidon looks for a project file called <code>build.ant</code>
in the current directory. A different project file can be specified using the
<code>-f</code> command-line option. Myrmidon executes the targets given on
the command-line, or the default target if none is given. For example, the
following executes the targets <code>clean</code> and <code>build</code> from
the project file <code>my-project.xml</code>:</p>

<pre>
prompt> ant -f my-project.xml clean build
</pre>

<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>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>&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>. 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>&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>

<p>The following example import the <code>&lt;my-task&gt;</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>&lt;property&gt;</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>&lt;target&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 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>

Write Preview
Loading…
Cancel
Save
Please read the following content carefully:

Dear OpenI User

Thank you for your continuous support to the Openl Qizhi Community AI Collaboration Platform. In order to protect your usage rights and ensure network security, we updated the Openl Qizhi Community AI Collaboration Platform Usage Agreement in January 2024. The updated agreement specifies that users are prohibited from using intranet penetration tools. After you click "Agree and continue", you can continue to use our services. Thank you for your cooperation and understanding.

For more agreement content, please refer to the《Openl Qizhi Community AI Collaboration Platform Usage Agreement》

Agree and continue
Disagree, exit