diff --git a/proposal/myrmidon/docs/buildfile.html b/proposal/myrmidon/docs/buildfile.html index 3522ff5b6..924f8697e 100644 --- a/proposal/myrmidon/docs/buildfile.html +++ b/proposal/myrmidon/docs/buildfile.html @@ -613,153 +613,59 @@ attributes:

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

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

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

diff --git a/proposal/myrmidon/docs/task.html b/proposal/myrmidon/docs/task.html new file mode 100644 index 000000000..33b5ab27f --- /dev/null +++ b/proposal/myrmidon/docs/task.html @@ -0,0 +1,232 @@ + + + + + + + + + + + + + + Apache Myrmidon - Writing a task + + + + + + + + + + +
+ +
Apache Myrmidon
+ + + + + + + + + + + + +
+
+
+

Myrmidon

+ +

User Guide

+ +

Extending Ant

+ +

Container Design

+
    +
+ 		+ + + +
+ + Writing a Task + +
+
+

In ant1 it was very easy to write your own task. In Ant2 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 +
    2. +
  2. + For each attribute, write a setter method. The setter method + must be a public void method that takes a single argument. The name + of the method must begin with "set", followed by the attribute name, with + the first character of the name in uppercase, and the rest in lowercase. + The type of the attribute can be: +
      +
    • String
      • +
    • + Any primitive type - they are converted for you from their + String-representation in the buildfile +
      • +
    • + File - the string representation will be interpreted relative to + the project's basedir. +
      • +
    +
    3. +
  3. + For each nested element create a public void method that takes a single + argument. The name of the method must begin with "add", followed by the + attribute name, with the first character of the name in uppercase, and + the rest in lowercase. The type of the parameter is an object with a + no-arguement constructor. It is configured in exactly the same was a + task is configured (via setters and adders) and then added to the task. +
    4. +
  4. + Write a public void method named "execute" with no arguments that + throws a TaskException. This is the method called to do the + actual work of the task. +
    5. +
+ + + +
+ + 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;
+import org.apache.myrmidon.api.TaskException;
+
+public class SystemOutPrinterTask 
+    extends Task 
+{
+    private String m_message;
+
+    // The setter for the "message" attribute
+    public void setMessage( final String message )
+    {
+        m_message = message;
+    }
+
+    // The method executing the task
+    public void execute() 
+        throws TaskException 
+    {
+        System.out.println( m_message );
+    }
+}
+
+
+

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"?>
+
+<project version="2.0">
+
+  <target name="main">
+    <taskdef name="printer" 
+             classname="org.realityforge.tasks.SystemOutPrinterTask"
+             classpath="build/classes"/>
+
+    <printer message="Hello World!"/>
+  </target>
+</project>
+
+
+
+
+
+
+
+
+
+
+
+
+ Copyright © 2000-2002, Apache Software Foundation +
+
+ + + + + + + diff --git a/proposal/myrmidon/docs/todo.html b/proposal/myrmidon/docs/todo.html index 1285b8360..6e3fc0974 100644 --- a/proposal/myrmidon/docs/todo.html +++ b/proposal/myrmidon/docs/todo.html @@ -159,12 +159,15 @@
  • 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 conditions: +
  • File Name Mappers:
    • -
  • File Filters: -
    • +
  • Port across the Ant 1 file filter proposal, once it is complete.
  • Copy task: + + + +
    + + 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 + Condition.
      • +
    • Define a task using template.
      • +
    • Add some lightweight scripting tasks.
      • +
    +
    +
    @@ -309,6 +325,12 @@
  • 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.
    • +
  • Move the <http> and <socket> + conditions to an antlib. Need to resolve how these will be passed a logger.
    • +
  • Make the <uptodate> task a condition, and move to + an antlib.
    • +
  • Split up <is-set> condition into is-set and is-true conditions.
    • +
  • Allow the <if> task to take any condition implementation.
  • Unit tests.
    • diff --git a/proposal/myrmidon/docs/vfs.html b/proposal/myrmidon/docs/vfs.html index 5a3722f02..340488105 100644 --- a/proposal/myrmidon/docs/vfs.html +++ b/proposal/myrmidon/docs/vfs.html @@ -367,9 +367,13 @@

    <basename>

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

    +

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

    +

    <is-empty-folder>

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

    <is-folder>

    Selects folders, does not select regular files.

    diff --git a/proposal/myrmidon/src/xdocs/buildfile.xml b/proposal/myrmidon/src/xdocs/buildfile.xml index 785d6de02..96d1c223d 100644 --- a/proposal/myrmidon/src/xdocs/buildfile.xml +++ b/proposal/myrmidon/src/xdocs/buildfile.xml @@ -206,53 +206,74 @@ attributes:

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

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    TaskDescription
    failCauses the build to fail.
    ifConditionally executes a set of tasks.
    load-propertiesLoads a set of properties from a file.
    logWrites a log message.
    propertySets a property.
    try-catchRuns a set of tasks, with a provided error and clean-up handler.
    converter-defRegister a type converter. These are used when configuring a task - or data-type from attributes.
    type-defRegister a task or data-type.
    importRegister the contents of an antlib.
    +

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

    + +
    + +

    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.

    + +
    + diff --git a/proposal/myrmidon/src/xdocs/todo.xml b/proposal/myrmidon/src/xdocs/todo.xml index f6e451ebe..9e909ac99 100644 --- a/proposal/myrmidon/src/xdocs/todo.xml +++ b/proposal/myrmidon/src/xdocs/todo.xml @@ -74,12 +74,15 @@
  • 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 conditions: +
      +
    • Add more condition implementations that perform checks on files. + One that searches a path for a file would be useful.
      • +
  • File Name Mappers:
    • Add a file name mapper interface, and port the current Mapper @@ -105,15 +108,7 @@ 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.
      • -
    • +
  • Port across the Ant 1 file filter proposal, once it is complete.
  • Copy task:
    • Implement 'preservelastmodified', 'overwrite', and 'includeemptydirs'.
      • @@ -155,6 +150,19 @@ + +

      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 + Condition.
        • +
      • Define a task using template.
        • +
      • Add some lightweight scripting tasks.
        • +
      +       +

      Everyone loves writing documentation, and so a goal for Ant 2 is to @@ -209,6 +217,12 @@

    • 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.
      • +
    • Move the <http> and <socket> + conditions to an antlib. Need to resolve how these will be passed a logger.
      • +
    • Make the <uptodate> task a condition, and move to + an antlib.
      • +
    • Split up <is-set> condition into is-set and is-true conditions.
      • +
    • Allow the <if> task to take any condition implementation.
    • Unit tests.
    diff --git a/proposal/myrmidon/src/xdocs/vfs.xml b/proposal/myrmidon/src/xdocs/vfs.xml index 50fc5ca70..9ed6e07b0 100644 --- a/proposal/myrmidon/src/xdocs/vfs.xml +++ b/proposal/myrmidon/src/xdocs/vfs.xml @@ -163,6 +163,12 @@

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

    +

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