diff --git a/proposal/myrmidon/docs/buildfile.html b/proposal/myrmidon/docs/buildfile.html new file mode 100644 index 000000000..3522ff5b6 --- /dev/null +++ b/proposal/myrmidon/docs/buildfile.html @@ -0,0 +1,785 @@ + + + + + + + + + + + + + + Apache Myrmidon - User Guide + + + + + + + + + + +
+ +
Apache Myrmidon
+ + + + + + + + + + + + +
+
+
+

Myrmidon

+ +

User Guide

+ +

Extending Ant

+ +

Container Design

+
    +
+ 		+ + + +
+ + Project File + +
+
+

+The project file format is very similar to that of Ant 1. The root element of +the project file must be a <project> element. It can +take the following attributes: +

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + Attribute + + + + Description + + + + Default Value + +
+ + name + + + + The project name. + + + + The base-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. + + + + + The directory containing the project file. + +
+ + default + + + + The name of the default target. + + + + main + +
+ + version + + + + The project file 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 <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 following syntax: +project-name->target-name. Here is a simple example:

+
+ + + + + + + + + + + + + + + + + 
+
+<project version="2.0">
+    <!-- Reference another project -->
+    <projectref name="subproject" location="subproject/build.xml"/>
+
+    <!-- Use the "compile" target from the referenced project -->
+    <target name="main" depends="subproject->compile">
+        .. do some stuff ..
+    </target>
+</project>
+
+
+
+
+ + + +
+ + Library Imports + +
+
+

Library imports allow the project to import the tasks and data-types from an +antlib. An <import> element takes the following attributes:

+ + + + + + + + + + + + + + + + + + + + + +
+ + Attribute + + + + Description + + + + Default Value + +
+ + library + + + + The name of the library to import. The ext directory + of the Myrmidon distribution is searched for a library file with + the given name, and an atl extension. + + + + Required + +
+ + type + + + + The type of definition to import. Values include task, + and data-type. + + + + None + +
+ + name + + + + The name of the type to import. + + + + None + +
+

+If the type and name attributes are not provided, +the entire contents of the antlib are imported. +

+

The following example import the <my-task> task from +the my-tasks antlib.

+
+ + + + + + + + + + + + + + + + + 
+
+<project version="2.0">
+  <!-- Import task <my-task> from the 'my-tasks' antlib. -->
+  <import library="my-tasks" type="task" name="my-task"/>
+
+  <target name="main">
+     <my-task some-prop=".."/>
+  </target>
+</project>
+
+
+
+
+ + + +
+ + Implicit Tasks + +
+
+

Implicit tasks are run before any of the project's targets are run. Any task +can be used, including <property> and data-type instances. +Implicit tasks can be used to initialise the project. For example:

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

Targets have the same format as in Ant 1.x, though some of the behaviour +is different. A <target> element takes the following +attributes:

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + Attribute + + + + Description + + + + Default Value + +
+ + name + + + + The name of the target. + + + + Required + +
+ + depends + + + + A comma-separated list of targets that this target depends on. + This list can contain targets from referenced projects. + + + + None + +
+ + if + + + + Only execute this target if the specified property is set, and not + equal to false. + + + + None + +
+ + unless + + + + Do not execute this target if the specified property is set, and not + equal to false. + + + + None + +
+
+
+
+
+ + + +
+ + Tasks + +
+
+

+The following table lists some of the current set of tasks. You can find +example usages of these tasks in the sample project file +src/make/sample.ant. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ + Task + + + + Description + +
+ + 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. + +
+
+
+
+
+
+
+ Copyright © 2000-2002, Apache Software Foundation +
+
+ + + + + + + diff --git a/proposal/myrmidon/docs/classloader.html b/proposal/myrmidon/docs/classloader.html new file mode 100644 index 000000000..ca2250332 --- /dev/null +++ b/proposal/myrmidon/docs/classloader.html @@ -0,0 +1,208 @@ + + + + + + + + + + + + + + Apache Myrmidon - On ClassLoaders in Ant2 + + + + + + + + + + +
+ +
Apache Myrmidon
+ + + + + + + + + + + + +
+
+
+

Myrmidon

+ +

User Guide

+ +

Extending Ant

+ +

Container Design

+
    +
+ 		+ + + +
+ + ClassLoader Management + +
+
+

In many ways Ant2 needs to follow rules similar to a number of +different application servers with respect to ClassLoader management. +Ant2 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. +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 Ant2 is as +follows:

+
+ + + + + + + + + + + + + + + + + 
+      Bootstrap
+          |
+       System
+          |
+       Common
+      /      \
+ Container  Shared
+             /   \
+        Antlib1  Antlib2 ... 
+
+
+
    +
  • + The Bootstrap ClassLoader contains the classes and resources + provided by the Java runtime. +
    • +
  • + The System ClassLoader contains the classes that were made accessible + via the CLASSPATH environment variable. If the standard ant script was used then this + should only contain the classes that are used to bootstrap the ant runtime. ie + $ANT_HOME/bin/ant-launcher.jar +
    • +
  • + The Common ClassLoader contains the classes and resources + that are made visible to both the Container and to all the ant type librarys. This + contains all the classes that the Container uses to communicate with tasks and other + supporting infrastructure. In particular it contains the following APIs; +
      +
    • + Task API - Contains the classes that are part of the API used + to define tasks. +
      • +
    • + ProjectListener API - Contains the classes necessary to define new + ProjectListeners. +
      • +
    • + Aspect API - Contains the classes that are used to define Aspects + of the container. +
      • +
    • + Container API - Contains the interfaces that are required to communicate + with the objects deep within the container. NOTE: These interfaces + are not to be used by user tasks but are made available so that certain tasks (such + as <antcall/>) can be implemented. However they are subject to change without + notice between between different ant2 versions. +
      • +
    +

    + These classes are loaded from all the jars present in the $ANT_HOME/lib + directory. +

    +
    • +
  • + The Container ClassLoader contains all the classes and resources + that are part of the actual implementation of the Container. These classes are not + directly accessible to any Ant library or task. Some of the classes are indirectly + accessible to tasks and other elements defined in the ant librarys as they implement + interfaces defined in the Common ClassLoader. The classes that are + stored in jars in the $ANT_HOME/bin/lib/ directory. +
    • +
  • + The Shared ClassLoader contains all the classes and resources + that are shared across all of the ant librarys (unless they are als needed by the + container in which case they should be placed int the Container + ClassLoader). This ClassLoader is populated by all the jars that are contained in + the $ANT_HOME/shared/ directory. +
    • +
  • + The AntLib ClassLoaders each contain the classes and resources + that required by that particular library. Note that in some cases a single Ant + Library will manifest as a single ClassLoader containing a single jar. However + in some cases it is possible for one Ant Library to have multiple jars in its + ClassLoader or even have multiple ClassLoaders. See XXXX for further details. +
    • +
+
+
+
+
+
+
+ Copyright © 2000-2002, Apache Software Foundation +
+
+ + + + + + + diff --git a/proposal/myrmidon/docs/getinvolved.html b/proposal/myrmidon/docs/getinvolved.html new file mode 100644 index 000000000..5a39cd304 --- /dev/null +++ b/proposal/myrmidon/docs/getinvolved.html @@ -0,0 +1,110 @@ + + + + + + + + + + + + + + Apache Myrmidon - Get Involved + + + + + + + + + + +
+ +
Apache Myrmidon
+ + + + + + + + + + + + +
+
+
+

Myrmidon

+ +

User Guide

+ +

Extending Ant

+ +

Container Design

+
    +
+ 		+ + + +
+ + Get Involved + +
+
+

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

+

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 + or comments you have to the ant-dev mailing list.

+
+
+
+
+
+
+ Copyright © 2000-2002, Apache Software Foundation +
+
+ + + + + + + diff --git a/proposal/myrmidon/docs/index.html b/proposal/myrmidon/docs/index.html index b123083f4..8e0dfed50 100644 --- a/proposal/myrmidon/docs/index.html +++ b/proposal/myrmidon/docs/index.html @@ -18,10 +18,12 @@ - - + + +
+
Apache Myrmidon
@@ -35,12 +37,31 @@ +

User Guide

+ +

Extending Ant

+ +

Container Design

+
diff --git a/proposal/myrmidon/docs/librarys.html b/proposal/myrmidon/docs/librarys.html new file mode 100644 index 000000000..729f58b8c --- /dev/null +++ b/proposal/myrmidon/docs/librarys.html @@ -0,0 +1,327 @@ + + + + + + + + + + + + + + Apache Myrmidon - On Librarys in Ant2 + + + + + + + + + + +
+ +
Apache Myrmidon
+ + + + + + + + + + + + +
+
+
+

Myrmidon

+ +

User Guide

+ +

Extending Ant

+ +

Container Design

+
    +
+ 		+ + + +
+ + Library Management + +
+
+

Long ago there was identified the need for librarys 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 Ant2. The librarys (also referred to as +deployments) will be termed antlibs.

+

Ant librarys 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 +ant specific descriptors in addition to the standard Jar manifest +and other descriptor files. The archive will also contain the +.class files for all the tasks and other types the +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 librarys 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 +the Ant library needs to have access to the Trax API and an +implementation of the API. The Antlib mechanism thus uses the standard +"Optional Package" Specification to declare dependencies on other +libraries.

+

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 +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 +root directory being the base via which code and resources are loaded. So +the .class file for the Java class com.biz.tasks.Mytask +would be stored in /com/biz/tasks/Mytask.class

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

+

Ant2 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 +$JDK_HOME/docs/guide/extensions/versioning.html. Alternatively +it is available online at + +http://java.sun.com/j2se/1.3/docs/guide/extensions/versioning.html.

+

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

To make other jars available to Ant librarys 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, +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 +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 +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 +registry. This registry will be used by the library loading mechanism to locate +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 +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 +
+
+ + + + + + + diff --git a/proposal/myrmidon/docs/todo.html b/proposal/myrmidon/docs/todo.html index 6be2925da..de41c2a45 100644 --- a/proposal/myrmidon/docs/todo.html +++ b/proposal/myrmidon/docs/todo.html @@ -18,10 +18,12 @@ - - + + +
+
Apache Myrmidon
@@ -35,39 +37,35 @@ +

User Guide

+ +

Extending Ant

+ +

Container Design

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

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

-

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 -or comments you have to the ant-dev mailing list.

-
-
-
Todo List @@ -76,9 +74,9 @@ or comments you have to the ant-dev mailing 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.

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

@@ -88,10 +86,10 @@ achieve that goal. This list is currently under construction.

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

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

@@ -104,8 +102,8 @@ able to be built from scratch, without using Ant 1.x at all).

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

+ executed by Myrmidon, and allow Ant 1.x tasks to be executed unmodified + by Myrmidon.

@@ -119,21 +117,21 @@ by Myrmidon.

The VFS needs plenty of work:

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

    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.

    + <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 - FileObject, rather than java.io.File. - This process has started, in the antlib.vfile package. -
      • -
    • File Selectors: -
        -
      • Change AbstractNameFileSelector to use Ant 1 style patterns - matches, rather than Globs patterns.
        • -
      • Add 'defaultexcludes' to DefaultFileSet. Also add a - file selector implementation that matches everything except the default - excludes.
        • -
      • Add a condition -> file selector adaptor, so that arbitrary conditions - can be used to select files.
        • -
      • Add a name selector that loads patterns from a file.
        • -
      • Add more selector implementations: size and last-modified comparisons, - checksum comparison, byte-wise content comparison.
        • -
      • -
    • File Name Mappers: -
        -
      • Add a file name mapper interface, and port the current Mapper - implementations to it.
        • -
      • -
    • File Sets: -
        -
      • Add a file set implementation that uses a mapper to transform a nested - file set.
        • -
      • Add a file set implementation that provides the union of several - nested file sets (that is, a file set that merges several file sets - together).
        • -
      • Add a file set implementation that filters files that are up-to-date - WRT some other file. Alternatively, this might be better done using a - file selector.
        • -
      • -
    • Paths: -
        -
      • Add path implementations that evaluate to the system classpath, - and the ant runtime classpath. Or, more generally, combine this with - ClassLoaderManager to evaluate to the classpath of any - 'library' (e.g. system classpath, ant runtime, tools.jar, - an antlib, an installed extension, or the system classes of another JVM - for cross-compiling).
        • -
      • -
    • File Filters: -
        -
      • Add a file filter interface, and use it in the copy task.
        • -
      • Add a filter implementation that applies the token replacement that - the old copy task provides.
        • -
      • Add a filter that does cr/lf translation.
        • -
      • Add a gzip/gunzip filter.
        • -
      • Add a filter that applies character set encode/decode.
        • -
      • -
    • Copy task: -
        -
      • Implement 'preservelastmodified', 'overwrite', and 'includeemptydirs'.
        • -
      • Support a file name mapper.
        • -
      • Support file filters.
        • -
      • -
    • Implement the <move>, <delete>, - <touch> and <mkdir> tasks on top - of the VFS and the new file data-types. Might be some scope for generalising - 'touch' and 'mkdir' into a single task.
      • -
    +
  • Redesign the file data-types, replacing them with an interface-based + API, plus a set of implementations. The API should use the VFS file + FileObject, rather than java.io.File. + This process has started, in the antlib.vfile package. +
    • +
  • File Selectors: +
      +
    • Change AbstractNameFileSelector to use Ant 1 style patterns + matches, rather than Globs patterns.
      • +
    • Add 'defaultexcludes' to DefaultFileSet. Also add a + file selector implementation that matches everything except the default + excludes.
      • +
    • Add a condition -> file selector adaptor, so that arbitrary conditions + can be used to select files.
      • +
    • Add a name selector that loads patterns from a file.
      • +
    • Add more selector implementations: size and last-modified comparisons, + checksum comparison, byte-wise content comparison.
      • +
    • +
  • File Name Mappers: +
      +
    • Add a file name mapper interface, and port the current Mapper + implementations to it.
      • +
    • +
  • File Sets: +
      +
    • Add a file set implementation that uses a mapper to transform a nested + file set.
      • +
    • Add a file set implementation that provides the union of several + nested file sets (that is, a file set that merges several file sets + together).
      • +
    • Add a file set implementation that filters files that are up-to-date + WRT some other file. Alternatively, this might be better done using a + file selector.
      • +
    • +
  • Paths: +
      +
    • Add path implementations that evaluate to the system classpath, + and the ant runtime classpath. Or, more generally, combine this with + ClassLoaderManager to evaluate to the classpath of any + 'library' (e.g. system classpath, ant runtime, tools.jar, + an antlib, an installed extension, or the system classes of another JVM + for cross-compiling).
      • +
    • +
  • File Filters: +
      +
    • Add a file filter interface, and use it in the copy task.
      • +
    • Add a filter implementation that applies the token replacement that + the old copy task provides.
      • +
    • Add a filter that does cr/lf translation.
      • +
    • Add a gzip/gunzip filter.
      • +
    • Add a filter that applies character set encode/decode.
      • +
    • +
  • Copy task: +
      +
    • Implement 'preservelastmodified', 'overwrite', and 'includeemptydirs'.
      • +
    • Support a file name mapper.
      • +
    • Support file filters.
      • +
    • +
  • Implement the <move>, <delete>, + <touch> and <mkdir> tasks on top + of the VFS and the new file data-types. Might be some scope for generalising + 'touch' and 'mkdir' into a single task.
    • +
    @@ -224,26 +222,26 @@ Unfortunately, they aren't particularly extensible.

    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.

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

    +
    @@ -256,23 +254,23 @@ configuration files.

    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:

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

    +
    @@ -286,32 +284,32 @@ of filling out.

    A completely unordered list of items, big and small:

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

    User Guide

    + +

    Extending Ant

    + +

    Container Design

    +
    		@@ -256,1030 +277,6 @@ the command-line options that are available.

    - - - -
    - - Project File - -
    -
    -

    -The project file format is very similar to that of Ant 1. The root element of -the project file must be a <project> element. It can -take the following attributes: -

    - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - - Attribute - - - - Description - - - - Default Value - -
    - - name - - - - The project name. - - - - The base-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. - - - - - The directory containing the project file. - -
    - - default - - - - The name of the default target. - - - - main - -
    - - version - - - - The project file 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 <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 following syntax: -project-name->target-name. Here is a simple example:

    -
    - - - - - - - - - - - - - - - - - 
    -
-<project version="2.0">
-    <!-- Reference another project -->
-    <projectref name="subproject" location="subproject/build.xml"/>
-
-    <!-- Use the "compile" target from the referenced project -->
-    <target name="main" depends="subproject->compile">
-        .. do some stuff ..
-    </target>
-</project>
-
    -
    -
    -
    - - - -
    - - Library Imports - -
    -
    -

    Library imports allow the project to import the tasks and data-types from an -antlib. An <import> element takes the following attributes:

    - - - - - - - - - - - - - - - - - - - - - -
    - - Attribute - - - - Description - - - - Default Value - -
    - - library - - - - The name of the library to import. The ext directory - of the Myrmidon distribution is searched for a library file with - the given name, and an atl extension. - - - - Required - -
    - - type - - - - The type of definition to import. Values include task, - and data-type. - - - - None - -
    - - name - - - - The name of the type to import. - - - - None - -
    -

    -If the type and name attributes are not provided, -the entire contents of the antlib are imported. -

    -

    The following example import the <my-task> task from -the my-tasks antlib.

    -
    - - - - - - - - - - - - - - - - - 
    -
-<project version="2.0">
-  <!-- Import task <my-task> from the 'my-tasks' antlib. -->
-  <import library="my-tasks" type="task" name="my-task"/>
-
-  <target name="main">
-     <my-task some-prop=".."/>
-  </target>
-</project>
-
    -
    -
    -
    - - - -
    - - Implicit Tasks - -
    -
    -

    Implicit tasks are run before any of the project's targets are run. Any task -can be used, including <property> and data-type instances. -Implicit tasks can be used to initialise the project. For example:

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

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

    - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - - Attribute - - - - Description - - - - Default Value - -
    - - name - - - - The name of the target. - - - - Required - -
    - - depends - - - - A comma-separated list of targets that this target depends on. - This list can contain targets from referenced projects. - - - - None - -
    - - if - - - - Only execute this target if the specified property is set, and not - equal to false. - - - - None - -
    - - unless - - - - Do not execute this target if the specified property is set, and not - equal to false. - - - - None - -
    -
    -
    -
    -
    - - - -
    - - 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:

    - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - - 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
      • -
    • Absolute file names
      • -
    • Relative file names. These are resolved relative to the - project's base directory. -
      • -
    - -     -
    - - Zip Files - - - - The contents of Zip files (and Jar, War, and Ear files). - Currently, the VFS supports read-only access to Zip file contents, - and only for local Zip files. - - - - zip:// zip-file-path [!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] - -
    -

    Here are some example URLs:

    -
      -
    • build/classes
      • -
    • c:\program files\ant\bin
      • -
    • file://C:/program files/ant
      • -
    • zip://build/lib/ant.jar!/org/apache/tools
      • -
    • ftp://adam@somehost/pub/downloads
      • -
    • smb://password:adam@somehost/home/adam
      • -
    -

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

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

    -
    - - - - - - - - - - - - - - - - - 
    -
-<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 -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 -of nested paths or file sets.

    -

    An example:

    -
    - - - - - - - - - - - - - - - - - 
    -
-<v-copy todir="dist/lib">
-  <flat-fileset>
-    <v-fileset dir="build/lib">
-        <basename pattern="*.jar"/>
-    <v-fileset>
-    <v-path path="${classpath}"/>
-  </flat-fileset>
-</v-copy>
-
    -
    -
    -
    - - - -
    - - 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 -expression.

    -

    <exists>

    -

    Selects files that exist.

    -

    <is-empty>

    -

    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> -selector accepts all files.

    -

    <url>

    -

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

    -
    -
    -
    -
    - - -
    - - Tasks - -
    -
    -

    -The following table lists some of the current set of tasks. You can find -example usages of these tasks in the sample project file -src/make/sample.ant. -

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - - Task - - - - Description - -
    - - 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. - -
    -
    -
    diff --git a/proposal/myrmidon/docs/vfs.html b/proposal/myrmidon/docs/vfs.html new file mode 100644 index 000000000..f2ca67f19 --- /dev/null +++ b/proposal/myrmidon/docs/vfs.html @@ -0,0 +1,413 @@ + + + + + + + + + + + + + + Apache Myrmidon - VFS User Guide + + + + + + + + + + +
    + +
    Apache Myrmidon
    + + + + + + + + + + + + +
    +
    +
    +

    Myrmidon

    + +

    User Guide

    + +

    Extending Ant

    + +

    Container Design

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

    + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + + 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
      • +
    • Absolute file names
      • +
    • Relative file names. These are resolved relative to the + project's base directory. +
      • +
    + +     +
    + + Zip Files + + + + The contents of Zip files (and Jar, War, and Ear files). + Currently, the VFS supports read-only access to Zip file contents, + and only for local Zip files. + + + + zip:// zip-file-path [!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] + +
    +

    Here are some example URLs:

    +
      +
    • build/classes
      • +
    • c:\program files\ant\bin
      • +
    • file://C:/program files/ant
      • +
    • zip://build/lib/ant.jar!/org/apache/tools
      • +
    • ftp://adam@somehost/pub/downloads
      • +
    • smb://password:adam@somehost/home/adam
      • +
    +

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

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

    +
    + + + + + + + + + + + + + + + + + 
    +
+                <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 + 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 + of nested paths or file sets.

    +

    An example:

    +
    + + + + + + + + + + + + + + + + + 
    +
+<v-copy todir="dist/lib">
+  <flat-fileset>
+    <v-fileset dir="build/lib">
+      <basename pattern="*.jar"/>
+    <v-fileset>
+    <v-path path="${classpath}"/>
+  </flat-fileset>
+</v-copy>
+
    +
    +
    +
    + + + +
    + + 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 + expression.

    +

    <exists>

    +

    Selects files that exist.

    +

    <is-empty>

    +

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