|
Myrmidon
User Guide
Extending Ant
Container Design
|
|
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.
|
Optional Dependencies
|
Extend Myrmidons library management facilities so that optional
dependencies may be declared for a library. ie The library will still
operate in absence of such libraries but can provide further features
if these libraries are present. Most likely this will be done via a
new manifest entry "Optional-Extension-List:" that behaves similar
to "Extension-List:" except that the extensions are optional.
|
|
Mail tasks
|
Convert the ant1.x Mail tasks to myrmidon.
|
|
Self Hosting
|
Myrmidon must be able to build itself. Currently, it is built using
Ant 1.x. Ultimately, Myrmidon should be able to build itself from exactly the
same build file. To start with, however, there is no need for Myrmidon to be
able to do this. Myrmidon should also be able to be bootstrapped (that is, be
able to be built from scratch, without using Ant 1.x at all).
|
|
Validation Pass
|
Consider calling validate() on task prior to execute(). This would allow
us to have a "make -k" mode that actually did basic validation and would also
encourage task writers to do validation properly.
|
|
Paths
|
Consider allowing the user to configure the ant system by setting the
following path types.
- ant.type.path: path that is used to search for the type libraries
- ant.ext.path: path that is used to search for "Optional Packages"
or extensions.
The default search path will probably include a per-user path element,
a workspace path element and a system path elemtn that are searched in
that order. Some possible defaults;
- Unix Per-user: ${user.home}/.ant/lib, ${user.home}/.ant/ext
- Windows Per-user: ${user.home}/ant/lib, ${user.home}/ant/ext
- MacOSX Per-user: ${user.home}/Library/Ant/lib,
${user.home}/Library/Ant/ext
- Unix System-wide: /opt/ant/lib, /opt/ant/ext
- Unix System-wide: /usr/local/ant/lib, /usr/local/ant/ext
- Windows System-wide: %SYS_DRIVE%/Program Files/ant/lib,
%SYS_DRIVE%/Program Files/ant/ext
- MacOSX System-wide: /Library/Ant/lib, /Library/Ant/ant/ext
|
|
Ant 1.x Compatibility
|
The Ant1 Compatibility layer is still in early stages of development.
- Get a version of
<antcall> working.
-
Provide hooks between Ant1 references and Myrmidon properties.
May use converters for adapting Ant2 objects (like Ant2
<path> or <fileset>)
as Ant1 types.
-
Missing tests:
- Make sure properties are shared between Ant1 and Myrmidon tasks.
- Get GUMP runs going using Myrmidon.
- Add protected accessors for get/set/list properties in
Ant1 Project, to minimise the amount of code duplication in
Ant1CompatProject.
|
|
Virtual File System
|
The VFS needs plenty of work:
- Move files/folders.
- Recursive folders copy.
- 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.
- Convert files/folders into local files, for handing off
to external commands, or legacy tasks.
- Refactor the replication mechanism out of ZipFileSystemProvder,
and make more general pluggable.
- Capabilities discovery.
- Attributes and attribute schema.
- Handle file canonicalisation better (for cases like case-insensitive
file systems, symbolic links, name encoding, etc).
- 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).
|
|
File Data-Types and Tasks
|
The file data-types, such as
<fileset> and
<path>, are some of the most widely used parts of Ant 1.x.
Unfortunately, they aren't particularly extensible.
- Redesign the file data-types, replacing them with an interface-based
API, plus a set of implementations. The API should use the VFS file
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 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:
- Change FileNameMapper.mapFileName() to take vfs.FileName objects.
- Move the current mapper implementations across to antlib.
- File Sets:
- 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 as 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).
- Port across the Ant 1 file filter proposal, once it is complete.
- Copy task:
- Implement 'preservelastmodified', 'overwrite', and 'includeemptydirs'.
- Support a file name mapper.
- Support file filters.
- Detect and handle destination file name collisions.
- 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.
|
|
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.
|
|
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.
|
|
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.
- Allow service factories to be configured from the contents of the
ant-services.xml descriptor.
- 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.
- 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.
- Add an else block to the
<if> task.
- Split the
<available> condition into separate conditions
that test for the availability of a class, or a resource.
- Move
crimson.jar to
bin/lib in the distribution,
and make available to other jars via the extension mechanism.
- Change
DefaultPropertyResolver to ignore '$${'.
- Add a
--type command-line option, to allow
the project builder to be manually selected.
- Unit tests.
|
|
|