From abda44570c0f582ed160df8f626de60178759738 Mon Sep 17 00:00:00 2001 From: adammurdoch Date: Wed, 27 Feb 2002 01:24:12 +0000 Subject: [PATCH] Some doco updates. git-svn-id: https://svn.apache.org/repos/asf/ant/core/trunk@271568 13f79535-47bb-0310-9956-ffa450edef68 --- proposal/myrmidon/docs/index.html | 639 +----------- proposal/myrmidon/docs/todo.html | 262 +++++ proposal/myrmidon/docs/user.html | 913 ++++++++++++++++++ proposal/myrmidon/src/xdocs/index.xml | 256 +---- .../src/xdocs/stylesheets/project.xml | 3 + proposal/myrmidon/src/xdocs/todo.xml | 164 ++++ proposal/myrmidon/src/xdocs/user.xml | 346 +++++++ 7 files changed, 1710 insertions(+), 873 deletions(-) create mode 100644 proposal/myrmidon/docs/todo.html create mode 100644 proposal/myrmidon/docs/user.html create mode 100644 proposal/myrmidon/src/xdocs/todo.xml create mode 100644 proposal/myrmidon/src/xdocs/user.xml diff --git a/proposal/myrmidon/docs/index.html b/proposal/myrmidon/docs/index.html index 550f5e9be..b123083f4 100644 --- a/proposal/myrmidon/docs/index.html +++ b/proposal/myrmidon/docs/index.html @@ -11,7 +11,7 @@ - Apache Myrmidon - Myrmidon + Apache Myrmidon - Introduction @@ -34,6 +34,12 @@

Myrmidon

@@ -64,8 +70,11 @@ many of the Ant 1.x tasks to the Myrmidon task engine.

- - +
+ +
+ + -
Differences to Ant 1.x @@ -90,6 +99,8 @@ Changes to the property model:
  • Properties and data type references now share the same namespace.
  • Properties are mutable.
  • Properties are scoped into global, local, and parent contexts.
    • +
  • if and unless checks now test the property + value against false, in addition to testing set/not-set.
    • @@ -120,627 +131,7 @@ tasks to do their work without depending on other tasks: - -
    - - - - - - -
    - - Building Myrmidon - -
    -
    -

    -First, you will need to fetch the Myrmidon source from CVS. The source -can be source in the proposal/myrmidon directory of the -Ant source tree. You should check out the jakarta-ant CVS -module, as described -here. -

    -

    -To build Myrmidon, use the build.xml build script. You will need -to use Ant 1.4.1 or later. The default target builds the Myrmidon distribution -into the dist directory. The distribution is a ready-to-run -installation of Myrmidon. -

    -
    -
    - - - -
    - - Running Myrmidon - -
    -
    -

    -To run Myrmidon, use one of the following methods: -

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

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

    -Run Myrmidon with the -h command-line option for a list of -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 name of the project file, with the extension removed. - -
    - - basedir - - - - The base directory for the project. - - - - 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. -

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

    -
    -
    - - - -
    - - Implicit Tasks - -
    -
    -

    Implicit tasks are run before any of the project's targets are run.

    -
    -
    - - - -
    - - Targets - -
    -
    -

    Targets are the same as Ant 1.x.

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

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

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

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

    diff --git a/proposal/myrmidon/docs/todo.html b/proposal/myrmidon/docs/todo.html new file mode 100644 index 000000000..ad6f184ae --- /dev/null +++ b/proposal/myrmidon/docs/todo.html @@ -0,0 +1,262 @@ + + + + + + + + + + + + + + Apache Myrmidon - Get Involved + + + + + + + + +
    + +
    + + + + + + + + + + + + +
    +
    +
    +

    Myrmidon

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

    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.

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

    +
    +
    + + + +
    + + Ant 1.x Compatibility + +
    +
    +

    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.

    +
    +
    + + + +
    + + Virtual File System + +
    +
    +

    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). +
      • +
    +
    +
    + + + +
    + + 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.
      • + +
    • Allow the following via config files: +
        +
      • Add (or override) the lib and ext directories.
        • +
      • Enable more than one listener, and configure the listeners from + the conents of the config file.
        • +
      • Import libraries, and set properties.
        • +
      • Execute tasks.
        • +
      • Install and configure runtime services.
        • +
      +
      • + +
    +
    +
    + + + +
    + + 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.
      • + +
    • Task writer documentation - describing things like an overview the task API, +how configuration works, task lifecycle, how to assemble an antlib, a catalog +of the runtime services, and so on.
      • + +
    • Myrmidon developer documentation - a broad outline of the architecture, +how to build, how to test, and so on. Also, this todo list needs plenty +of filling out.
      • + +
    +
    +
    + + + +
    + + Miscellaneous + +
    +
    +

    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.
      • +
    +
    +
    +
    +
    +
    +
    +
    +
    + Copyright © 2000-2002, Apache Software Foundation +
    +
    + + + + + + + diff --git a/proposal/myrmidon/docs/user.html b/proposal/myrmidon/docs/user.html new file mode 100644 index 000000000..8a05f3faa --- /dev/null +++ b/proposal/myrmidon/docs/user.html @@ -0,0 +1,913 @@ + + + + + + + + + + + + + + Apache Myrmidon - User Guide + + + + + + + + +
    + +
    + + + + + + + + + + + + +
    +
    +
    +

    Myrmidon

    + +     		+ + + +
    + + Building Myrmidon + +
    +
    +

    +First, you will need to fetch the Myrmidon source from CVS. The source +can be source in the proposal/myrmidon directory of the +Ant source tree. You should check out the jakarta-ant CVS +module, as described +here. +

    +

    +To build Myrmidon, use the build.xml build script. You will need +to use Ant 1.4.1 or later. The default target builds the Myrmidon distribution +into the dist directory. The distribution is a ready-to-run +installation of Myrmidon. +

    +
    +
    + + + +
    + + Running Myrmidon + +
    +
    +

    +To run Myrmidon, use one of the following methods: +

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

    +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 +in the current directory. A different project file can be specified using the +-f command-line option. Myrmidon executes the targets given on +the command-line, or the default target if none is given. For example, the +following executes the targets clean and build from +the 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. +

    +
    +
    + + + +
    + + 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/src/xdocs/index.xml b/proposal/myrmidon/src/xdocs/index.xml index 1e49bb175..0853c7f5b 100644 --- a/proposal/myrmidon/src/xdocs/index.xml +++ b/proposal/myrmidon/src/xdocs/index.xml @@ -2,7 +2,7 @@ Adam Murdoch -Myrmidon +Introduction @@ -31,7 +31,9 @@ many of the Ant 1.x tasks to the Myrmidon task engine.

    - + + +

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

    @@ -52,6 +54,8 @@ Changes to the property model:
  • Properties and data type references now share the same namespace.
  • Properties are mutable.
  • Properties are scoped into global, local, and parent contexts.
    • +
  • if and unless checks now test the property + value against false, in addition to testing set/not-set.
    • @@ -83,256 +87,10 @@ tasks to do their work without depending on other tasks: - - -
    - -
    - -

    -First, you will need to fetch the Myrmidon source from CVS. The source -can be source in the proposal/myrmidon directory of the -Ant source tree. You should check out the jakarta-ant CVS -module, as described -here. -

    - -

    -To build Myrmidon, use the build.xml build script. You will need -to use Ant 1.4.1 or later. The default target builds the Myrmidon distribution -into the dist directory. The distribution is a ready-to-run -installation of Myrmidon. -

    - -
    - -
    - -

    -To run Myrmidon, use one of the following methods: -

    - - - -

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

    - -

    - -

    - - - - - - - - - - - - - - - -
    VariableDescription
    JAVA_HOMEThe directory that the JDK is installed in.
    JAVACMDThe 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. -
    - -     - - - -

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

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

    +

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

    -
    - -

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

    - - - - - - - - - - - - - - - - - - - - - - - -
    AttributeDescriptionDefault Value
    nameThe project name.The name of the project file, with the extension removed.
    basedirThe base directory for the project.The directory containing the project file.
    defaultThe name of the default target.main
    versionThe 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 allow the project to import, or reference, other projects. -A <projectref> element takes the following attributes:

    - - - - - - - - - - - - - -
    AttributeDescriptionDefault Value
    nameThe name to use to identify the referenced project.Required
    locationThe 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. -

    - -     - - - -

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

    - - - - - - - - - - - - - - - - - - -
    AttributeDescriptionDefault Value
    libraryThe 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
    typeThe type of definition to import. Values include task, - and data-type.None
    nameThe name of the type to import.None
    - -

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

    - -     - - - -

    Implicit tasks are run before any of the project's targets are run.

    - -     - - - -

    Targets are the same as Ant 1.x.

    - -     - - -
    - -
    - -

    -The following table lists 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.
    - -
    diff --git a/proposal/myrmidon/src/xdocs/stylesheets/project.xml b/proposal/myrmidon/src/xdocs/stylesheets/project.xml index 53c40d299..497ca6dd1 100644 --- a/proposal/myrmidon/src/xdocs/stylesheets/project.xml +++ b/proposal/myrmidon/src/xdocs/stylesheets/project.xml @@ -5,6 +5,9 @@ + + + diff --git a/proposal/myrmidon/src/xdocs/todo.xml b/proposal/myrmidon/src/xdocs/todo.xml new file mode 100644 index 000000000..a00b7b4a7 --- /dev/null +++ b/proposal/myrmidon/src/xdocs/todo.xml @@ -0,0 +1,164 @@ + + + +Adam Murdoch +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.

    + +
    + +
    + +

    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.

    + + + +

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

    + +     + + + +

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

    + +     + + + +

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

    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.
      • + +
    • Allow the following via config files: +
        +
      • Add (or override) the lib and ext directories.
        • +
      • Enable more than one listener, and configure the listeners from + the conents of the config file.
        • +
      • Import libraries, and set properties.
        • +
      • Execute tasks.
        • +
      • Install and configure runtime services.
        • +
      +
      • + +
    + +     + + + +

    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.
      • + +
    • Task writer documentation - describing things like an overview the task API, +how configuration works, task lifecycle, how to assemble an antlib, a catalog +of the runtime services, and so on.
      • + +
    • Myrmidon developer documentation - a broad outline of the architecture, +how to build, how to test, and so on. Also, this todo list needs plenty +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/src/xdocs/user.xml b/proposal/myrmidon/src/xdocs/user.xml new file mode 100644 index 000000000..c7db268f6 --- /dev/null +++ b/proposal/myrmidon/src/xdocs/user.xml @@ -0,0 +1,346 @@ + + + +Adam Murdoch +User Guide + + + + +
    + +

    +First, you will need to fetch the Myrmidon source from CVS. The source +can be source in the proposal/myrmidon directory of the +Ant source tree. You should check out the jakarta-ant CVS +module, as described +here. +

    + +

    +To build Myrmidon, use the build.xml build script. You will need +to use Ant 1.4.1 or later. The default target builds the Myrmidon distribution +into the dist directory. The distribution is a ready-to-run +installation of Myrmidon. +

    + +
    + +
    + +

    +To run Myrmidon, use one of the following methods: +

    + + + +

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

    + +

    + +

    + + + + + + + + + + + + + + + +
    VariableDescription
    JAVA_HOMEThe directory that the JDK is installed in.
    JAVACMDThe 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. +
    + +     + + + +

    +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 +in the current directory. A different project file can be specified using the +-f command-line option. Myrmidon executes the targets given on +the command-line, or the default target if none is given. For example, the +following executes the targets clean and build from +the 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. +

    + +
    + +
    + +

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

    + + + + + + + + + + + + + + + + + + + + + + + +
    AttributeDescriptionDefault Value
    nameThe project name.The base-name of the project file, with the extension removed.
    basedirThe 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.
    defaultThe name of the default target.main
    versionThe 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 allow the project to import, or reference, other projects. +A <projectref> element takes the following attributes:

    + + + + + + + + + + + + + +
    AttributeDescriptionDefault Value
    nameThe name to use to identify the referenced project.Required
    locationThe 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:

    + + + + + + + + .. do some stuff .. + + +]]> + +     + + + +

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

    + + + + + + + + + + + + + + + + + + +
    AttributeDescriptionDefault Value
    libraryThe 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
    typeThe type of definition to import. Values include task, + and data-type.None
    nameThe 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.

    + + + + + + + + + +]]> + +     + + + +

    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:

    + + + + + + + + Set classpath to ${classpath} + + + .. do some stuff .. + + + +]]> + +     + + + +

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

    + + + + + + + + + + + + + + + + + + + + + + + +
    AttributeDescriptionDefault Value
    nameThe name of the target.Required
    dependsA comma-separated list of targets that this target depends on. + This list can contain targets from referenced projects.None
    ifOnly execute this target if the specified property is set, and not + equal to false.None
    unlessDo not execute this target if the specified property is set, and not + equal to false.None
    + +     + +
    + +
    + +

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

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