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

Converted Ant1 Compatibility layer README to xdoc, 

and updated the docs.


git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@271949 13f79535-47bb-0310-9956-ffa450edef68
master
Darrell DeBoer 23 years ago
parent
ee35557dea
commit
214bb47106
14 changed files with 549 additions and 127 deletions
Split View
Diff Options
Show Stats Download Patch File Download Diff File
  1. +223
    -0
      proposal/myrmidon/docs/ant1compat.html
  2. +2
    -0
      proposal/myrmidon/docs/buildfile.html
  3. +2
    -0
      proposal/myrmidon/docs/classloader.html
  4. +2
    -0
      proposal/myrmidon/docs/getinvolved.html
  5. +2
    -0
      proposal/myrmidon/docs/index.html
  6. +2
    -0
      proposal/myrmidon/docs/librarys.html
  7. +2
    -0
      proposal/myrmidon/docs/task.html
  8. +173
    -64
      proposal/myrmidon/docs/todo.html
  9. +2
    -0
      proposal/myrmidon/docs/user.html
  10. +2
    -0
      proposal/myrmidon/docs/vfs.html
  11. +0
    -58
      proposal/myrmidon/src/ant1compat/README.txt
  12. +112
    -0
      proposal/myrmidon/src/xdocs/ant1compat.xml
  13. +1
    -0
      proposal/myrmidon/src/xdocs/stylesheets/project.xml
  14. +24
    -5
      proposal/myrmidon/src/xdocs/todo.xml

+ 223
- 0
proposal/myrmidon/docs/ant1compat.html View File

@@ -0,0 +1,223 @@
<!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="Darrell DeBoer">
<meta name="email" value="darrell at apache dot org">
<title>Apache Myrmidon - Ant1 Compatibitlity Layer</title>
</head>
<body bgcolor="#ffffff" text="#000000" link="#525D76">
<table border="0" width="100%" cellspacing="0">
<!-- TOP IMAGE -->
<tr>
<td> <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>
</td>
<td valign="bottom"><div align="right"><b><font size="+3" color="#525D76">Apache Myrmidon</font></b></div></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="./getinvolved.html">Get Involved</a>
</li>
<li> <a href="./user.html">Building Myrmidon</a>
</li>
<li> <a href="./todo.html">Todo List</a>
</li>
</ul>
<p><strong>User Guide</strong></p>
<ul>
<li> <a href="./buildfile.html">Build file</a>
</li>
<li> <a href="./vfs.html">Virtual File System</a>
</li>
<li> <a href="./ant1compat.html">Ant1 Compatibility Layer</a>
</li>
</ul>
<p><strong>Extending Ant</strong></p>
<ul>
<li> <a href="./task.html">Task Writers HOWTO</a>
</li>
<li> <a href="./classloader.html">ClassLoader HOWTO</a>
</li>
<li> <a href="./librarys.html">Library HOWTO</a>
</li>
</ul>
<p><strong>Container Design</strong></p>
<ul>
</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="Overview"><strong>Overview</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
The Myrmidon-Ant1 Compatibility layer works by reusing most of the Ant1 code,
with tasks and datatypes
being prefixed with "ant1." in build files. Almost all of the main Ant1 tree
is included in the compatibility layer antlib. To insulate from changes in
the Ant1 tree, Ant1 class files are extracted from a jar, rather than
being compiled from scratch.
</p>
<p>
Here's how it works: The first time an Ant1 task is encountered, an Ant1
project is created, and stored in the TaskContext under the name "ant1.project".
The Ant1 versions of Task and Project have been extended, overriding core behaviour,
with Myrmidon-specific behaviour.
</p>
<p>
The updated version of Task implements Configurable, receiving it's
complete Task Model, and actually setting/adding/creating attributes
with the help of the IntrospectionHelper. This process is designed to
mimic the Ant1 configuration policy, although not <i>all</i> of the
subtle variations of configuration present in Ant1 are handled.
</p>
<p>
The updated version of Project will provide hooks into the Myrmidon TaskContext,
such as:</p>
<ul>
<li>logging (done)</li>
<li>properties (done)</li>
<li>references (not yet done)</li>
<li>Task defined by &lt;taskdef&gt; (done)</li>
</ul>
<p>
So at present, properties declared in Ant2 tasks are available to all Ant1 tasks,
and vice-versa. However, while a <code>&lt;ant1.path&gt;</code> reference works fine
in other <code>&lt;ant1.XXX&gt;</code>
tasks, it's not visible to Ant2 tasks in the same build, and vice-versa.
</p>
<p>
The <code>&lt;taskdef&gt;</code> task works ok, registering the task with the TypeManager using the
"ant1." prefix. Only a couple of DataTypes (Path and Patternset) are working
as top-level types, but this should be just a matter of adding references to
the Ant1 version of TypeInstanceTask in the descriptor.
</p>
<p>
The TransformingProjectBuilder (which is now the default builder for files
of type ".xml", applies a transformation stylesheet to the file, prefixing select
tasks (all at present) with "ant.". If a version attribute is encountered, the
file is not transformed
</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="Using the compatibility layer"><strong>Using the compatibility layer</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#828DA6">
<font color="#ffffff" face="arial,helvetica,sanserif">
<a name="Using Ant1 tasks in a Myrmidon build file"><strong>Using Ant1 tasks in a Myrmidon build file</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
If you have a Myrmidon build file (eg with <code>version="2.0"</code>
on the project element, you can use Ant1 tasks and datatypes by using
the "ant1." suffix on the regular element name.
Virtually <i>all</i> tasks and datatypes from Ant1.4.1 are available
in this way.
</p>
<p>
When declaring a new task using the <code>&lt;ant1.taskdef&gt;</code>
task, <i>don't</i> prepend "ant1." to the taskname. This will be
done automatically by the taskdef task. However, you will need
to use the "ant1." prefix in all uses of that task.
</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="Using an existing Ant1 build file"><strong>Using an existing Ant1 build file</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>
Myrmidon will automatically handle Ant1 build files using the
Ant1 Compatibility layer. So, using an Ant1 build
file with Myrmidon should be as simple as:</p>
<pre>[myrmidon-command] -f ant1-build-file.xml</pre>
<p>
This works as follows: When Myrmidon encounters a ".xml" build file which does not have a
<code>version</code> attribute on the top-level <code>project</code>
element, it assumes that it is an Ant1 build file. So all tasks are
interpreted as though they are prefixed with the "ant." name prefix.
</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="Building the compatibility layer"><strong>Building the compatibility layer</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>Before building the Ant1 Compatibility layer, you need to build
Myrmidon, running the <code>dist-lite</code> target of the main build.
See <a href="user.html#Building Myrmidon">the build instructions</a>
for more details.</p>
<p>To build the compatibility layer, simply execute:</p>
<pre>ant -f ant1compat.xml</pre>
<p>from within the root directory of the Myrmidon source tree.</p>
</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 -->





+ 2
- 0
proposal/myrmidon/docs/buildfile.html View File

@@ -49,6 +49,8 @@
<li> <a href="./buildfile.html">Build file</a>
</li>
<li> <a href="./vfs.html">Virtual File System</a>
</li>
<li> <a href="./ant1compat.html">Ant1 Compatibility Layer</a>
</li>
</ul>
<p><strong>Extending Ant</strong></p>


+ 2
- 0
proposal/myrmidon/docs/classloader.html View File

@@ -49,6 +49,8 @@
<li> <a href="./buildfile.html">Build file</a>
</li>
<li> <a href="./vfs.html">Virtual File System</a>
</li>
<li> <a href="./ant1compat.html">Ant1 Compatibility Layer</a>
</li>
</ul>
<p><strong>Extending Ant</strong></p>


+ 2
- 0
proposal/myrmidon/docs/getinvolved.html View File

@@ -49,6 +49,8 @@
<li> <a href="./buildfile.html">Build file</a>
</li>
<li> <a href="./vfs.html">Virtual File System</a>
</li>
<li> <a href="./ant1compat.html">Ant1 Compatibility Layer</a>
</li>
</ul>
<p><strong>Extending Ant</strong></p>


+ 2
- 0
proposal/myrmidon/docs/index.html View File

@@ -49,6 +49,8 @@
<li> <a href="./buildfile.html">Build file</a>
</li>
<li> <a href="./vfs.html">Virtual File System</a>
</li>
<li> <a href="./ant1compat.html">Ant1 Compatibility Layer</a>
</li>
</ul>
<p><strong>Extending Ant</strong></p>


+ 2
- 0
proposal/myrmidon/docs/librarys.html View File

@@ -49,6 +49,8 @@
<li> <a href="./buildfile.html">Build file</a>
</li>
<li> <a href="./vfs.html">Virtual File System</a>
</li>
<li> <a href="./ant1compat.html">Ant1 Compatibility Layer</a>
</li>
</ul>
<p><strong>Extending Ant</strong></p>


+ 2
- 0
proposal/myrmidon/docs/task.html View File

@@ -49,6 +49,8 @@
<li> <a href="./buildfile.html">Build file</a>
</li>
<li> <a href="./vfs.html">Virtual File System</a>
</li>
<li> <a href="./ant1compat.html">Ant1 Compatibility Layer</a>
</li>
</ul>
<p><strong>Extending Ant</strong></p>


+ 173
- 64
proposal/myrmidon/docs/todo.html View File

@@ -49,6 +49,8 @@
<li> <a href="./buildfile.html">Build file</a>
</li>
<li> <a href="./vfs.html">Virtual File System</a>
</li>
<li> <a href="./ant1compat.html">Ant1 Compatibility Layer</a>
</li>
</ul>
<p><strong>Extending Ant</strong></p>
@@ -92,6 +94,40 @@
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="Paths"><strong>Paths</strong></a>
</font>
</td></tr>
<tr><td>
<blockquote>
<p>Consider allowing the user to configure the ant system by setting the
following path types.</p>
<ul>
<li>ant.type.path: path that is used to search for the type libraries</li>
<li>ant.ext.path: path that is used to search for "Optional Packages"
or extensions.</li>
</ul>
<p>
The default search path will probably include a per-user path element,
a workspace path element and a system path elemtn that are searched in
that order. Some possible defaults;
</p>
<ul>
<li>Unix Per-user: ${user.home}/.ant/lib, ${user.home}/.ant/ext</li>
<li>Windows Per-user: ${user.home}/ant/lib, ${user.home}/ant/ext</li>
<li>MacOSX Per-user: ${user.home}/Library/Ant/lib,
${user.home}/Library/Ant/ext</li>
<li>Unix System-wide: /opt/ant/lib, /opt/ant/ext</li>
<li>Unix System-wide: /usr/local/ant/lib, /usr/local/ant/ext</li>
<li>Windows System-wide: %SYS_DRIVE%/Program Files/ant/lib,
%SYS_DRIVE%/Program Files/ant/ext</li>
<li>MacOSX System-wide: /Library/Ant/lib, /Library/Ant/ant/ext</li>
</ul>
</blockquote>
</td></tr>
</table>
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tr><td bgcolor="#828DA6">
@@ -101,9 +137,30 @@
</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>
<p>The Ant1 Compatibility layer is still in early stages of development.
</p>
<ul>
<li>Get a version of <code>&lt;ant&gt;</code> and
<code>&lt;antcall&gt;</code> working.</li>
<li>
Provide hooks between Ant1 references and Myrmidon properties.
May use converters for adapting Ant2 objects (like Ant2
<code>&lt;path&gt;</code> or <code>&lt;fileset&gt;</code>)
as Ant1 types.
</li>
<li>Handle differences between Ant1 if/unless on targets,
and Myrmidon &lt;if&gt; task.</li>
<li>
Write tests for the various bits that rely on Myrmidon
functionality:
<ul>
<li>if/unless on targets: check that behaviour complies with Ant1</li>
<li>Make sure properties are shared between Ant1 and Myrmidon tasks.</li>
<li>Make sure that &lt;ant1.property&gt; behaves as per Ant1</li>
</ul>
</li>
<li>Get GUMP runs going using Myrmidon.</li>
</ul>
</blockquote>
</td></tr>
</table>
@@ -150,66 +207,96 @@
</td></tr>
<tr><td>
<blockquote>
<p>The file data-types, such as <code>&lt;fileset&gt;</code> and
<code>&lt;path&gt;</code>, are some of the most widely used parts of Ant 1.x.
Unfortunately, they aren't particularly extensible.</p>
<p>The file data-types, such as
<code>&lt;fileset&gt;</code> and

<code>&lt;path&gt;</code>, are some of the most widely used parts of Ant 1.x.
Unfortunately, they aren't particularly extensible.
</p>
<ul>
<li>Redesign the file data-types, replacing them with an interface-based
API, plus a set of implementations. The API should use the VFS file
<code>FileObject</code>, rather than <code>java.io.File</code>.
This process has started, in the <code>antlib.vfile</code> package.

<code>FileObject</code>, rather than
<code>java.io.File</code>.
This process has started, in the
<code>antlib.vfile</code> package.

</li>
<li>File Selectors:
<ul>
<li>Change <code>AbstractNameFileSelector</code> to use Ant 1 style patterns
matches, rather than Globs patterns.</li>
<li>Add 'defaultexcludes' to <code>DefaultFileSet</code>. Also add a
file selector implementation that matches everything except the default
excludes.</li>
<li>Add a name selector that loads patterns from a file.</li>
<li>Add more selector implementations: size and last-modified comparisons,
checksum comparison, byte-wise content comparison.</li>
</ul></li>

<ul>
<li>Change
<code>AbstractNameFileSelector</code> to use Ant 1 style patterns
matches, rather than Globs patterns.
</li>
<li>Add 'defaultexcludes' to
<code>DefaultFileSet</code>. Also add a
file selector implementation that matches everything except the default
excludes.
</li>
<li>Add a name selector that loads patterns from a file.</li>
<li>Add more selector implementations: size and last-modified comparisons,
checksum comparison, byte-wise content comparison.</li>
</ul>
</li>
<li>File conditions:
<ul>
<li>Add more condition implementations that perform checks on files.
One that searches a path for a file would be useful.</li>
</ul></li>

<ul>
<li>Add more condition implementations that perform checks on files.
One that searches a path for a file would be useful.</li>
</ul>
</li>
<li>File Name Mappers:
<ul>
<li>Change FileNameMapper.mapFileName() to take vfs.FileName objects.</li>
<li>Move the current mapper implementations across to antlib.</li>
</ul></li>

<ul>
<li>Change FileNameMapper.mapFileName() to take vfs.FileName objects.</li>
<li>Move the current mapper implementations across to antlib.</li>
</ul>
</li>
<li>File Sets:
<ul>
<li>Add a file set implementation that provides the union of several
nested file sets (that is, a file set that merges several file sets
together).</li>
<li>Add a file set implementation that filters files that are up-to-date
WRT some other file. Alternatively, this might be better done as a
file selector.</li>
</ul></li>

<ul>
<li>Add a file set implementation that provides the union of several
nested file sets (that is, a file set that merges several file sets
together).</li>
<li>Add a file set implementation that filters files that are up-to-date
WRT some other file. Alternatively, this might be better done as a
file selector.</li>
</ul>
</li>
<li>Paths:
<ul>
<li>Add path implementations that evaluate to the system classpath,
and the ant runtime classpath. Or, more generally, combine this with
<code>ClassLoaderManager</code> to evaluate to the classpath of any
'library' (e.g. system classpath, ant runtime, tools.jar,
an antlib, an installed extension, or the system classes of another JVM
for cross-compiling).</li>
</ul></li>

<ul>
<li>Add path implementations that evaluate to the system classpath,
and the ant runtime classpath. Or, more generally, combine this with

<code>ClassLoaderManager</code> to evaluate to the classpath of any
'library' (e.g. system classpath, ant runtime, tools.jar,
an antlib, an installed extension, or the system classes of another JVM
for cross-compiling).
</li>
</ul>
</li>
<li>Port across the Ant 1 file filter proposal, once it is complete.</li>
<li>Copy task:
<ul>
<li>Implement 'preservelastmodified', 'overwrite', and 'includeemptydirs'.</li>
<li>Support a file name mapper.</li>
<li>Support file filters.</li>
<li>Detect and handle destination file name collisions.</li>
</ul></li>
<li>Implement the <code>&lt;move&gt;</code>, <code>&lt;delete&gt;</code>,
<code>&lt;touch&gt;</code> and <code>&lt;mkdir&gt;</code> tasks on top

<ul>
<li>Implement 'preservelastmodified', 'overwrite', and 'includeemptydirs'.</li>
<li>Support a file name mapper.</li>
<li>Support file filters.</li>
<li>Detect and handle destination file name collisions.</li>
</ul>
</li>
<li>Implement the
<code>&lt;move&gt;</code>,
<code>&lt;delete&gt;</code>,

<code>&lt;touch&gt;</code> and
<code>&lt;mkdir&gt;</code> tasks on top
of the VFS and the new file data-types. Might be some scope for generalising
'touch' and 'mkdir' into a single task.</li>
'touch' and 'mkdir' into a single task.
</li>
</ul>
</blockquote>
</td></tr>
@@ -232,8 +319,12 @@
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>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>
@@ -308,7 +399,9 @@
<ul>
<li>Search through the code for 'TODO' items and fix them.</li>
<li>Allow service factories to be configured from the contents of the
<code>ant-services.xml</code> descriptor.</li>

<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
@@ -320,17 +413,33 @@
<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>Move the <code>&lt;http&gt;</code> and <code>&lt;socket&gt;</code>
conditions to an antlib. Need to resolve how these will be passed a logger.</li>
<li>Make the <code>&lt;uptodate&gt;</code> task a condition, and move to
an antlib.</li>
<li>Split up <code>&lt;is-set&gt;</code> condition into is-set and is-true conditions.</li>
<li>Allow the <code>&lt;if&gt;</code> task to take any condition implementation.</li>
<li>Add an else block to the <code>&lt;if&gt;</code> task.</li>
<li>Split the <code>&lt;available&gt;</code> condition into separate conditions
that test for the availability of a class, or a resource.</li>
<li>Move <code>crimson.jar</code> to <code>bin/lib</code> in the distribution,
and make to other jars via the extension mechanism.</li>
<li>Move the
<code>&lt;http&gt;</code> and
<code>&lt;socket&gt;</code>
conditions to an antlib. Need to resolve how these will be passed a logger.
</li>
<li>Make the
<code>&lt;uptodate&gt;</code> task a condition, and move to
an antlib.
</li>
<li>Split up
<code>&lt;is-set&gt;</code> condition into is-set and is-true conditions.
</li>
<li>Allow the
<code>&lt;if&gt;</code> task to take any condition implementation.
</li>
<li>Add an else block to the
<code>&lt;if&gt;</code> task.
</li>
<li>Split the
<code>&lt;available&gt;</code> condition into separate conditions
that test for the availability of a class, or a resource.
</li>
<li>Move
<code>crimson.jar</code> to
<code>bin/lib</code> in the distribution,
and make to other jars via the extension mechanism.
</li>
<li>Unit tests.</li>
</ul>
</blockquote>


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

@@ -49,6 +49,8 @@
<li> <a href="./buildfile.html">Build file</a>
</li>
<li> <a href="./vfs.html">Virtual File System</a>
</li>
<li> <a href="./ant1compat.html">Ant1 Compatibility Layer</a>
</li>
</ul>
<p><strong>Extending Ant</strong></p>


+ 2
- 0
proposal/myrmidon/docs/vfs.html View File

@@ -49,6 +49,8 @@
<li> <a href="./buildfile.html">Build file</a>
</li>
<li> <a href="./vfs.html">Virtual File System</a>
</li>
<li> <a href="./ant1compat.html">Ant1 Compatibility Layer</a>
</li>
</ul>
<p><strong>Extending Ant</strong></p>


+ 0
- 58
proposal/myrmidon/src/ant1compat/README.txt View File

@@ -1,58 +0,0 @@
Myrmidon Ant1 compatibility layer.

This directory contains the source for the Ant1 compatibility layer.

DESCRIPTION
-----------
The layer works by reusing most of the Ant1 code, with tasks and datatypes
being prefixed with "ant1." in build files. Almost all of the main Ant1 tree
is included in the compatibility layer antlib. To insulate from changes in
the Ant1 tree, Ant1 class files are extracted from a jar, rather than
being compiled from scratch.

Here's how it works: The first time an Ant1 task is encountered, an Ant1
project is created, and stored in the TaskContext. The Ant1 versions of Task
and Project have been extended, with Task implementing Configurable so that
it may can mimic the Ant1 configuration policy using the IntrospectionHelper.

The idea is to provide hooks between the Ant1 project and the Myrmidon
project, eg
logging: done
properties: done
references: not done
Task definitions: done.

So at present, while a <ant1:path> reference works fine in other <ant1:xxx>
tasks, it's not visible to the rest of the build, and vice-versa.

The <taskdef> task works ok, registering the task with the TypeManager using the
"ant1." prefix. Only a couple of DataTypes (Path and Patternset) are working
as top-level types, but this should be just a matter of adding references to
the Ant1 version of TypeInstanceTask in the descriptor.

The TransformingProjectBuilder (which is now the default builder for files
of type ".xml", applies a transformation stylesheet to the file, prefixing select
tasks (all at present) with "ant.". If a version attribute is encountered, the
file is not transformed

USAGE INSTRUCTIONS
------------------
Myrmidon will automatically attempt to upgrade any ".xml" build file that
doesn't have a version attribute on the root element. So, using an Ant1 build
file with Myrmidon should be as simple as:
[myrmidon-command] -f ant1-build-file.xml

BUILD INSTRUCTIONS
------------------
* It is required that Myrmidon is first build by running the default target
in the Myrmidon directory.
* Run "ant -f ant1compat.xml"

TODO
----
* Convert this to an Xdoc document
* Get a version of <ant> and <antcall> working
* Test heaps more tasks
* Provide hooks between Ant1 references and Myrmidon properties. Need to use
converters for adapting Ant2 objects (like Ant2 <path> or <fileset>) as Ant1 types.


+ 112
- 0
proposal/myrmidon/src/xdocs/ant1compat.xml View File

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

<properties>
<author email="darrell at apache dot org">Darrell DeBoer</author>
<title>Ant1 Compatibitlity Layer</title>
</properties>

<body>

<section name="Overview">
<p>
The Myrmidon-Ant1 Compatibility layer works by reusing most of the Ant1 code,
with tasks and datatypes
being prefixed with "ant1." in build files. Almost all of the main Ant1 tree
is included in the compatibility layer antlib. To insulate from changes in
the Ant1 tree, Ant1 class files are extracted from a jar, rather than
being compiled from scratch.
</p>
<p>
Here's how it works: The first time an Ant1 task is encountered, an Ant1
project is created, and stored in the TaskContext under the name "ant1.project".
The Ant1 versions of Task and Project have been extended, overriding core behaviour,
with Myrmidon-specific behaviour.
</p>
<p>
The updated version of Task implements Configurable, receiving it's
complete Task Model, and actually setting/adding/creating attributes
with the help of the IntrospectionHelper. This process is designed to
mimic the Ant1 configuration policy, although not <i>all</i> of the
subtle variations of configuration present in Ant1 are handled.
</p>
<p>
The updated version of Project will provide hooks into the Myrmidon TaskContext,
such as:</p>
<ul>
<li>logging (done)</li>
<li>properties (done)</li>
<li>references (not yet done)</li>
<li>Task defined by &lt;taskdef&gt; (done)</li>
</ul>

<p>
So at present, properties declared in Ant2 tasks are available to all Ant1 tasks,
and vice-versa. However, while a <code>&lt;ant1.path&gt;</code> reference works fine
in other <code>&lt;ant1.XXX&gt;</code>
tasks, it's not visible to Ant2 tasks in the same build, and vice-versa.
</p>

<p>
The <code>&lt;taskdef&gt;</code> task works ok, registering the task with the TypeManager using the
"ant1." prefix. Only a couple of DataTypes (Path and Patternset) are working
as top-level types, but this should be just a matter of adding references to
the Ant1 version of TypeInstanceTask in the descriptor.
</p>

<p>
The TransformingProjectBuilder (which is now the default builder for files
of type ".xml", applies a transformation stylesheet to the file, prefixing select
tasks (all at present) with "ant.". If a version attribute is encountered, the
file is not transformed
</p>
</section>

<section name="Using the compatibility layer">
<subsection name="Using Ant1 tasks in a Myrmidon build file">
<p>
If you have a Myrmidon build file (eg with <code>version="2.0"</code>
on the project element, you can use Ant1 tasks and datatypes by using
the "ant1." suffix on the regular element name.
Virtually <i>all</i> tasks and datatypes from Ant1.4.1 are available
in this way.
</p>
<p>
When declaring a new task using the <code>&lt;ant1.taskdef&gt;</code>
task, <i>don't</i> prepend "ant1." to the taskname. This will be
done automatically by the taskdef task. However, you will need
to use the "ant1." prefix in all uses of that task.
</p>
</subsection>

<subsection name="Using an existing Ant1 build file">
<p>
Myrmidon will automatically handle Ant1 build files using the
Ant1 Compatibility layer. So, using an Ant1 build
file with Myrmidon should be as simple as:</p>
<pre>[myrmidon-command] -f ant1-build-file.xml</pre>
<p>
This works as follows: When Myrmidon encounters a ".xml" build file which does not have a
<code>version</code> attribute on the top-level <code>project</code>
element, it assumes that it is an Ant1 build file. So all tasks are
interpreted as though they are prefixed with the "ant." name prefix.
</p>

Myrmidon will automatically attempt to upgrade any ".xml" build file that
</subsection>
</section>

<section name="Building the compatibility layer">
<p>Before building the Ant1 Compatibility layer, you need to build
Myrmidon, running the <code>dist-lite</code> target of the main build.
See <a href="user.html#Building Myrmidon">the build instructions</a>
for more details.</p>

<p>To build the compatibility layer, simply execute:</p>
<pre>ant -f ant1compat.xml</pre>
<p>from within the root directory of the Myrmidon source tree.</p>

</section>

</body>
</document>


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

@@ -13,6 +13,7 @@
<menu name="User Guide">
<item name="Build file" href="/buildfile.html"/>
<item name="Virtual File System" href="/vfs.html"/>
<item name="Ant1 Compatibility Layer" href="/ant1compat.html"/>
</menu>

<menu name="Extending Ant">


+ 24
- 5
proposal/myrmidon/src/xdocs/todo.xml View File

@@ -53,11 +53,30 @@
</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>

<p>The Ant1 Compatibility layer is still in early stages of development.
</p>
<ul>
<li>Get a version of <code>&lt;ant&gt;</code> and
<code>&lt;antcall&gt;</code> working.</li>
<li>
Provide hooks between Ant1 references and Myrmidon properties.
May use converters for adapting Ant2 objects (like Ant2
<code>&lt;path&gt;</code> or <code>&lt;fileset&gt;</code>)
as Ant1 types.
</li>
<li>Handle differences between Ant1 if/unless on targets,
and Myrmidon &lt;if&gt; task.</li>
<li>
Write tests for the various bits that rely on Myrmidon
functionality:
<ul>
<li>if/unless on targets: check that behaviour complies with Ant1</li>
<li>Make sure properties are shared between Ant1 and Myrmidon tasks.</li>
<li>Make sure that &lt;ant1.property&gt; behaves as per Ant1</li>
</ul>
</li>
<li>Get GUMP runs going using Myrmidon.</li>
</ul>
</subsection>

<subsection name="Virtual File System">


Write Preview
Loading…
Cancel
Save