From 214bb47106faf56b5b40a0b9e5cf61ed4a7b0c53 Mon Sep 17 00:00:00 2001 From: Darrell DeBoer Date: Fri, 22 Mar 2002 04:26:34 +0000 Subject: [PATCH] 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 --- proposal/myrmidon/docs/ant1compat.html | 223 ++++++++++++++++ proposal/myrmidon/docs/buildfile.html | 2 + proposal/myrmidon/docs/classloader.html | 2 + proposal/myrmidon/docs/getinvolved.html | 2 + proposal/myrmidon/docs/index.html | 2 + proposal/myrmidon/docs/librarys.html | 2 + proposal/myrmidon/docs/task.html | 2 + proposal/myrmidon/docs/todo.html | 237 +++++++++++++----- proposal/myrmidon/docs/user.html | 2 + proposal/myrmidon/docs/vfs.html | 2 + proposal/myrmidon/src/ant1compat/README.txt | 58 ----- proposal/myrmidon/src/xdocs/ant1compat.xml | 112 +++++++++ .../src/xdocs/stylesheets/project.xml | 1 + proposal/myrmidon/src/xdocs/todo.xml | 29 ++- 14 files changed, 549 insertions(+), 127 deletions(-) create mode 100644 proposal/myrmidon/docs/ant1compat.html delete mode 100644 proposal/myrmidon/src/ant1compat/README.txt create mode 100644 proposal/myrmidon/src/xdocs/ant1compat.xml diff --git a/proposal/myrmidon/docs/ant1compat.html b/proposal/myrmidon/docs/ant1compat.html new file mode 100644 index 000000000..4bd18ea99 --- /dev/null +++ b/proposal/myrmidon/docs/ant1compat.html @@ -0,0 +1,223 @@ + + + + + + + + + + + + + + Apache Myrmidon - Ant1 Compatibitlity Layer + + + + + + + + + + +
+ +
Apache Myrmidon
+ + + + + + + + + + + + +
+
+
+

Myrmidon

+ +

User Guide

+ +

Extending Ant

+ +

Container Design

+
    +
+ 		+ + + +
+ + Overview + +
+
+

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

+

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

+

+ 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 all of the + subtle variations of configuration present in Ant1 are handled. +

+

+ The updated version of Project will provide hooks into the Myrmidon TaskContext, + such as:

+
    +
  • logging (done)
    • +
  • properties (done)
    • +
  • references (not yet done)
    • +
  • Task defined by <taskdef> (done)
    • +
+

+ So at present, properties declared in Ant2 tasks are available to all Ant1 tasks, + and vice-versa. However, while a <ant1.path> reference works fine + in other <ant1.XXX> + tasks, it's not visible to Ant2 tasks in the same 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 +

+
+
+ + + +
+ + Using the compatibility layer + +
+
+ + + +
+ + Using Ant1 tasks in a Myrmidon build file + +
+
+

+ If you have a Myrmidon build file (eg with version="2.0" + on the project element, you can use Ant1 tasks and datatypes by using + the "ant1." suffix on the regular element name. + Virtually all tasks and datatypes from Ant1.4.1 are available + in this way. +

+

+ When declaring a new task using the <ant1.taskdef> + task, don't 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. +

+
+
+ + + +
+ + Using an existing Ant1 build file + +
+
+

+ 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:

+ 
[myrmidon-command] -f ant1-build-file.xml
+

+ This works as follows: When Myrmidon encounters a ".xml" build file which does not have a + version attribute on the top-level project + 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. +

+
+
+
+
+ + + +
+ + Building the compatibility layer + +
+
+

Before building the Ant1 Compatibility layer, you need to build + Myrmidon, running the dist-lite target of the main build. + See the build instructions + for more details.

+

To build the compatibility layer, simply execute:

+ 
ant -f ant1compat.xml
+

from within the root directory of the Myrmidon source tree.

+
+
+
+
+
+
+ Copyright © 2000-2002, Apache Software Foundation +
+
+ + + + + + + diff --git a/proposal/myrmidon/docs/buildfile.html b/proposal/myrmidon/docs/buildfile.html index e0e06d47e..892185827 100644 --- a/proposal/myrmidon/docs/buildfile.html +++ b/proposal/myrmidon/docs/buildfile.html @@ -49,6 +49,8 @@
  • Build file
  • Virtual File System +
    • +
  • Ant1 Compatibility Layer

    • Extending Ant

    diff --git a/proposal/myrmidon/docs/classloader.html b/proposal/myrmidon/docs/classloader.html index ca2250332..183b6d103 100644 --- a/proposal/myrmidon/docs/classloader.html +++ b/proposal/myrmidon/docs/classloader.html @@ -49,6 +49,8 @@
  • Build file
  • Virtual File System +
    • +
  • Ant1 Compatibility Layer

    • Extending Ant

    diff --git a/proposal/myrmidon/docs/getinvolved.html b/proposal/myrmidon/docs/getinvolved.html index 5a39cd304..78bfae909 100644 --- a/proposal/myrmidon/docs/getinvolved.html +++ b/proposal/myrmidon/docs/getinvolved.html @@ -49,6 +49,8 @@
  • Build file
  • Virtual File System +
    • +
  • Ant1 Compatibility Layer

    • Extending Ant

    diff --git a/proposal/myrmidon/docs/index.html b/proposal/myrmidon/docs/index.html index 8e0dfed50..0baf94640 100644 --- a/proposal/myrmidon/docs/index.html +++ b/proposal/myrmidon/docs/index.html @@ -49,6 +49,8 @@
  • Build file
  • Virtual File System +
    • +
  • Ant1 Compatibility Layer

    • Extending Ant

    diff --git a/proposal/myrmidon/docs/librarys.html b/proposal/myrmidon/docs/librarys.html index 729f58b8c..83db6bbb0 100644 --- a/proposal/myrmidon/docs/librarys.html +++ b/proposal/myrmidon/docs/librarys.html @@ -49,6 +49,8 @@
  • Build file
  • Virtual File System +
    • +
  • Ant1 Compatibility Layer

    • Extending Ant

    diff --git a/proposal/myrmidon/docs/task.html b/proposal/myrmidon/docs/task.html index 33b5ab27f..c551dc7cb 100644 --- a/proposal/myrmidon/docs/task.html +++ b/proposal/myrmidon/docs/task.html @@ -49,6 +49,8 @@
  • Build file
  • Virtual File System +
    • +
  • Ant1 Compatibility Layer

    • Extending Ant

    diff --git a/proposal/myrmidon/docs/todo.html b/proposal/myrmidon/docs/todo.html index 68f8239dd..4b8ae218e 100644 --- a/proposal/myrmidon/docs/todo.html +++ b/proposal/myrmidon/docs/todo.html @@ -49,6 +49,8 @@
  • Build file
  • Virtual File System +
    • +
  • Ant1 Compatibility Layer

    • Extending Ant

    @@ -92,6 +94,40 @@ able to be built from scratch, without using Ant 1.x at all).

    + + + +
    + + Paths + +
    +
    +

    Consider allowing the user to configure the ant system by setting the + following path types.

    +
      +
    • ant.type.path: path that is used to search for the type libraries
      • +
    • ant.ext.path: path that is used to search for "Optional Packages" + or extensions.
      • +
    +

    + 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; +

    +
      +
    • Unix Per-user: ${user.home}/.ant/lib, ${user.home}/.ant/ext
      • +
    • Windows Per-user: ${user.home}/ant/lib, ${user.home}/ant/ext
      • +
    • MacOSX Per-user: ${user.home}/Library/Ant/lib, + ${user.home}/Library/Ant/ext
      • +
    • Unix System-wide: /opt/ant/lib, /opt/ant/ext
      • +
    • Unix System-wide: /usr/local/ant/lib, /usr/local/ant/ext
      • +
    • Windows System-wide: %SYS_DRIVE%/Program Files/ant/lib, + %SYS_DRIVE%/Program Files/ant/ext
      • +
    • MacOSX System-wide: /Library/Ant/lib, /Library/Ant/ant/ext
      • +
    +
    +
    @@ -101,9 +137,30 @@
    -

    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.

    +

    The Ant1 Compatibility layer is still in early stages of development. +

    +
      +
    • Get a version of <ant> and + <antcall> working.
      • +
    • + Provide hooks between Ant1 references and Myrmidon properties. + May use converters for adapting Ant2 objects (like Ant2 + <path> or <fileset>) + as Ant1 types. +
      • +
    • Handle differences between Ant1 if/unless on targets, + and Myrmidon <if> task.
      • +
    • + Write tests for the various bits that rely on Myrmidon + functionality: +
        +
      • if/unless on targets: check that behaviour complies with Ant1
        • +
      • Make sure properties are shared between Ant1 and Myrmidon tasks.
        • +
      • Make sure that <ant1.property> behaves as per Ant1
        • +
      +
      • +
    • Get GUMP runs going using Myrmidon.
      • +
    @@ -150,66 +207,96 @@
    -

    The file data-types, such as <fileset> and - <path>, are some of the most widely used parts of Ant 1.x. - Unfortunately, they aren't particularly extensible.

    +

    The file data-types, such as + <fileset> and + + <path>, are some of the most widely used parts of Ant 1.x. + Unfortunately, they aren't particularly extensible. +

    @@ -232,8 +319,12 @@ configuration files.
  • Allow the following via config files: +

    Extending Ant

    diff --git a/proposal/myrmidon/docs/vfs.html b/proposal/myrmidon/docs/vfs.html index 921acf275..c100d5f38 100644 --- a/proposal/myrmidon/docs/vfs.html +++ b/proposal/myrmidon/docs/vfs.html @@ -49,6 +49,8 @@
  • Build file
  • Virtual File System +
    • +
  • Ant1 Compatibility Layer

    • Extending Ant

    diff --git a/proposal/myrmidon/src/ant1compat/README.txt b/proposal/myrmidon/src/ant1compat/README.txt deleted file mode 100644 index c3926ba20..000000000 --- a/proposal/myrmidon/src/ant1compat/README.txt +++ /dev/null @@ -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 reference works fine in other -tasks, it's not visible to the rest of the build, and vice-versa. - -The 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 and working -* Test heaps more tasks -* Provide hooks between Ant1 references and Myrmidon properties. Need to use - converters for adapting Ant2 objects (like Ant2 or ) as Ant1 types. - diff --git a/proposal/myrmidon/src/xdocs/ant1compat.xml b/proposal/myrmidon/src/xdocs/ant1compat.xml new file mode 100644 index 000000000..7a86b59c8 --- /dev/null +++ b/proposal/myrmidon/src/xdocs/ant1compat.xml @@ -0,0 +1,112 @@ + + + + Darrell DeBoer + Ant1 Compatibitlity Layer + + + + +
    +

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

    +

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

    +

    + 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 all of the + subtle variations of configuration present in Ant1 are handled. +

    +

    + The updated version of Project will provide hooks into the Myrmidon TaskContext, + such as:

    +
      +
    • logging (done)
      • +
    • properties (done)
      • +
    • references (not yet done)
      • +
    • Task defined by <taskdef> (done)
      • +
    + +

    + So at present, properties declared in Ant2 tasks are available to all Ant1 tasks, + and vice-versa. However, while a <ant1.path> reference works fine + in other <ant1.XXX> + tasks, it's not visible to Ant2 tasks in the same 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 +

    +
    + +
    + +

    + If you have a Myrmidon build file (eg with version="2.0" + on the project element, you can use Ant1 tasks and datatypes by using + the "ant1." suffix on the regular element name. + Virtually all tasks and datatypes from Ant1.4.1 are available + in this way. +

    +

    + When declaring a new task using the <ant1.taskdef> + task, don't 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. +

    +     + + +

    + 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:

    + 
    [myrmidon-command] -f ant1-build-file.xml
    +

    + This works as follows: When Myrmidon encounters a ".xml" build file which does not have a + version attribute on the top-level project + 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. +

    + + Myrmidon will automatically attempt to upgrade any ".xml" build file that +     +
    + +
    +

    Before building the Ant1 Compatibility layer, you need to build + Myrmidon, running the dist-lite target of the main build. + See the build instructions + for more details.

    + +

    To build the compatibility layer, simply execute:

    + 
    ant -f ant1compat.xml
    +

    from within the root directory of the Myrmidon source tree.

    + +
    + + +     + diff --git a/proposal/myrmidon/src/xdocs/stylesheets/project.xml b/proposal/myrmidon/src/xdocs/stylesheets/project.xml index a1fa7b2fc..f31ccf37b 100644 --- a/proposal/myrmidon/src/xdocs/stylesheets/project.xml +++ b/proposal/myrmidon/src/xdocs/stylesheets/project.xml @@ -13,6 +13,7 @@ + diff --git a/proposal/myrmidon/src/xdocs/todo.xml b/proposal/myrmidon/src/xdocs/todo.xml index c0035e039..6321131be 100644 --- a/proposal/myrmidon/src/xdocs/todo.xml +++ b/proposal/myrmidon/src/xdocs/todo.xml @@ -53,11 +53,30 @@ - -

    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.

    - +

    The Ant1 Compatibility layer is still in early stages of development. +

    +
      +
    • Get a version of <ant> and + <antcall> working.
      • +
    • + Provide hooks between Ant1 references and Myrmidon properties. + May use converters for adapting Ant2 objects (like Ant2 + <path> or <fileset>) + as Ant1 types. +
      • +
    • Handle differences between Ant1 if/unless on targets, + and Myrmidon <if> task.
      • +
    • + Write tests for the various bits that rely on Myrmidon + functionality: +
        +
      • if/unless on targets: check that behaviour complies with Ant1
        • +
      • Make sure properties are shared between Ant1 and Myrmidon tasks.
        • +
      • Make sure that <ant1.property> behaves as per Ant1
        • +
      +
      • +
    • Get GUMP runs going using Myrmidon.
      • +