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.

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

Feature	Jar File	Download From
SMB VFS support (Samba, Windows shares)	jcifs.jar	jcifs.samba.org
FTP VFS support	netcomponents.jar	www.savarese.org

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.

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:

• <projectref>
• <import>
• Implicit tasks
• <target>

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

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.

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.