adammurdoch 2002/06/06 05:54:29 Modified: site build.xml site/docs ant1compat.html buildfile.html building.html classloader.html configuring.html differences.html getinvolved.html index.html librarys.html project-descriptor.html running.html subprojects.html task.html todo.html vfs.html Added: site/docs/css ns4_only.css print.css site.css tigris.css site/docs/images nw_min.gif strich.gif sw_min.gif Log: Regen docs. Revision Changes Path 1.2 +4 -0 jakarta-ant-myrmidon/site/build.xml Index: build.xml =================================================================== RCS file: /home/cvs/jakarta-ant-myrmidon/site/build.xml,v retrieving revision 1.1 retrieving revision 1.2 diff -u -r1.1 -r1.2 --- build.xml 10 Apr 2002 23:43:46 -0000 1.1 +++ build.xml 6 Jun 2002 12:54:28 -0000 1.2 @@ -34,6 +34,10 @@ excludes="stylesheets/**" velocitypropertiesfile="${xdocs.dir}/velocity.properties" /> + + + + 1.6 +117 -149 jakarta-ant-myrmidon/site/docs/ant1compat.html Index: ant1compat.html =================================================================== RCS file: /home/cvs/jakarta-ant-myrmidon/site/docs/ant1compat.html,v retrieving revision 1.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- ant1compat.html 19 May 2002 13:37:50 -0000 1.5 +++ ant1compat.html 6 Jun 2002 12:54:28 -0000 1.6 @@ -6,90 +6,92 @@ + - + - + Apache Myrmidon - Ant 1 Compatibitlity Layer - - - - - -
+ + + + + + + - - +

To build the compatibility layer, simply execute:

+
ant -f ant1compat.xml
+

from within the root directory of the Myrmidon source tree.

+ + - - - -
-

Myrmidon

- -

User Guide

- -

Extending Myrmidon

- -

Developers Guide

- -
- - - + -
- - Overview - -
-
-

+

+ +
+
+

Overview

+

The Myrmidon-Ant1 Compatibility layer works by reusing most of the Ant 1 code, with tasks and datatypes being prefixed with "ant1." in build files. Almost all of the main Ant 1 tree @@ -97,137 +99,103 @@ the Ant 1 tree, Ant 1 class files are extracted from a jar, rather than being compiled from scratch.

-

+

Here's how it works: The first time an Ant 1 task is encountered, an Ant 1 project is created, and stored in the TaskContext under the name "ant1.project". The Ant 1 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 Ant 1 configuration policy, although not all of the subtle variations of configuration present in Ant 1 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 Ant 2 tasks are available to all Ant 1 tasks, and vice-versa. However, while a <ant1.path> reference works fine in other <ant1.XXX> tasks, it's not visible to Ant 2 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 Ant 1 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 Ant 1 tasks in a Myrmidon build file - -
-
-

+ +

+

Using the compatibility layer

+
+

Using Ant 1 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 Ant 1 tasks and datatypes by using the "ant1." suffix on the regular element name. Virtually all tasks and datatypes from Ant 1.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 Ant 1 build file - -
-
-

+ +

+

Using an existing Ant 1 build file

+

Myrmidon will automatically handle Ant 1 build files using the Ant 1 Compatibility layer. So, using an Ant 1 build file with Myrmidon should be as simple as:

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

+

[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 Ant 1 build file. So all tasks are interpreted as though they are prefixed with the "ant." name prefix.

-
-
-
-
- - - -
- - Building the compatibility layer - -
-
-

Before building the Ant 1 Compatibility layer, you need to build + + +

+

Building the compatibility layer

+

Before building the Ant 1 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 -
-
+ + + + 1.7 +381 -496 jakarta-ant-myrmidon/site/docs/buildfile.html Index: buildfile.html =================================================================== RCS file: /home/cvs/jakarta-ant-myrmidon/site/docs/buildfile.html,v retrieving revision 1.6 retrieving revision 1.7 diff -u -r1.6 -r1.7 --- buildfile.html 2 Jun 2002 14:05:55 -0000 1.6 +++ buildfile.html 6 Jun 2002 12:54:28 -0000 1.7 @@ -6,325 +6,301 @@ + - + - + Apache Myrmidon - Using Myrmidon - - - - - -
+ + + + + + + - -
-

Myrmidon

- -

User Guide

- -

Extending Myrmidon

- -

Developers Guide

- -
- - - + -
- - Overview - -
-
+
+ +
+
+

Overview

+

+ You define a build process using a project file. A + project file is an XML file, which describes what needs to be done to + perform the build. A project is usually made up of several stages, + or targets. For example, a project might be made up + of a target that compiles the Java source files, another target that runs + unit tests, and a third target that assembles a distribution. +

+

+ A target may depend on other targets. For example, a target that + builds a distribution, cannot do its work until the source files have been + compiled. Myrmidon makes sure that targets are executed in the correct order, + so that a target is executed before the targets that depend on it. Target + are only executed once. +

-You define a build process using a project. A project -describes what needs to be done to perform the build. You define a project -by breaking it up into several smaller steps, or targets. Targets -represent the main stages of your build. For example, a project might have -a target that compiles the Java source files, another target that runs unit -tests, and a third target that assembles a distribution. -

-

-A target may depend on other targets. For example, -a target that builds a distribution, cannot do its work until the source files -have been compiled. Myrmidon makes sure that targets are executed in the -correct order, so that a target is executed before the targets that depend on it. -

-

-You define a target using basic units of work called tasks. -Tasks can range from the most simple operations, such as copying a file, or -setting a property, up to complex operations like compiling Java source, or -running a test suite. -

- -
- - -
- - The Project File - -
-
+ You define a target using basic units of work called tasks. + Tasks can range from simple operations, such as copying a file, or setting a + property, up to complex operations like compiling Java source, or running a + test suite. +

-A project file is an XML file that defines a single project. The root element -of a project file must be a <project> element. -It can take the following attributes: -

- - -
- + Let's look at a simple example. The project below contains two targets, + called compile and build-jar. The compile + target executes the javac task, which, as you probably + guessed, compiles up a bunch of Java source files. + The build-jar target depends on the compile target, + which means that it will only ever get executed after the + compile target has been executed. The build-jar + target executes the jar task, which assembles the compiled + class files into a Jar file. +

+
+
  +<project version="2.0" default="build-jar">
  +
  +    <!-- Compile the Java source -->
  +    <target name="compile">
  +        <javac src-dir="src/java" dest-dir="build/classes"/>
  +    </target>
  +
  +    <!-- Assemble a Jar file -->
  +    <target name="build-jar" depends="compile">
  +        <jar dest-file="build/myproject.jar">
  +            <fileset dir="build/classes"/>
  +        </jar>
  +    </target>
  +</project>
  +
+
+ +
+

The Project File

+

+ A project file is an XML file that defines a single project. The root element + of a project file must be a <project> element. + It can take the following attributes: +

+ + + - - + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - + +
Attribute - - - - + + Description - - - - + + Default Value - - -
- + +
name - - - + The project name. - - - + The name of the project file, with the extension removed. - -
- +
basedir - - - + The base directory for the project. The base directory is used - to resolve all relative file names used in the project file. - - - - + to resolve all relative file names used in the project file. + + The directory containing the project file. - -
- +
default - - - + The name of the default target. - - - + main - -
- +
version - - - + The project file format version that the project is written for. - - - + None, must be 2.0 - -
-

-A <project> element can contain the following elements, -in the order given below: -

- - - - - - - - - + + +
- - Project References - -
-
-

Project references allow the project to import, or reference, other projects. +

+ A <project> element can contain the following elements, + in the order given below: +

+ +

Below is a simple example, which contains two targets:

+
+
  +<project version="2.0" name="some-project" basedir="..">
  +
  +    <target name="compile">
  +        ...
  +    </target>
  +
  +    <target name="tests">
  +        ...
  +    </target>
  +</project>
  +
+
+
+

Project References

+

Project references allow the project to import, or reference, other projects. A <projectref> element takes the following attributes:

- - - -
- + + + - - + + - + - + - - - + + + - + - + - + +
Attribute - - - - + + Description - - - - + + Default Value - - -
- + +
name - - - + The name to use to identify the referenced project. - - - + Required - -
- +
location - - - + The path to the project file to reference. - - - + Required - -
-

+

The targets of a referenced project can be used in the depends list of a target in the referencing project, using the syntax project-name->target-name. Here is a simple example:

-
- - - - - - - - - - - - - - - - -
  -
  +                          
+
   <project version="2.0">
       <!-- Reference another project -->
       <projectref name="subproject" location="subproject/build.xml"/>
  @@ -334,245 +310,154 @@
           .. do some stuff ..
       </target>
   </project>
  -
+
- -
- - - -
- - Initialization Tasks - -
-
-

Initialization tasks are run before any of the project's targets are run, and -are used to initialize the project. Any task can be used as an initialization -task, including <property> and data-type instances. An example:

-
- - - - - - - - - - - - - - - - -
  -
  +            
  +                          
+

Initialization Tasks

+

+ Initialization tasks are executed before any of the + project's targets are executed, and are used to initialize the project. + Any task can be used as an initialization task, including + <property> and data-type instances. The initialization + tasks are executed in the order they appear in the project file. +

+

Below is an example:

+
+
   <project version="2.0">
   
  +  <!-- Initialization tasks -->
     <property name="some-property" value="some value"/>
  -  <path id="classpath">
  -    <fileset dir="lib"/>
  -  </path>
  +  <path id="classpath" ... />
     <log>Set classpath to ${classpath}</log>
   
  +  <!-- Targets -->
     <target name="main">
  -    .. do some stuff ..
  +    ...
     </target>
   
   </project>
  -
+
-
-
- - - -
- - Targets - -
-
-

Targets have a similar format to targets in Ant 1.x, though some of the -behaviour is different. A <target> element takes the -following attributes:

- - - -
- + + +
+

Targets

+

+ A target is a list of tasks, contained in a <target> + element. When the target is executed, the tasks are executed in the order + they appear in the project file. A target may also have a list of dependencies. + These are targets that must be executed before the target is executed. +

+

A <target> element takes the following attributes:

+ + + - - - - - - - + + + + + + + - + - + - + + + + + + +
Attribute - - - - + + Description - - - - + + Default Value - - -
- - name - - - - The name of the target. - - - - Required - -
- + +
+ description + + A description of the target. + + None +
depends - - - + A comma-separated list of targets that this target depends on. - This list can contain targets from referenced projects. - - - + This list can contain targets from referenced projects. + None - -
+ name + + The name of the target. + + Required +
- -
-
-
- - - -
- - Tasks - -
-
+

An example project, with two targets:

+
+
  +<project version="2.0" default="jars">
  +
  +    <target name="compile" description="Compiles the Java source">
  +        <javac ... />
  +    </target>
  +
  +    <target name="jars" depends="compile" description="Builds the Jar file">
  +        <jar ... />
  +    </target>
  +
  +</project>
  +
+
+ +
+

Tasks

+

+ A task is represented as an XML element, where the name of the task is used + as the element name. The attributes and nested elements that a task allows + depend on the task. Below are two example tasks: +

+
+
  +<property name="a-prop" value="some value"/>
  +<log>This is a log message.</log>
  +
+

- Listed below are some of the current set of tasks. You can find example - usages of these tasks in the sample project file src/make/sample.ant. + Some tasks may contain other tasks. You can find out about how to write + your own tasks here.

-

<condition>

-

Sets a property if a particular condition is true. See - Conditions for a list of available conditions.

-

<fail>

-

Causes the build to fail.

-

<if>

-

Conditionally executes a set of tasks.

-

<load-properties>

-

Loads a set of properties from a file.

-

<log>

-

Writes a log message.

-

<property>

-

Sets a property.

-

<try-catch>

-

Runs a set of tasks, with a provided error and clean-up handler.

-

<converter-def>

-

Register a type converter. These are used when configuring a task - or data-type from attributes.

-

<type-def>

-

Register a task or data-type.

-

<import>

-

Register the contents of an antlib.

-
-
- - - -
- - Conditions - -
-
-

The following conditions are available

-

<and>

-

Evaluates a set of nested conditions, and AND them together. Evaluation is - lazy. An empty <and> condition evaluates to true.

-

<available>

-

Tests if a particular class or resource is available.

-

<file-test>

-

Tests a file against a set of file selectors.

-

<is-set>

-

Tests whether a proeprty is set, and not set to 'false'.

-

<or>

-

Evaluates a set of nested conditions, and OR them together. Evaluation is - lazy. An empty <or> evaluates to true.

-

<os>

-

Tests which operating system the build is running on.

-

<not>

-

Negates a nested condition.

-
-
- - - -
- - File Name Mappers - -
-
-

The following file name mappers are available:

-

<chain>

-

Applies a set of nested file name mappers to file names.

-

<flatten>

-

Maps all file names to a single directory.

-

<prefix>

-

Adds a prefix to the front of each file name.

-

<map-extension>

-

Changes the extension of file names.

-
-
-
-
-
-
- Copyright © 2000-2002, Apache Software Foundation -
-
+ + + + 1.3 +125 -143 jakarta-ant-myrmidon/site/docs/building.html Index: building.html =================================================================== RCS file: /home/cvs/jakarta-ant-myrmidon/site/docs/building.html,v retrieving revision 1.2 retrieving revision 1.3 diff -u -r1.2 -r1.3 --- building.html 19 May 2002 13:37:50 -0000 1.2 +++ building.html 6 Jun 2002 12:54:28 -0000 1.3 @@ -6,95 +6,97 @@ + - + - + Apache Myrmidon - Building Myrmidon - - - - - -
+ + + + + + + - -
-

Myrmidon

- -

User Guide

- -

Extending Myrmidon

- -

Developers Guide

- -
- - - + + + - - - -
- - Building Myrmidon - -
-
-

+

+ +
+
+

Building Myrmidon

+

First, you will need to fetch the Myrmidon source from CVS. The source can be found in the jakarta-ant-myrmidon CVS module. Details can be found here.

-

+

To build Myrmidon, use the build.xml file in the root of the source tree. You will need to use Ant 1.5 or later, and you will need to include junit and xalan in your CLASSPATH. The default target builds a minimal Myrmidon @@ -103,87 +105,67 @@ build a full Myrmidon distribution, including all documentation, into the myrmidon/distributions directory.

-

There are a number features that are not built unless the appropriate optional Jar +

There are a number features that are not built unless the appropriate optional Jar files are found in the lib directory:

- - - -
- + + + - - + + - + - + - - - + + + - + - + - + +
Feature - - - - + + Jar File - - - - + + Download From - - -
- + +
SMB VFS support (Samba, Windows shares) - - - + jcifs.jar - - - + jcifs.samba.org.

Note: there are problems using the 0.6.1 release. Try 0.6.0 instead.

- -
- +
FTP VFS support - - - + netcomponents.jar - - - + www.savarese.org - -
- -
-
-
-
-
- Copyright © 2000-2002, Apache Software Foundation -
-
+ + + + 1.6 +95 -111 jakarta-ant-myrmidon/site/docs/classloader.html Index: classloader.html =================================================================== RCS file: /home/cvs/jakarta-ant-myrmidon/site/docs/classloader.html,v retrieving revision 1.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- classloader.html 19 May 2002 13:37:50 -0000 1.5 +++ classloader.html 6 Jun 2002 12:54:28 -0000 1.6 @@ -6,115 +6,109 @@ + - + - + Apache Myrmidon - On ClassLoaders in Ant 2 - - - - - -
+ + + + + + + - - + + - - - -
-

Myrmidon

- -

User Guide

- -

Extending Myrmidon

- -

Developers Guide

- -
- - - + -
- - ClassLoader Management - -
-
-

In many ways Ant 2 needs to follow rules similar to a number of +

+ +
+
+

ClassLoader Management

+

In many ways Ant 2 needs to follow rules similar to a number of different application servers with respect to ClassLoader management. Ant 2 will create a number of different ClassLoaders that have access to different sets of resources (and thus Classes). The main reason for this arrangment is to partition different sections of the application such as the Container, the Task API, task/type libraries and support libraries.

-

The recomended structure for ClassLoader relationships is a hierarchy. +

The recomended structure for ClassLoader relationships is a hierarchy. When a ClassLoader is asked for a resource (or a class) it first delegates to it's parent to ask for the resource. If the resource is not present in its parent ClassLoader then the ClassLoader attempts to locate the resource in it's own store. In practice this means that all the classes (and static variables defined by said classes) in a parent ClassLoader are shared with the child ClassLoaders.

-

Using kooky ascii art, the specific ClassLoader structure for Ant 2 is as +

Using kooky ascii art, the specific ClassLoader structure for Ant 2 is as follows:

-
- - - - - - - - - - - - - - - - -
  +                          
+
                     Bootstrap
                         |
                      System
  @@ -124,17 +118,9 @@
                Container  Shared
                            /   \
                       Antlib1  Antlib2 ...
  -            
+
-
    +
    • The Bootstrap ClassLoader contains the classes and resources @@ -222,22 +208,20 @@
    - -
-
-
-
-
- Copyright © 2000-2002, Apache Software Foundation -
-
+ + + + 1.6 +158 -278 jakarta-ant-myrmidon/site/docs/configuring.html Index: configuring.html =================================================================== RCS file: /home/cvs/jakarta-ant-myrmidon/site/docs/configuring.html,v retrieving revision 1.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- configuring.html 19 May 2002 13:37:50 -0000 1.5 +++ configuring.html 6 Jun 2002 12:54:28 -0000 1.6 @@ -6,234 +6,172 @@ + - + - + Apache Myrmidon - On Task Configuring in Ant 2 - - - - - -
+ + + + + + + - - + + + - - - -
-

Myrmidon

- -

User Guide

- -

Extending Myrmidon

- -

Developers Guide

- -
- - - + -
- - Introduction - -
-
-

This section will describe in detail the mechanism via which tasks are +

+ +
+
+

Introduction

+

This section will describe in detail the mechanism via which tasks are configured. Configuration is the name given to the stage in tasks lifecycle via which the XML representation is mapped onto the task object.

- -
- - - -
- - Names - -
-
-

When mapping the XML representation on to the task object you + +

+

Names

+

When mapping the XML representation on to the task object you need to be able map the names as they appear in the XML to the names as they appear in the Java code. The process is for generating a java name from the xml name is as follows.

-
    +
    1. Capitalize the first character of name.
    2. Find any '-' characters in XML name and remove character and capitalize the following letter. (And there must be a following letter)
    -

    Some example mappings;

    -
    - - - - - - - - - - - - - - - - -
      +                        

    Some example mappings;

    +
    +
       my-name    ===>   MyName
       aString    ===>   AString
       Basedir    ===>   Basedir
       baseDir    ===>   BaseDir
      -url        ===>   Url
    +url ===> Url
    -

    Note that the above transformation is lossy and as such the +

    Note that the above transformation is lossy and as such the following XML names all map to the same Java name. The ant1.x mapping is similarly lossy and in practice this has not been an issue.

    -
    - - - - - - - - - - - - - - - - -
      +                          
    +
       base-dir   ===>   BaseDir
       Base-dir   ===>   BaseDir
       baseDir    ===>   BaseDir
      -BaseDir    ===>   BaseDir
    +BaseDir ===> BaseDir
    -

    NOTE: We should really resolve this and either disallow '-' characters +

    NOTE: We should really resolve this and either disallow '-' characters or disallow uppercase or something. (PD)

    -
-
- - - -
- - Resolving Values - -
-
-

The first stage of mapping the XML representation to the task + +

+

Resolving Values

+

The first stage of mapping the XML representation to the task is resolving all text data. The text data that needs to be resolved include the values of attributes and the content.

-

Resolution consists of expanding any property references in the text +

Resolution consists of expanding any property references in the text data. Property references are identified as starting with the token "${" and finishing with another "}" token. The text in between is the name of a property. The value of the property replaces the sequence of text starting with the "${" token and finishing with the "}" token.

-

Note that the value of the property may not be a string. If the text data +

Note that the value of the property may not be a string. If the text data contains text (or other property references) to either side of the property reference then it must be converted to a String.

-
-
- - - -
- - Modeller - -
-
-

Currently the representation of object are stored in a hierarchial + +

+

Modeller

+

Currently the representation of object are stored in a hierarchial tree of org.apache.myrmidon.api.metadata.ModelElement objects. Each ModelElement has a number of attributes and can have either content or sub-elements.

-

In most cases it is the responsibility of the runtime to map +

In most cases it is the responsibility of the runtime to map the ModelElement onto an object. However in some cases it may be useful for the object to get access to it's own model and for it to explicitly manage it's own configuration. In this case the object should implement the org.apache.myrmidon.api.metadata.Modeller interface which will provide the mechanism for the object to receive its own representation and configure itself.

-

Note that the Modeller mechanism should be avoided if possible +

Note that the Modeller mechanism should be avoided if possible as it adds considerable complexity to the implementing object.

-
-
- - - -
- - Attributes - -
-
-

To map an XML attribute on to a Java object, the name of the + +

+

Attributes

+

To map an XML attribute on to a Java object, the name of the attribute is mapped to a java name and prefixed with the string "set". The resulting string is then used to look up a method with a single parameter.

-

For example, for the attribute "world" would result +

For example, for the attribute "world" would result in a lookup of a method named "setWorld" with a single parameter.

-

If multiple methods were matched during the lookup then an +

If multiple methods were matched during the lookup then an exception is thrown indicating ambiguity. Theres is an exception to this rule that allows 2 methods to be matched if one of the methods takes a java.lang.String parameter. The method @@ -241,144 +179,90 @@ the other method would be chosen. This exception is allowed as it is common practice for a task to evolve from String parameters to more strongly typed parameters.

-

The resolved text data of the attribute must be +

The resolved text data of the attribute must be converted to the type of the matched methods parameter. For example, if the "setWorld" method took a parameter of type java.io.File then the resolved text data must be converted into a java.io.File. The conversion is done by the Converter architecture that is more fully described in the Converter HOWTO.

-

After the value is converted to the correct type the method is +

After the value is converted to the correct type the method is invoked with the converted value.

-
-
- - - -
- - Content - -
-
-

The XML representation of object can have either have nested + +

+

Content

+

The XML representation of object can have either have nested elements or nested text (content) but not both. To add the content to an object a method named "content" with one parameter is looked up. The resolved text data for content is then converted to the type of the parameter and passed in via the method.

-
-
- - - -
- - Element - -
-
-

Mapping an ModelElement onto a java object is a series of steps. + +

+

Element

+

Mapping an ModelElement onto a java object is a series of steps. If the ModelElement name ends with the string "-ref" then it is treated as a reference element - see the Referrenced Elements section. Otherwise, the element is first attempted to be mapped as a Named Element and if no match is found via that method it tries to treat the element as a Typed Element.

- - - -
- - Named Elements - -
-
-

To map a named ModelElement on to a Java object, the name of +

+

Named Elements

+

To map a named ModelElement on to a Java object, the name of the element is mapped to a java name and prefixed with the string "add". The resulting string is then used to look up a method with a single parameter.

-

For example, for the attribute "geometry" would result +

For example, for the attribute "geometry" would result in a lookup of a method named "addGeometry" with a single parameter. If multiple methods were matched during the lookup then an exception is thrown indicating ambiguity. If no methods were found that match name then skip down to configuring "typed" elements.

-

The type of the methods single parameter is then examined to determine +

The type of the methods single parameter is then examined to determine what happens next. There are two valid situations, if neither of these are satisfied, then an exception is thrown.

-
    +
    • The parameters type is org.apache.myrmidon.api.metadata.ModelElement
    • The parameters type is a concrete class
    -

    1. If the parameter has a type of org.apache.myrmidon.api.metadata.ModelElement +

    1. If the parameter has a type of org.apache.myrmidon.api.metadata.ModelElement then the un-modified model representation of element is passed to object by invoking the adder method.

    -

    2. If the parameters type is concrete then an instance of the parameter is +

    2. If the parameters type is concrete then an instance of the parameter is instantiated using the default constructor. This created object is then configured in the same manner as task using the elements representation as the model. After the object is configured it is passed into object by invoking the adder method.

    -
-
- - - -
- - Referrenced Elements - -
-
-

A referenced element is one that has a name ending in + +

+

Referrenced Elements

+

A referenced element is one that has a name ending in "-ref" and has a single attribute "name" and no content or child elements.

-

The value of the "name" attribute is the name of a property. +

The value of the "name" attribute is the name of a property. The value of this property is retrieved from the TaskContext.

-

Like with Named Elements the name of the element (minus +

Like with Named Elements the name of the element (minus the "-ref" part) is mapped to a java name and prefixed with the string "add". The resulting string is then used to look up a method with a single parameter. If multiple methods were matched during the lookup then an exception is thrown indicating ambiguity.

-

The value retrieved from the TaskContext is then converted to the type +

The value retrieved from the TaskContext is then converted to the type of the methods parameter and the add method is invoked with the converted value.

-

An example usage is the following;

-
- - - - - - - - - - - - - - - - -
  +                        

An example usage is the following;

+
+
   
               <my-task ...>
                 <classpath-ref name="project.class.path"/>
               </my-task>
   
  -
+
-
-
- - - -
- - Typed Elements - -
-
-

"Typed" elements can also be added to an object. A typed element + +

+

Typed Elements

+

"Typed" elements can also be added to an object. A typed element is one in which the name of the element actually refers to a type rather than the name of the adder to call.

-

For example, you may wish to allow a task to add arbitrary instances of the +

For example, you may wish to allow a task to add arbitrary instances of the Condition role to a task. So instead of adding methods such as addAnd(AndCondition), addOr(OrCondition) and addXor(XorCondition) you can instead add a single method @@ -388,34 +272,30 @@ a "nand" condition they could write the Nand type use it in their build file. For a discussion on roles and types see the Types HOWTO.

-

To use a Typed adder there must be a single method named "add" that +

To use a Typed adder there must be a single method named "add" that has a single parameter. The parameter MUST be an abstract interface and must be registered as a role. The name of the element is then used to lookup the a type in the TypeManager with a role matching the interface name.

-

For example if an element named "nand" was added to an object that had +

For example if an element named "nand" was added to an object that had an adder with the signature void add( Condition condition ) then the type named "nand" in the role "Condition" would be looked up. An instance of the type would then be created using the default constructor and the created object would be configured and then adder to object using adder.

-
-
-
-
-
-
-
-
- Copyright © 2000-2002, Apache Software Foundation -
-
+ + + + 1.9 +91 -91 jakarta-ant-myrmidon/site/docs/differences.html Index: differences.html =================================================================== RCS file: /home/cvs/jakarta-ant-myrmidon/site/docs/differences.html,v retrieving revision 1.8 retrieving revision 1.9 diff -u -r1.8 -r1.9 --- differences.html 24 May 2002 06:39:41 -0000 1.8 +++ differences.html 6 Jun 2002 12:54:28 -0000 1.9 @@ -6,91 +6,93 @@ + - + - + Apache Myrmidon - Differences to Ant 1 - - - - - -
+ + + + + + + - - + + - - - -
-

Myrmidon

- -

User Guide

- -

Extending Myrmidon

- -

Developers Guide

- -
- - - + -
- - Differences to Ant 1.x - -
-
-

Some of the differences between Ant 1.x and Myrmidon:

-
    +
+ +
+
+

Differences to Ant 1.x

+

Some of the differences between Ant 1.x and Myrmidon:

+
  • Dependencies on targets in other build files are now possible. The user first places a @@ -150,25 +152,23 @@
-

There are plenty more features planned. You can read about them +

There are plenty more features planned. You can read about them here.

- -
-
-
-
-
- Copyright © 2000-2002, Apache Software Foundation -
-
+ + + + 1.6 +92 -92 jakarta-ant-myrmidon/site/docs/getinvolved.html Index: getinvolved.html =================================================================== RCS file: /home/cvs/jakarta-ant-myrmidon/site/docs/getinvolved.html,v retrieving revision 1.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- getinvolved.html 19 May 2002 13:37:50 -0000 1.5 +++ getinvolved.html 6 Jun 2002 12:54:28 -0000 1.6 @@ -6,118 +6,118 @@ + - + - + Apache Myrmidon - Get Involved - - - - - -
+ + + + + + + - - + + - - - -
-

Myrmidon

- -

User Guide

- -

Extending Myrmidon

- -

Developers Guide

- -
- - - + -
- - Get Involved - -
-
-

There are plenty of things you can do to help out with Myrmidon. The +

+ +
+
+

Get Involved

+

There are plenty of things you can do to help out with Myrmidon. The Todo list 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.

-

Some things that are worth reading if you do want to get involved:

-
    +

    Some things that are worth reading if you do want to get involved:

    + -

    There is no Ant 2 or Myrmidon mailing list yet, so direct any questions +

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

    - -
-
-
-
-
- Copyright © 2000-2002, Apache Software Foundation -
-
+ + + + 1.6 +103 -119 jakarta-ant-myrmidon/site/docs/index.html Index: index.html =================================================================== RCS file: /home/cvs/jakarta-ant-myrmidon/site/docs/index.html,v retrieving revision 1.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- index.html 19 May 2002 13:37:50 -0000 1.5 +++ index.html 6 Jun 2002 12:54:28 -0000 1.6 @@ -6,117 +6,111 @@ + - + - + Apache Myrmidon - Myrmidon - - - - - -
+ + + + + + + - - + + - - - -
-

Myrmidon

- -

User Guide

- -

Extending Myrmidon

- -

Developers Guide

- -
- - - + -
- - What is Ant? - -
-
-

Ant is a cross-platform build tool that features ease of +

+ +
+
+

What is Ant?

+

Ant is a cross-platform build tool that features ease of use and extensibility as it's primary goal.

-

Why another build tool when there is already make, gnumake, +

Why another build tool when there is already make, gnumake, nmake, jam, and others? Make-like tools are inherently shell-based; they execute native commands and shell scripts to perform the work associated with the build process. So to extend the the tool by writing a program or script executable by the OS you are on. This makes it difficult to achieve portability between platforms.

-

Ant is a different beast. Instead of using OS-specific commands +

Ant is a different beast. Instead of using OS-specific commands to extend the build process, you leverage the cross-platform features of Java to write "tasks". This makes it much easier to achieve a portal build process between platforms. Ant also differs in that it uses XML to describe the build process.

- -
- - - -
- - What is Myrmidon? - -
-
-

Myrmidon is a proposal for Ant 2. Ant 2 is the next evolution of the + +

+

What is Myrmidon?

+

Myrmidon is a proposal for Ant 2. Ant 2 is the next evolution of the Ant build tool aimed at removing many of the limitations of the Ant 1.x product. In particular it aims to;

-
    +
    • Remove ambiguities and points of confusion for build file writers.
    • Ease deployment and management of 3rd party tasks and @@ -128,28 +122,20 @@
    • Integrate templating technologies such as XSLT, velocity etc to enable development of reusable build file elements.
    -

    You can read more about the goals of Ant 2 +

    You can read more about the goals of Ant 2 here.

    -

    Myrmidon was specifically designed as both a tool and as +

    Myrmidon was specifically designed as both a tool and as an API library that can be reused in other products. It contains the basic building blocks for assembling any sort of task-based tool. Ant 2 is an example of such a tool, which could be assembled using the Myrmidon task container, and a library of build related tasks. In the future expect to see Testing frameworks, Job Schedulers (ie Cron managers), shells and install tools based on the Myrmidon base.

    -
-
- - - -
- - A Rose by any other name ... - -
-
-

+ +

+

A Rose by any other name ...

+

The name Myrmidon is a derivation of a mythological name for some ants that were turned into soldiers by the god Zeus. It came to mean "a subordinate who executes orders unquestioningly" which seemed suitable for a task execution/build tool. A more complete @@ -157,7 +143,7 @@ http://bondi-blue.parlez.com/previous_words/myrmidon.txt.

- + The appellation Myrmidon was derived from the Greek word "myrmex", meaning ant. According to Greek mythology, the Myrmidons were transformed into humans by the god Zeus as an act of kindness to his @@ -168,22 +154,20 @@ Myrmidons. See "The Iliad" for Homers' account of the Myrmidons during the Trojan War. -
-
-
-
-
-
- Copyright © 2000-2002, Apache Software Foundation -
-
+ + + + 1.6 +131 -227 jakarta-ant-myrmidon/site/docs/librarys.html Index: librarys.html =================================================================== RCS file: /home/cvs/jakarta-ant-myrmidon/site/docs/librarys.html,v retrieving revision 1.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- librarys.html 19 May 2002 13:37:50 -0000 1.5 +++ librarys.html 6 Jun 2002 12:54:28 -0000 1.6 @@ -6,102 +6,104 @@ + - + - + Apache Myrmidon - On Libraries in Ant 2 - - - - - -
+ + + + + + + - - + + + - - - -
-

Myrmidon

- -

User Guide

- -

Extending Myrmidon

- -

Developers Guide

- -
- - - + -
- - Library Management - -
-
-

Long ago there was identified the need for libraries that contain +

+ +
+
+

Library Management

+

Long ago there was identified the need for libraries that contain tasks and other elements present in the build file. This document attempts to describe the mechanism via which these libraries will be defined and used in Ant 2. The libraries (also referred to as deployments) will be termed antlibs.

-

Ant libraries can be packaged and signed into a ANt Type Library +

Ant libraries can be packaged and signed into a ANt Type Library format (.atl) using the standard Java Archive tools. (For details on the .jar file format see the Jar Specification.

-

When packaged into such a form the META-INF/ directory contains +

When packaged into such a form the META-INF/ directory contains ant specific descriptors in addition to the standard Jar manifest and other descriptor files. The archive will also contain the @@ -109,7 +111,7 @@ library defines. It may also contain additional resources that can be referenced in the build file (an example being DTDs).

-

The library may also need access to other libraries or resources +

The library may also need access to other libraries or resources to perform its job. For instance, if the task loaded an XML document and then processed said document using the Trax API then @@ -119,34 +121,20 @@ "Optional Package" Specification to declare dependencies on other libraries.

-

The libraries will usually be installed in standard locations that +

The libraries will usually be installed in standard locations that make it possible for the Ant container to automatically locate and scan the libraries. It will also be possible for the users to specify additional search locations or even the specific location of ant libraries.

-

The following sections will describe each of these different facets +

The following sections will describe each of these different facets in greater detail.

- - - -
- - Descriptors - -
-
-

FIXME: Import this part from other doco

-
-
- - - -
- - Class and Resource Files - -
-
-

The class and resources files should be stored as in standard jars. The +

+

Descriptors

+

FIXME: Import this part from other doco

+
+
+

Class and Resource Files

+

The class and resources files should be stored as in standard jars. The root directory being the base via which code and resources are loaded. So the .class file for the Java class @@ -154,22 +142,14 @@ would be stored in /com/biz/tasks/Mytask.class

-
-
- - - -
- - Dependencies - -
-
-

It is often the case that a library will need external resources. The + +

+

Dependencies

+

It is often the case that a library will need external resources. The example given above described dependence on an external XML library. The ant library thus needs a mechanism via which to declare dependencies on external libraries.

-

Ant 2 uses the "Optional Package" mechanism. Prior to JDK1.3, an "Optional +

Ant 2 uses the "Optional Package" mechanism. Prior to JDK1.3, an "Optional Package" was known as an Extension. The specification for this mechanism is available in the JDK1.3 documentation in the directory @@ -180,83 +160,43 @@ http://java.sun.com/j2se/1.3/docs/guide/extensions/versioning.html.

-

This mechanism was adopted as it is an established standard. The standard +

This mechanism was adopted as it is an established standard. The standard is also begining to be adopted by other specifications such as the Servlet 2.3 API. Thus we are likely to see an increase of jars using this mechanism to specify dependencies.

-

The "Optional Package" mechanism allows jars to specify dependencies on other +

The "Optional Package" mechanism allows jars to specify dependencies on other jars that implement a particular specification at particular version levels. For example you could specify a dependency on the Trax 1.1 API by adding the following to the manifest of your jar.

-
- - - - - - - - - - - - - - - - -
  +                          
+
   Extension-List: trax
   trax-Extension-Name: Java API for XML Parsing
   trax-Specification-Version: 1.1
  -                
+
-

In some cases you may also wish to specify a dependency on a specific vendors +

In some cases you may also wish to specify a dependency on a specific vendors implementation. For instance you may need to use xalan due to it implementing a particular extension you need. In that case you manifest may contain;

-
- - - - - - - - - - - - - - - - -
  +                          
+
   Extension-List: trax
   trax-Extension-Name: Java API for XML Parsing
   trax-Specification-Version: 1.1
   trax-Implementation-Title: org.apache.xalan.xslt
   trax-Implementation-Version: 2.1.0
   trax-Implementation-Vendor: Apache Software Foundation
  -                
+
-

In many cases there will be no distinction between the specification and +

In many cases there will be no distinction between the specification and the implementation of a library. For instance the Velocity project only has one implementation and one specification. In which case it is sufficient to just declare a dependency on the Velocity "Specification". A library that uses both the Trax API and the Velocity project may look like;

-
- - - - - - - - - - - - - - - - -
  +                          
+
   Extension-List: trax velocity
   velocity-Extension-Name: org.apache.velocity
   velocity-Specification-Version: 1.0
  @@ -265,62 +205,30 @@
   trax-Implementation-Title: org.apache.xalan.xslt
   trax-Implementation-Version: 2.1.0
   trax-Implementation-Vendor: Apache Software Foundation
  -                
+
-

To make other jars available to Ant libraries as "Optional Packages" +

To make other jars available to Ant libraries as "Optional Packages" or Extensions then you need to add a few lines to the manifest of the other jar. The minimal manifest is the following;

-
- - - - - - - - - - - - - - - - -
  +                          
+
   Extension-Name: org.realityforge.dve
   Specification-Vendor: Peter Donald
   Specification-Version: 1.0
  -                
+
-

It is important to note that looking for dependencies is recursive. For example, +

It is important to note that looking for dependencies is recursive. For example, if the ant library depends upon jar A and and A depends on B then both A and B will need to be loaded by the container.

-
-
- - - -
- - Implementation Notes - -
-
-

So far there has been no mention of implementation strategies for + +

+

Implementation Notes

+

So far there has been no mention of implementation strategies for managing ClassLoaders and other details about where the "Optional Packages" are stored. This section will outline such details but they could change in the future. The above specification will still be accurate but the approach to implementing specification will be different.

-

In the current architecture all of the "Optional Packages" are assumed to +

In the current architecture all of the "Optional Packages" are assumed to be stored in the $ANT_HOME/ext directory. The runtime will scan this directory for jars and add all the "optional Packages" found into a @@ -328,31 +236,27 @@ all the "Optional Packages". The user is able to specify an alternative directory or add a new directory to search on the commandline.

-

When the container attempts to load an ant library it will also try to load +

When the container attempts to load an ant library it will also try to load any needed dependencies. First it will check the parent ClassLoaders to see if any of them contain the required dependencies. If not then it will search the "Optional Packages" registry. If the dependency is not found then a error will be signaled. If the dependency is found in the "Optional Packages" registry then it is loaded by the same ClassLoader that is used to load the Ant library.

-
-
- -
-
-
-
-
- Copyright © 2000-2002, Apache Software Foundation -
-
+ + + + 1.5 +513 -759 jakarta-ant-myrmidon/site/docs/project-descriptor.html Index: project-descriptor.html =================================================================== RCS file: /home/cvs/jakarta-ant-myrmidon/site/docs/project-descriptor.html,v retrieving revision 1.4 retrieving revision 1.5 diff -u -r1.4 -r1.5 --- project-descriptor.html 19 May 2002 13:37:50 -0000 1.4 +++ project-descriptor.html 6 Jun 2002 12:54:28 -0000 1.5 @@ -6,423 +6,332 @@ + - + - + Apache Myrmidon - Project Descriptor - - - - - -
+ + + + + + + - -
-

Myrmidon

- -

User Guide

- -

Extending Myrmidon

- -

Developers Guide

- -
- - - +
- - Project Descriptor - -
-
-

Each Myrmidon sub-project has a project descriptor associated with it. +

+ +
+
+

Project Descriptor

+

Each Myrmidon sub-project has a project descriptor associated with it. This is an xml file that provides meta-information about the project, such as the name of the project, its current version, where the source can be found, and so on. The descriptor is used to generate the project's build file.

-

The root element of the project descriptor must be a +

The root element of the project descriptor must be a <project> element. The <project> element may contain the following elements:

- - -
- + + + - - + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - + +
Element - - - - + + Description - - - - + + Multivalued - - -
- + +
additional-build - - - + The details of how to compile and assemble the project's additional Jars. These are Jar files that are assembled as part of the build, but not included as part of the project output. For example, test Jar files. - - - + yes - -
- +
build - - - + The details of how to compile the project and assemble it into jar files. - - - + no - -
- +
classpath - - - + The project classpath, used for compiling the project Jars, unit tests, and additional Jars. This is an Ant <path> data-type. - - - + no - -
- +
compilePatterns - - - + The include and exclude patterns to use when compiling the project Jars, unit tests, and additional Jars. This is an Ant <patternset> data-type. - - - + no - -
- +
copyrightYear - - - + The year(s) that the project was copyrighted in. - - - + no - -
- +
currentVersion - - - + The version number for the project. - - - + no - -
- +
dist - - - + The additional Ant tasks for preparing the distribution. By default, the project's jar files and Javadocs are copied into the distribution directory. Use this element to perform extra tasks to assemble the distribution. - - - + no - -
- +
id - - - + The identifier for the project. Used in generated file and directory names. - - - + no - -
- +
name - - - + The descriptive name of the project. Used as the title for the project's Javadocs. - - - + no - -
- +
property - - - + A global build property. This is an Ant <property> task. - - - + yes - -
- +
target - - - + An additional target to add to the build file. This is an Ant target, and is copied directly into the generated build file. - - - + yes - -
- +
unitTest - - - + The details of how to compile and execute the unit tests. - - - + no - -
- - -
- - Build Definition - -
-
-

The <build> and <additional-build> +

+

Build Definition

+

The <build> and <additional-build> elements describes how to compile and assemble a set of Jar files. The <build> element describes the Jar files included as part of the project's output. The <additional-build> describes Jar files that are not included in the project's output, such as test files. These elements may contain the following nested elements:

- - - -
- + + + - - + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - + +
Element - - - - + + Description - - - - + + Multivalued - - -
- + +
classpath - - - + The classpath to use for compiling the Jars. This is an Ant <path> data-type. This classpath is appended to the project classpath. Note that the Ant @@ -430,527 +339,372 @@ include the Ant runtime, add an empty <ant-runtime> element to this <classpath> element. - - - + no - -
- +
compilePatterns - - - + The patternset to use when compiling the project source. This is an Ant <patternset> data-type. This patternset is added to the project compile patternset. - - - + yes - -
- +
jar - - - + Defines a Jar output file. - - - + yes - -
- +
lib-path - - - + Defines the directory to place the assembled Jar files (<additional-build> only). - - - + no - -
- +
prepare - - - + Additional Ant tasks to perform before compiling the source. This can be used, for example, to check for the availability of various libraries (<build> only). - - - + no - -
- +
sourceDirectory - - - + The directory containing the project's Java source files. - - - + yes - -
- -
- - - + + + - - - -
- - Unit Test Definition - -
-
-

The <unitTest> element defines how to compile + +

+

Unit Test Definition

+

The <unitTest> element defines how to compile and execute the project's unit tests. The <unitTest> element may contain the following nested elements:

- - - -
- + + + - - + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - + +
Element - - - - + + Description - - - - + + Multivalued - - -
- + +
classpath - - - + The classpath to use for compiling and executing the project unit tests. This is appended to the project classpath. This is an Ant <path> data-type. - - - + no - -
- +
compilePatterns - - - + The patternset to use when compiling the unit tests. This is an Ant <patternset>. This is combined with the compile patternset. - - - + yes - -
- +
includeDescriptors - - - + Controls whether antlib descriptors are generated for the unit tests. Descriptors are generated by default. - - - + no - -
- +
prepare - - - + Additional Ant tasks to perform before executing the unit tests. - - - + no - -
- +
sourceDirectory - - - + The directory containing the project's unit test source files. - - - + no - -
- +
unitTestPatterns - - - + The patternset to use to select the unit tests to execute. This is an Ant <patternset> datatype. - - - + no - -
- -
- - - -
- - Jar Definition - -
-
-

A <jar> element defines a jar file produced by + +

+

Jar Definition

+

A <jar> element defines a jar file produced by the build. A manifest and antlib descriptors are generated for the Jar. A <jar> element may take the following nested elements:

- - - -
- + + + - - + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - + +
Element - - - - + + Description - - - - + + Multivalued - - -
- + +
attribute - - - + Defines an attribute to add to the main section of the manifest. - - - + yes - -
- +
depends - - - + Defines the extensions which the output file depends on. Used to generate the manifest. - - - + no - -
- +
extension - - - + Defines an extension. Used to generate the manifest. - - - + no - -
- +
fileset - - - + Additional files to include in the Jar. This is an Ant <fileset> datatype. - - - + yes - -
- +
id - - - + A unique short name for the Jar. This is used in the file name, and the names of generated files. - - - + no - -
- +
includeDescriptors - - - + Controls whether antlib descriptors are generated for the Jar. Descriptors are generated by default. - - - + no - -
- +
metainf - - - + See the Ant <jar> task. - - - + yes - -
- +
name - - - + Specifies the name of the Jar. By default, the name is generated from the Jar Id and current project version. - - - + no - -
- +
patternset - - - + Specifies which classes to include in the Jar. This is an Ant <patternset>. - - - + no - -
- -
-
-
-
-
-
-
- Copyright © 2000-2002, Apache Software Foundation -
-
+ + + + 1.4 +139 -179 jakarta-ant-myrmidon/site/docs/running.html Index: running.html =================================================================== RCS file: /home/cvs/jakarta-ant-myrmidon/site/docs/running.html,v retrieving revision 1.3 retrieving revision 1.4 diff -u -r1.3 -r1.4 --- running.html 2 Jun 2002 14:05:55 -0000 1.3 +++ running.html 6 Jun 2002 12:54:28 -0000 1.4 @@ -6,234 +6,194 @@ + - + - + Apache Myrmidon - Running Myrmidon - - - - - -
+ + + + + + + - -
-

Myrmidon

- -

User Guide

- -

Extending Myrmidon

- -

Developers Guide

- -
- - - + -
- - Installing Myrmidon - -
-
-

Installing Myrmidon is easy. Simply extract the contents of the +

+ +
+
+

Installing Myrmidon

+

Installing Myrmidon is easy. Simply extract the contents of the distribution zip or tar file, to whichever install directory you like. You should also add the distribution's bin directory to the PATH environment variable.

- -
- - - + + - - - -
- - Running Myrmidon - -
-
-

+ +

+

Running Myrmidon

+

To run Myrmidon, use one of the following methods:

- - - -
- - Launcher Script - -
-
-

+

+

Launcher Script

+

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

-

+

- - - -
- + + + - - + + - + - - - + + + - + - - - + + + - + - + +
Variable - - - - + + Description - - -
- + +
JAVA_HOME - - - + The directory that the JDK is installed in. - -
- +
JAVACMD - - - + The command to use to start the JVM. Defaults to java. - -
- +
ANT_HOME - - - + The directory containing the Myrmidon distribution. This must be set when running on Windows 95, 98 or Me. - -
- -
- - - -
- - Executable Jar File - -
-
-

+ +

+

Executable Jar File

+

The Myrmidon distribution includes an executable Jar file, which can be used to run Myrmidon. Use the following command:

-
  +                        
       prompt> java -jar ant-home/bin/myrmidon-launcher.jar options
       
-
-
-

When started, Myrmidon looks for a project file called build.ant +

+

When started, Myrmidon looks for a project file called build.ant in the current directory. A different project file can be specified using the -f command-line option. Myrmidon executes the targets that are listed on the command-line, or the default target if none is given. For example, the following command executes targets clean and build from project file my-project.xml:

-
  +                        
       prompt> ant -f my-project.xml clean build
       
-

+

Run Myrmidon with the -h command-line option for a list of the command-line options that are available.

-
-
-
-
-
-
- Copyright © 2000-2002, Apache Software Foundation -
-
+ + + + 1.5 +171 -211 jakarta-ant-myrmidon/site/docs/subprojects.html Index: subprojects.html =================================================================== RCS file: /home/cvs/jakarta-ant-myrmidon/site/docs/subprojects.html,v retrieving revision 1.4 retrieving revision 1.5 diff -u -r1.4 -r1.5 --- subprojects.html 19 May 2002 13:37:50 -0000 1.4 +++ subprojects.html 6 Jun 2002 12:54:28 -0000 1.5 @@ -6,272 +6,232 @@ + - + - + Apache Myrmidon - Myrmidon Subprojects - - - - - -
+ + + + + + + - -
-

Myrmidon

- -

User Guide

- -

Extending Myrmidon

- -

Developers Guide

- -
- - - + + + - - - -
- - Myrmidon Subprojects - -
-
-

Myrmidon is made up of several sub-projects. The projects are described below, +

+ +
+
+

Myrmidon Subprojects

+

Myrmidon is made up of several sub-projects. The projects are described below, in rough order of dependency. Most of these projects are intended to be reusable outside Myrmidon. Each project is contained in its own subdirectory of the source tree. The directory layout for each project is the same.

-

The projects are:

- - - -
- +

The projects are:

+ + + - - + + - + - - - + + + - + - - - + + + - + - - - + + + - + - - - + + + - + - - - + + + - + - - - + + + - + - - - + + + - + - - - + + + - + - + +
Project - - - - + + Description - - -
- + +
buildtools - - - + Utilities used to build Myrmidon. - -
- +
aut - - - + A library of reusable system level components. These components provide low-level services, such as managing the execution of native commands, or providing a Virtual File System. - -
- +
api - - - + This project defines the task API. This is the API which the tasks use to communicate with the task container that they are executing in. - -
- +
container - - - + The implementation of the task container. This project can be split into two broad parts: The container API, which defines the set of services that are assembled together to form the container, and the standard implementations of those services. This project also contains front-ends for embedding Myrmidon, or running it from the command-line. - -
- +
framework - - - + A collection of general purpose classes which can be used as the starting point for writing tasks. This includes general purpose data types, utility classes, and a handful of abstract task implementations. - -
- +
antlib - - - + The tasks libraries, or antlibs, which contain the standard tasks and data-types for the Myrmidon distribution. - -
- +
ant1compat - - - + The Ant 1 compatibility library. This is an antlib which provides an adaptor between the Ant 1 classes, and the Myrmidon task and container APIs. It allows tasks compiled for Ant 1 to execute in Myrmidon without modification. The ant1compat antlib also includes all of the Ant 1 tasks, which makes them available for use in Myrmidon projects. - -
- +
myrmidon - - - + This project assembles the output from the other projects into the final Myrmidon distribution. - -
- +
site - - - + The documentation and web site for Myrmidon. - -
- -
-
-
-
-
- Copyright © 2000-2002, Apache Software Foundation -
-
+ + + + 1.6 +101 -141 jakarta-ant-myrmidon/site/docs/task.html Index: task.html =================================================================== RCS file: /home/cvs/jakarta-ant-myrmidon/site/docs/task.html,v retrieving revision 1.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- task.html 19 May 2002 13:37:50 -0000 1.5 +++ task.html 6 Jun 2002 12:54:29 -0000 1.6 @@ -6,93 +6,95 @@ + - + - + Apache Myrmidon - My First Task - - - - - -
+ + + + + + + - - + + + - - - -
-

Myrmidon

- -

User Guide

- -

Extending Myrmidon

- -

Developers Guide

- -
- - - + -
- - My First Task - -
-
-

In Ant 1 it was very easy to write your own task. In Ant 2 we plan +

+ +
+
+

My First Task

+

In Ant 1 it was very easy to write your own task. In Ant 2 we plan to make it even easier. To write a basic task simply follow the following formula.

-
    +
    1. Create a Java class that extends org.apache.myrmidon.api.AbstractTask @@ -129,26 +131,12 @@ actual work of the task.
    - - - -
    - - A Basic Example - -
    -
    -

    So a basic task that has one attribute named "message" and just prints +

    +

    A Basic Example

    +

    So a basic task that has one attribute named "message" and just prints out this message is as simple as;

    -
    - - - - - - - - - - - - - - - - -
      +                          
    +
       package org.realityforge.tasks;
       
       import org.apache.myrmidon.api.AbstractTask;
      @@ -172,28 +160,12 @@
               System.out.println( m_message );
           }
       }
      -
    +
    -

    To use this task you could create a library but instead we will +

    To use this task you could create a library but instead we will just use <taskdef> to define the task. An example usage would be;

    -
    - - - - - - - - - - - - - - - - -
      +                          
    +
       
       
       <?xml version="1.0"?>
      @@ -210,35 +182,23 @@
       </project>
       
       
      -
    +
    -
    -
    - -
-
-
-
-
- Copyright © 2000-2002, Apache Software Foundation -
-
+ + + + 1.7 +225 -497 jakarta-ant-myrmidon/site/docs/todo.html Index: todo.html =================================================================== RCS file: /home/cvs/jakarta-ant-myrmidon/site/docs/todo.html,v retrieving revision 1.6 retrieving revision 1.7 diff -u -r1.6 -r1.7 --- todo.html 19 May 2002 13:37:50 -0000 1.6 +++ todo.html 6 Jun 2002 12:54:29 -0000 1.7 @@ -6,171 +6,135 @@ + - + - + Apache Myrmidon - Get Involved - - - - - -
+ + + + + + + - - + + + - - - -
-

Myrmidon

- -

User Guide

- -

Extending Myrmidon

- -

Developers Guide

- -
- - - + -
- - Todo List - -
-
-

The broad goal is to grow Myrmidon from a prototype task engine into a fully +

+ +
+
+

Todo List

+

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.

- - - -
- - Integrate XDocs proposal - -
-
-

Integrate with the XDocs proposal that generates XML documentation for +

+

Integrate XDocs proposal

+

Integrate with the XDocs proposal that generates XML documentation for tasks. Rework that proposal so that it knows about the Myrmidon specific patterns and features. Also rework it so that it can support reading documentation and examples from side-by-side the task.

-
-
- - - -
- - TaskInfo - -
-
-

Consider allowing task writers to write their own TaskInfo objects + +

+

TaskInfo

+

Consider allowing task writers to write their own TaskInfo objects (or at least have them generated from XDoclet directives). This would encompass both documentation and perhaps introspection of the types.

-
-
- - - -
- - XML Catalog to load XML Fragments - -
-
-

+ +

+

XML Catalog to load XML Fragments

+

When including fragments of XML we are currently forced to use relative paths. However this is sometimes undesirable when a single fragment needs to be used across several projects in several different locations. Instead we could use a Catalog to name the fragment and then each developer would only need to install the fragment once and it would be accessible from all the projects.

-
-
- - - -
- - Refactor Java Infrastructure into a Service - -
-
-

Much like Exec should be decoupled from Ant runtime, so should classes + +

+

Refactor Java Infrastructure into a Service

+

Much like Exec should be decoupled from Ant runtime, so should classes to implement java task for the same benefits.

-
-
- - - -
- - Structural Dependency Utils - -
-
-

+ +

+

Structural Dependency Utils

+

In the present ant, it is required that each task manage dependency separately. This makes it a lot of work to implement even simple dependency checking. To this day many of the core tasks do not implement it correctly. I am specifically talking about "structural" dependency information. The main reason is that it is painful to implement.

-

+

Some tasks do no dependency checking and will recompile/transform/etc everytime. Others may perform a simple dependency checking (ie if source file is newer than destination file then recompile). Ideally a dependency system would actually @@ -180,31 +144,15 @@ we need to allow tasks to implement this behaviour. Possibly by supplying an interface of the form;

-
- - - - - - - - - - - - - - - - -
  +                          
+
   public interface DependencyGenerator
   {
     File[] generateDependencies( File file );
   }
  -
+
-

+

Generating the dependency information is a costly operation and thus we do not want to be doing it everytime you run ant. We want to generate it on the initial build and then persist somewhere. Everytime a file is out of date, it's dependency information would @@ -214,76 +162,36 @@ as being compiled with -O2 flag. If any of the dependencies have changed or are out of date then foo.c would need to be recompiled.

-

+

A possible API would be

-
- - - - - - - - - - - - - - - - -
  +                          
+
   DependencyManager dm = ...;
   dm.setFileSet( myFileSet );
   dm.setDependencyCache( myDependencyCacheFile );
   File[] files = cm.getOutOfDate();
  -
+
-
-
- - - -
- - Antlibs storing templates - -
-
-

After a templating system is formalized it would useful to define + +

+

Antlibs storing templates

+

After a templating system is formalized it would useful to define a mechanism via which you can store templates in an antlib. These templates could then be loaded and used by build files through a "standard" mechanism. This may need to be merged with the XML catalog system.

-
-
- - - -
- - Antlibs Storing General Resources - -
-
-

Add a system via which ant libs can store general resources for + +

+

Antlibs Storing General Resources

+

Add a system via which ant libs can store general resources for consumption by build users. This could be used to store the XML fragments for the XML catalog, the template fragments for templates, images for documentation system and so forth.

-
-
- - - -
- - Coloring API - -
-
-

+ +

+

Coloring API

+

When you execute a task such as "javac" there is two types of dependency information that is important to analyze before we determine if we need to recompile a file. Say we are compiling Foo.java, it may depend on the Bar.java @@ -294,94 +202,54 @@ debug="false" then it is out of date and needs to be recompiled. We call this "environmental" dependency information "coloring".

-

+

So we need to create an infrastructure that allows tasks to manage "coloring". So a task should be able to add coloring information for each resource processed. When the task comes to process the resource again it will detect if the coloring has changed and if it has will force a recompile.

-

+

An API for such a bean has yet to be established but an example API would be.

-
- - - - - - - - - - - - - - - - -
  +                          
+
   ColoringManager cm = ...;
   cm.addColor( "debug", "true" );
   cm.addColor( "optimize", "false" );
   cm.setFileSet( myFileSet );
   File[] files = cm.getOutOfDate();
  -
+
-
-
- - - -
- - Create Task/Element/Attribute Naming guidelines - -
-
-

Currently Ant has a mixture of tasks from various stages it's evolution, with different + +

+

Create Task/Element/Attribute Naming guidelines

+

Currently Ant has a mixture of tasks from various stages it's evolution, with different authors and each utilizing different naming patterns. Some tasks use names such as "src" and "dest" while others use "file" and "tofile". It would be preferrable if consistent naming patterns were used. It is recomended that we come up with a "best practices" document to document our recomended naming patterns.

-

Before we can come up with such a document we need to identify common patterns through +

Before we can come up with such a document we need to identify common patterns through out the tasks. Several tasks have the notion of transforming input from a "source" to a "destination". So we should have consistent naming schemes for these attributes and elements. Analysis of existing tasks will likely bring out other similar patterns. Once we have identified and documented these similarities then we can establish conventions.

-
-
- - - -
- - Rethink Notification/Event scheme - -
-
-

We need to rethink the whole notificaiton scheme. Should tasks be able to + +

+

Rethink Notification/Event scheme

+

We need to rethink the whole notificaiton scheme. Should tasks be able to raise events? Probably as long as we have ContainerTasks. Should tasks be able to query state of run? ie Can a task request "are we paused?" or "are we stopped?" ? Probably as that way long running tasks are given the opportunity to be gracefully halted by the end users (primarily aimed at IDE vendors here).

-
    +
    • Add verbosity level to TaskEvent.
    • Fire taskFinished() events on task failure.
    • Get target finished and project finished events working.
    -
-
- - - -
- - XPath-like Locators for tasks - -
-
-

Most tasks are grouped into some sort of task container. The task containers + +

+

XPath-like Locators for tasks

+

Most tasks are grouped into some sort of task container. The task containers can be things like workspaces, projects, targets or other tasks. Each of these containers usually has a name. Thus we could refer to tasks via a path such as "/avalon/compile/javac" would refer to the task "javac" in the target "compile" @@ -389,91 +257,43 @@ to this path programatically - other people have also asked for access to things like the currently running target. We need to assess this and decide whether we wish to support it.

-

Another point to think about is that we could use XPath-like string to designate +

Another point to think about is that we could use XPath-like string to designate to other tasks to execute. ie antcall would refer to a path rather than a target name

-
-
- - - -
- - Embeddor HOWTO - -
-
-

Assigned To: Peter

-

Write a HOWTO describing how to embed Myrmidon into other + +

+

Embeddor HOWTO

+

Assigned To: Peter

+

Write a HOWTO describing how to embed Myrmidon into other applications.

-
-
- - - -
- - Optional Dependencies - -
-
-

Assigned To: Peter

-

Extend Myrmidons library management facilities so that optional + +

+

Optional Dependencies

+

Assigned To: Peter

+

Extend Myrmidons library management facilities so that optional dependencies may be declared for a library. ie The library will still operate in absence of such libraries but can provide further features if these libraries are present. Most likely this will be done via a new manifest entry "Optional-Extension-List:" that behaves similar to "Extension-List:" except that the extensions are optional.

-
-
- - - -
- - Facade task HOWTO - -
-
-

Currently we have a few tasks that have multiple implementations. For instance + +

+

Facade task HOWTO

+

Currently we have a few tasks that have multiple implementations. For instance Javac task can actually call jikes, jvc, classic javac or modern javac. Similar things will be seen with the jspc task and the cc task (if it ever gets written). We have a base class that is meant to facilitate this sort of task and make it easy to develope. See AbstractFacadeTask. However we need to write up a HOWTO so people can use it.

-
-
- - - -
- - Mail tasks - -
-
-

Convert the Ant 1.x Mail tasks to Myrmidon.

-
-
- - - -
- - Security Manager - -
-
-

Add the ability to run java programs that call System.exit() by adding a + +

+

Mail tasks

+

Convert the Ant 1.x Mail tasks to Myrmidon.

+
+
+

Security Manager

+

Add the ability to run java programs that call System.exit() by adding a security manager. Should look something like:

-
- - - - - - - - - - - - - - - - -
  +                          
+
   public class MyrmidonSecurityManager
       extends SecurityManager
   {
  @@ -486,70 +306,38 @@
       {
       }
   }
  -                
+
-
-
- - - -
- - Self Hosting - -
-
-

Myrmidon must be able to build itself. Currently, it is built using + +

+

Self Hosting

+

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

-
-
- - - -
- - Validation Pass - -
-
-

Consider calling validate() on task prior to execute(). This would allow + +

+

Validation Pass

+

Consider calling validate() on task prior to execute(). This would allow us to have a "make -k" mode that actually did basic validation and would also encourage task writers to do validation properly.

-
-
- - - -
- - Paths - -
-
-

Consider allowing the user to configure the ant system by setting the + +

+

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, @@ -560,20 +348,12 @@ %SYS_DRIVE%/Program Files/ant/ext
      • MacOSX System-wide: /Library/Ant/lib, /Library/Ant/ant/ext
      -
-
- - - -
- - Ant 1.x Compatibility - -
-
-

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

+

Ant 1.x Compatibility

+

The Ant 1 Compatibility layer is still in early stages of development.

-
    +
    • Update ant.jar and optional.jar to ant1.5 beta.
    • Get a version of <antcall> working.
    • @@ -595,19 +375,11 @@ Ant 1 Project, to minimise the amount of code duplication in Ant1CompatProject.
    -
-
- - - -
- - Virtual File System - -
-
-

The VFS needs plenty of work:

-
    + +
    +

    Virtual File System

    +

    The VFS needs plenty of work:

    +
    • Move files/folders.
    • Recursive folders copy.
    • Search through a file hierarchy, using Ant-style wildcards.
    • @@ -630,24 +402,16 @@ systems).
    -
-
- - - -
- - File Data-Types and Tasks - -
-
-

The file data-types, such as + +

+

File Data-Types and Tasks

+

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.

-
    +
    • Redesign the file data-types, replacing them with an interface-based API, plus a set of implementations. The API should use the VFS file @@ -732,22 +496,14 @@ 'touch' and 'mkdir' into a single task.
    -
-
- - - -
- - Command-line and Configuration Files - -
-
-

One of the goals of Ant 2 is to allow the user to easily customise and + +

+

Command-line and Configuration Files

+

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.

-
    +
    • Load configuration from system (from $ANT_HOME) and user (from $HOME) configuration files.
    • @@ -768,20 +524,12 @@
    -
-
- - - -
- - Scripting - -
-
-

Add the ability to extend Ant using languages other than + +

+

Scripting

+

Add the ability to extend Ant using languages other than Java:

-
    +
    • Define a task using a scripting language such as Javascript.
    • Use Rhino's ability to implement Java interfaces, to implement and define types, such as FileSelector, or @@ -789,22 +537,14 @@
    • Define a task using template.
    • Add some lightweight scripting tasks.
    -
-
- - - -
- - Documentation - -
-
-

Everyone loves writing documentation, and so a goal for Ant 2 is to + +

+

Documentation

+

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:

-
    +
    • 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.
    • @@ -818,19 +558,11 @@ of filling out.
    -
-
- - - -
- - Miscellaneous - -
-
-

A completely unordered list of items, big and small:

-
    + +
    +

    Miscellaneous

    +

    A completely unordered list of items, big and small:

    +
    • Search through the code for 'TODO' items and fix them.
    • Detect duplicate type names.
    • Validate type and role names.
    • @@ -875,25 +607,21 @@ TypeManager.createChildTypeManager(), Deployer.createChildDeployer, etc.
    • Configurer needs to be scoped. RoleManager probably does too.
    -
-
- -
-
-
-
-
- Copyright © 2000-2002, Apache Software Foundation -
-
+ + + + 1.6 +228 -326 jakarta-ant-myrmidon/site/docs/vfs.html Index: vfs.html =================================================================== RCS file: /home/cvs/jakarta-ant-myrmidon/site/docs/vfs.html,v retrieving revision 1.5 retrieving revision 1.6 diff -u -r1.5 -r1.6 --- vfs.html 19 May 2002 13:37:50 -0000 1.5 +++ vfs.html 6 Jun 2002 12:54:29 -0000 1.6 @@ -6,129 +6,120 @@ + - + - + Apache Myrmidon - VFS User Guide - - - - - -
+ + + + + + + - -
-

Myrmidon

- -

User Guide

- -

Extending Myrmidon

- -

Developers Guide

- -
- - - +
- - Handling Files - -
-
-

Myrmidon includes a Virtual File System (VFS), which allows files from +

+ +
+
+

Handling Files

+

Myrmidon includes a Virtual File System (VFS), which allows files from different sources to be treated identically. The VFS currently supports the following file types:

- - - +

<url>

+

Selects files whose URL matches an Ant 1 style pattern, or a regular expression.

+ + + - - - -
- + + + - - + + - + - + - - - + + + - + - + - - - + + + - + - + - - - + + + - + - + - + +
File System - - - - + + Description - - - - + + URL Format - - -
- + +
Local Files - - - + Files on the local file system. - - - + Three different formats are currently supported for local file names:
  • file:// absolute-file-name
  • @@ -138,75 +129,56 @@
- -
- +
Zip Files - - - + The contents of Zip files (and Jar, War, and Ear files). Currently, the VFS supports read-only access to Zip file contents. - - - + zip: zip-file-uri [!absolute-path] - -
- +
FTP - - - + Files on an FTP server. - - - + ftp:// [[password:] username@] hostname [:port] [absolute-path] - -
- +
SMB - - - + Files on a CFIS server, such as Samba or Windows shares. - - - + smb:// [[password:] username@] hostname [:port] [absolute-path] - -
-

Both forward or backward slashes can be used to separate the elements of +

Both forward or backward slashes can be used to separate the elements of a URL.

-

Here are some example URLs:

-
    +

    Here are some example URLs:

    +
    • build/classes
    • c:\program files\ant\bin
    • file://C:/program files/ant
    • @@ -214,123 +186,81 @@
    • ftp://adam@somehost/pub/downloads
    • smb://password:adam@somehost/home/adam
    -

    Currently, there are only a handful of VFS aware tasks. This will grow +

    Currently, there are only a handful of VFS aware tasks. This will grow as more tasks are ported to the new API, and data types.

    - - - -
    - - File Sets - -
    -
    -

    A file set in Myrmidon is more general than Ant 1's concept of a file set. +

    +

    File Sets

    +

    A file set in Myrmidon is more general than Ant 1's concept of a file set. Firstly, there is more than one type of file set. Secondly, they are VFS enabled. File sets are automatically converted to a path, and so can be used anywhere that a path can.

    -

    <v-fileset>

    -

    This is the equivalent of Ant 1's <fileset> (The name +

    <v-fileset>

    +

    This is the equivalent of Ant 1's <fileset> (The name is temporary, it will be changed to <fileset> once more porting work as been completed).

    -

    Rather than use a set of include and exclude patterns to choose the files +

    Rather than use a set of include and exclude patterns to choose the files that make up the file set, <v-fileset> takes zero or more file selectors. File selectors can be used to select files based on any attribute of the file, rather than just the name. You can use <name> selectors to achieve the same result as using includes or excludes.

    -

    A <v-fileset> element takes the following attributes:

    - - - -
    - +

    A <v-fileset> element takes the following attributes:

    + + + - - + + - + - + - + +
    Attribute - - - - + + Description - - - - + + Default Value - - -
    - + +
    dir - - - + The base directory for the file set. This can be any URL that the VFS supports. - - - + Required - -
    -

    A <v-fileset> element takes any number of nested +

    A <v-fileset> element takes any number of nested file selector elements. To be included in the file set, a file must be selected by all the file selectors. That is, the file selectors are implicitly AND-ed together. If no file selector is provided, all the files and directories are included in the set.

    -

    An example:

    -
    - - - - - - - - - - - - - - - - -
      +                        

    An example:

    +
    +
       
       <v-fileset dir="src">
           <name pattern="org/apache/tools/ant/**"/>
           <is-file/>
       </v-fileset>
      -
    +
    -

    <flat-fileset>

    -

    This file set takes a set of nested file sets and paths, and flattens them +

    <flat-fileset>

    +

    This file set takes a set of nested file sets and paths, and flattens them into a single directory. It can be used as a way of converting a path into a file set. It can also be used as a replacement for the flatten attribute for the copy and move tasks.

    -

    A <flat-fileset> element takes no attributes, and a set +

    A <flat-fileset> element takes no attributes, and a set of nested paths or file sets.

    -

    An example:

    -
    - - - - - - - - - - - - - - - - -
      +                        

    An example:

    +
    +
       
       <v-copy todir="dist/lib">
         <flat-fileset>
      @@ -340,95 +270,67 @@
           <v-path path="${classpath}"/>
         </flat-fileset>
       </v-copy>
      -
    +
    -

    <mapped-fileset>

    -

    A fileset that applies a file name mapper +

    <mapped-fileset>

    +

    A fileset that applies a file name mapper to a nested fileset.

    - -
    - - - -
    - - Paths - -
    -
    -

    Paths are an ordered list of files.

    -

    <v-path>

    -

    This is the equivalent of Ant 1's <path>.

    -

    <filtered-path>

    -

    A path that applies file selectors to a set of nested file sets and paths.

    -
    -
    - - - -
    - - File Selectors - -
    -
    -

    File selectors are used to select files from file sets and paths.

    -

    <and>

    -

    Combines zero or more file selectors, using AND. An empty <and> + +

    +

    Paths

    +

    Paths are an ordered list of files.

    +

    <v-path>

    +

    This is the equivalent of Ant 1's <path>.

    +

    <filtered-path>

    +

    A path that applies file selectors to a set of nested file sets and paths.

    +
    +
    +

    File Selectors

    +

    File selectors are used to select files from file sets and paths.

    +

    <and>

    +

    Combines zero or more file selectors, using AND. An empty <and> selector accepts all files.

    -

    <basename>

    -

    Selects files whose base name matches an Ant 1 style pattern, or a regular +

    <basename>

    +

    Selects files whose base name matches an Ant 1 style pattern, or a regular expression.

    -

    <condition>

    -

    Takes a set of conditions. If +

    <condition>

    +

    Takes a set of conditions. If the conditions evaluate to true, then select every file. Otherwise, select no files.

    -

    <exists>

    -

    Selects files that exist.

    -

    <is-empty-folder>

    -

    Selects empty folders, that is, folders that have no children.

    -

    <is-folder>

    -

    Selects folders, does not select regular files.

    -

    <is-file>

    -

    Selects regular files, does not select folders.

    -

    <name>

    -

    Selects files whose path in a file set matches an Ant 1 style pattern, or +

    <exists>

    +

    Selects files that exist.

    +

    <is-empty-folder>

    +

    Selects empty folders, that is, folders that have no children.

    +

    <is-folder>

    +

    Selects folders, does not select regular files.

    +

    <is-file>

    +

    Selects regular files, does not select folders.

    +

    <name>

    +

    Selects files whose path in a file set matches an Ant 1 style pattern, or a regular expression.

    -

    <not>

    -

    Selects files that are not selected by a nested file selector.

    -

    <or>

    -

    Combines zero or more file selectors, using OR. An empty <or> +

    <not>

    +

    Selects files that are not selected by a nested file selector.

    +

    <or>

    +

    Combines zero or more file selectors, using OR. An empty <or> selector accepts all files.

    -

    <url>

    -

    Selects files whose URL matches an Ant 1 style pattern, or a regular expression.

    -
    -
    -
    -
    -
-
-
-
- Copyright © 2000-2002, Apache Software Foundation -
-
+ + + + 1.1 jakarta-ant-myrmidon/site/docs/css/ns4_only.css Index: ns4_only.css =================================================================== /* simple rules suitable for Netscape 4.x only; richer rules are in tigris.css. see */ /* colors, backgrounds, borders, link indication */ body { background: #fff; color: #000; } #leftcol a:link, #leftcol a:visited { color: blue; } a:active, a:hover, #leftcol a:active, #leftcol a:hover { color: #f30; } #login a:link, #login a:visited { color: white; text-decoration: underline; } #banner a:active, #banner a:hover { color: #f90; } #leftcol a, #breadcrumbs a { text-decoration: none; } h2 .lastchild { color: #777 } .a td { background: #ddd; } .b td { background: #efefef; } .tabs td, .tabs th { background-color: #ddd; } body .app th { background-color: #bbb; } body .tabs th { background-color: #888; color: #fff; } body .app .axial th { background-color: #ddd; color: black } .tabs td { background-color: #ddd; } .alert { color: #c00; } .confirm { color: green; } .info { color: blue; } .selection { background: #ffc; } #login { color: #fff; } #helptext th { background: #cc9; } #helptext td { background: #ffc; } .tabs a { text-decoration: none; } #navcolumn div strong { color: #555; } #banner, #banner td { background: #036; color: #fff; } body #banner #login a { color: white; } /* font and text properties, exclusive of link indication, alignment, text-indent */ body, div, p, th, td, li, dl, dd { font-family: Lucida, Arial, Helvetica, sans-serif; } code, pre { font-family: 'Andale Mono', Courier, monospace; } h2, h3, h4 { font-family: Tahoma, Verdana, Helvetica, Arial, sans-serif; } .selection { font-weight: bold } #login .username { font-weight: bold; } /* box properties (exclusive of borders), positioning, alignments, list types, text-indent */ th, td { text-align: left; vertical-align: top } .right { text-align: right; } .center { text-align: center; } body .app .axial th { text-align: right; } .app .axial td th { text-align: left; } body td .stb { margin-top: 1em; text-indent: 0; } body td .mtb { margin-top: 2em; text-indent: 0; } dd { margin-bottom: .67em; } #footer { margin: 4px } #helptext { margin-top: 1em } #helptext td div { margin: .5em } .courtesylinks { margin-top: 1em; padding-top: 1em } #navcolumn div { margin-bottom: .5em; } #navcolumn div div { margin-top: .3em } #navcolumn div div { padding-left: 1em; } #banner, #banner td { vertical-align: middle; } body.docs, body.nonav { margin: 1em } 1.1 jakarta-ant-myrmidon/site/docs/css/print.css Index: print.css =================================================================== #banner, #footer, #leftcol, #breadcrumbs, .docs #toc, .docs .courtesylinks { display: none; } body.docs div.docs { margin: 0 !important; border: none !important } 1.1 jakarta-ant-myrmidon/site/docs/css/site.css Index: site.css =================================================================== div#banner { border-top: 1px solid #fff; border-bottom: 1px solid #aaa; } #banner, #banner td { background: #fff; color: #036; } #source { background-color: #fff; color: #000; border-right: 1px solid #888; border-left: 1px solid #888; border-top: 1px solid #888; border-bottom: 1px solid #888; margin-right: 7px; margin-left: 7px; margin-top: 1em; } #source pre { margin-right: 7px; margin-left: 7px; } 1.1 jakarta-ant-myrmidon/site/docs/css/tigris.css Index: tigris.css =================================================================== /* contains rules unsuitable for Netscape 4.x; simpler rules are in ns4_only.css. see */ /* colors, backgrounds, borders, link indication */ body { background: #fff; color: #000; } .app h3, .app h4, .tabs td, .tabs th, .functnbar { background-image: url(../images/nw_min.gif); background-repeat: no-repeat; } #navcolumn div div, body.docs #toc li li { background-image: url(../images/strich.gif); background-repeat: no-repeat; background-position: .5em .5em; } #navcolumn div div.heading { background-image: none; } .app h3, .app h4 { color: #fff; } .app h3 { background-color: #036; } .app h4 { background-color: #888; } .a td { background: #ddd; } .b td { background: #efefef; } table, th, td { border: none } .mtb { border-top: solid 1px #ddd; } div.colbar { background: #bbb; } #banner { border-top: 1px solid #369; border-bottom: 1px solid #003; } div#helptext th { border-bottom: 1px solid #996; border-right: 1px solid #996; } div#helptext td { border-bottom: 1px solid #cc9; border-right: 1px solid #cc9; } .tabs th { border-right: 1px solid #333; background-color: #ddd; color: #fff; } .tabs td { background-color: #999; border-bottom: 1px solid #fff; border-right: 1px solid #fff; } .tabs { border-bottom: 6px #ddd solid; } .tabs th, .tabs th a:link, .tabs th a:visited { color: #555; } .tabs td, .tabs td a:link, .tabs td a:visited { color: #fff; } .tabs a { text-decoration: none; } #navcolumn { background: #eee; border-right: 1px solid #aaa; border-bottom: 1px solid #aaa; } #breadcrumbs { border-bottom: 1px solid #aaa; background-color: #ddd } #navcolumn, #breadcrumbs { border-top: 1px solid #fff; } #rightcol div.www, #rightcol div.help { border: 1px solid #ddd; } div#navcolumn div.focus { border-top: 1px solid #aaa; border-left: 1px solid #aaa; background-color: #fff; } body.docs div.docs { background: #fff; border-left: 1px solid #ddd; border-top: 1px solid #ddd; } body.docs { background: #eee url(../images/help_logo.gif) top right no-repeat !important; } .docs h3, .docs h4 { border-top: solid 1px #000; } #alerterrormessage { background: url(../images/icon_alert.gif) top left no-repeat !important; } .functnbar { background-color: #aaa; } .functnbar2, .functnbar3 { background: #aaa url(../images/sw_min.gif) no-repeat bottom left; } .functnbar3 { background-color: #ddd; } .functnbar, .functnbar2, .functnbar3 { color: #000; } .functnbar a, .functnbar2 a, .functnbar3 a { color: #000; text-decoration: underline; } #topmodule { background: #ddd; border-top: 1px solid #fff; border-bottom: 1px solid #aaa; border-right: 1px solid #aaa; } #topmodule #issueid { border-right: 1px solid #aaa; } a:link, #navcolumn a:visited, .app a:visited, .tasknav a:visited { color: blue; } a:link.selfref, a:visited.selfref { color: #555 !important; text-decoration: none; } a:active, a:hover, #leftcol a:active, #leftcol a:hover { color: #f30 !important; } #login a:link, #login a:visited { color: white; text-decoration: underline; } #banner a:active, #banner a:hover { color: #f90 !important; } #leftcol a, #breadcrumbs a { text-decoration: none; } #apphead h2 em { color: #777; } a:link.selfref, a:visited.selfref { color: #555 !important; text-decoration: none; } .app th { background-color: #bbb; } .axial th { background-color: #ddd; color: black } .alert { color: #c00; } .confirm { color: green; } .info { color: blue; } .selection { background: #ffc; } #login { color: #fff; } #helptext th { background: #cc9; } #helptext td { background: #ffc; } #navcolumn div strong { color: #000; } #banner, #banner td { background: #036; color: #fff; } body #banner #login a { color: #fff; } h4 a:link, h4 a:visited { text-decoration: underline; color: #fff; } /* font and text properties, exclusive of link indication, alignment, text-indent */ body, th, td, input, select, textarea, h2 small { font-family: Verdana, Helvetica, Arial, sans-serif; } code, pre { font-family: 'Andale Mono', Courier, monospace; } html body, body th, body td, textarea, h2 small, .app h3, .app h4, #rightcol h3, #bodycol pre, #bodycol code { font-size: x-small; voice-family: "\"}\""; voice-family: inherit; font-size: small } html>body, html>body th, html>body td, html>body input, html>body select, html>body textarea, html>body h2 small, html>body .app h3, html>body .app h4, html>body #rightcol h3, html>body #bodycol pre, html>body #bodycol code { font-size: small } small, div#footer td, div#login, div.tabs th, div.tabs td, input, select, .paginate, .functnbar, .functnbar2, .functnbar3, #breadcrumbs td, .courtesylinks, #rightcol div.help, .colbar, .tasknav, body.docs div#toc, #leftcol { font-size: xx-small; voice-family: "\"}\""; voice-family: inherit; font-size: x-small } html>body small, html>body div#footer td, html>body div#login, html>body div.tabs th, html>body div.tabs td, html>body input, html>body select, html>body .paginate, html>body .functnbar, html>body .functnbar2, html>body .functnbar3, html>body #breadcrumbs td, html>body .courtesylinks, html>body #rightcol div.help, html>body .colbar, html>body .tasknav, html>body.docs #toc, html>body #leftcol { font-size: x-small } #bodycol h2 { font-family: Tahoma, Verdana, Helvetica, Arial, sans-serif; font-size: 1.5em; font-weight: normal; } .tabs td, .tabs th, dt, .tasknav .selfref, #login .username, .selection { font-weight: bold } h4 { font-size: 1em; } #apphead h2 em { font-style: normal; } /* box properties (exclusive of borders), positioning, alignments, list types, text-indent */ #bodycol h2 { margin-top: .3em; margin-bottom: .5em; } p, ul, ol, dl { margin-top: .67em; margin-bottom: .67em; } h3, h4 { margin-bottom: 0; } form { margin-top: 0; margin-bottom: 0; } #bodycol { padding-left: 12px; padding-right: 12px; width: 100%; voice-family: "\"}\""; voice-family: inherit; width: auto; } html>body #bodycol { width: auto; } .docs { line-height: 1.4; } .app h3, .app h4 { padding: 5px; margin-right: 2px; margin-left: 2px; } .h3 p, .h4 p, .h3 dt, .h4 dt { margin-right: 7px; margin-left: 7px; } .tasknav { margin-bottom: 1.33em } div.colbar { padding: 3px; margin: 2px 2px 0; } .tabs { margin-top: .67em; margin-right: 2px; margin-left: 2px; } #leftcol { padding-bottom: .5em; } #breadcrumbs td { vertical-align: middle; padding: 2px 8px; } .tabs td, .tabs th { padding: 3px 9px; } #rightcol div.www, #rightcol div.help { padding: 0 .5em } #navcolumn { margin: -8px -8px 0 -8px; padding: 4px; } #navcolumn div { padding-left: 5px } div#navcolumn div div { margin-top: .3em; margin-bottom: .3em; } div#navcolumn div.focus { margin-top: -.1em; padding: .2em 4px; } body.docs #toc { position: absolute; top: 15px; left: 0px; width: 120px; padding: 0 20px 0 0 } body.docs #toc ul, #toc ol { margin-left: 0; padding-left: 0; } body.docs #toc li { margin-top: 7px; padding-left: 10px; list-style-type: none; } body.docs div.docs { margin: 61px 0 0 150px; padding: 1em 2em 1em 1em !important; } .docs p+p { text-indent: 5%; margin-top: -.67em } .docs h3, .docs h4 { margin-bottom: .1em; padding-top: .3em; } #alerterrormessage { padding-left: 100px; } .functnbar, .functnbar2, .functnbar3 { padding: 5px; margin: .67em 2px; } #topmodule td { vertical-align: middle; padding: 2px 8px } body { padding: 1em; } body.composite, body.docs { margin: 0; padding: 0; } th, td { text-align: left; vertical-align: top } .right { text-align: right !important; } .center { text-align: center !important; } .axial th { text-align: right; } .app .axial td th { text-align: left; } body td .stb { margin-top: 1em; text-indent: 0; } body td .mtb { margin-top: 2em; text-indent: 0; } dd { margin-bottom: .67em; } #footer { margin: 4px } #helptext { margin-top: 1em } #helptext td div { margin: .5em } .courtesylinks { margin-top: 1em; padding-top: 1em } #navcolumn div { margin-bottom: .5em; } #navcolumn div div { margin-top: .3em } #navcolumn div div { padding-left: 1em; } #banner, #banner td { vertical-align: middle; } 1.1 jakarta-ant-myrmidon/site/docs/images/nw_min.gif <> 1.1 jakarta-ant-myrmidon/site/docs/images/strich.gif <> 1.1 jakarta-ant-myrmidon/site/docs/images/sw_min.gif <> -- To unsubscribe, e-mail: For additional commands, e-mail: