antmerge 1.1

Ant http://ant.apache.org is a build tool. Generating ant build files can be hard work. In particular, I've found that its very hard to share build file code between different projects. antmerge attempts to address this problem, in a relatively straight forward way.

This manual describes how to use the antmerge tool, version 1.1.

1. Overview
2. installation
3. Usage
4. Special Tags
5. Command Line Options
6. Supplied Build files
7. Avoiding dual builds
8. The Future
9. Acknowledgements, and Contact

1. Overview

The ant tool was developed to address the needs for a cross platform independent tool. Besides, we are told, "make files are inherently evil". This is probably all true. However ant files are also fairly evil, as anyone who has spent any time writing them will know. The complexity of the system is enormous. Some of this can be overcome by using a DTD for editing ant files. At least you can get files that ant will run. However even then the semantics of the different tags is often not clear, and a large amount of trail and error is necessary. Ant also uses XML, a format which is amusing described as "human readable", but often is not.

Now all of these difficulties are compounded by the difficulty of reusing ant files within one another. Ant provides no ability to include one file within another (although you can do an lexical include by defining an XML entity), and it provides no sort of inheritance between different builds.

Antmerge attempts to address this problem. It does this in a relatively straightforward way, by merging two or more build files, the "main files" (or parent files) and a "merge file", according to a set of rules. This generates an end build file, that is something like what would happen if the merge file inherited from the main files. You can add new functionality to the main files, and you over ride existing functionality.

Antmerge will work with any ant build file, although it will work better if the main files have been written with antmerge in mind. Additionally, antmerge provides some basic, generic, build files that you can use as main files for your own projects.

2. installation

The easiest way to install antmerge on Unix is to symlink the file "antmerge.sh" into the system path. It should just then run. This is assuming java is on the system path also.

If you are using a Windows system, then you can use antmerge.bat instead. The supplied and generated build files assume that antmerge's binary `bin' directory is on the system path.

Installation can be a little more difficult if you are build straight from source, as you need to boot strap the process, for which see 2.1 Boot Installation.

2.1 Boot Installation

2.1 Boot Installation

Generally you do not need to build antmerge. If you want to, then it uses itself to generate build files, so a build should work as normal, with ant.

If you get antmerge from CVS, then you will need to bootstrap the entire process to generate ant's own build files. Further instructions are in the file building-antmerge.txt.

3. Usage

Basic usage of antmerge is very simple. You might create a file called `build-in.xml', which is the default name, with the following contents...

<project name="antmerge" default="compile"/>

You might then choose to use the default build file that antmerge provides. Simply invoking antmerge default, will result in the generation of a new `build.xml' file.

In this case `default' refers to the file `default.xml' provided with antmerge, which provides most of the basic targets that you will for a project. The `build-in.xml' provides the project name, and default targets. In this manual, the file `build-in.xml' is described as the "merge file".

It is also possible to over ride specific parts of the main file. For instance, adding

<property name="ext-base" value="../../external-dependencies"/>

will override the property definition that the `default.xml' file provides. Likewise you can override a target definition, so....

<target name="precompile"> <uptodate property="antfiles.uptodate" targetfile="${etc}/default.xml"> <srcfiles dir="${etc}"> <include name="default-in.xml"/> <include name="antmerge.xml"/> </srcfiles> </uptodate> </target>

will change the precompile target to have the following definition.

As well as being able to override properties, and targets, you can specifically override any top level (i.e. immediate child of project) tag that has an unique "id" attribute.

Finally if you want to introduce a new target, not in the main file, then you can just added it to the merge file.

You can specify more than one main file (separated by commas or plus signs: note that the Windows command interpreter treats comma as a parameter separarator: we therefore recommend using plus signs if you expect your build files to be executed on Windows systems.

If you specify multiple main files, then antmerge merges the second main file into the first as above, then the third (if present) into the the result, and so on, finally merging the merge file inot the result of merging all the mainfiles.

4. Special Tags

There is support for a number of "specials". Both of these provide support for a super like functionality. At the moment these are a little ad hoc, but they have been added to antmerge to help reduce code duplication, which is one of the points of antmerge.

Currently there are two uses of specials. Firstly within a property tag, so this example

<property name="property" value="hello"/>

overridden with this one

<property name="property" value="${super},goodbye"/>

will produce

<property name="property" value="hello,goodbye"/>

The ${super} syntax was chosen because it looks like an ant variable.

Secondly a <super/> tag is usable within a <target> tag. The <super/> tag will be replaced by the all of the children of the <target> tag in the parent that is being replaced. So

<target name="a"> <hello/> </target>

extended by

<target name="a"> <super/> <goodbye/> </target>

will produce

<target name="a"> <hello/> <goodbye/> </target>

As well as the <super/> tag, you can also use the ${super} var in the target tag, in the depends attribute.

It's worth noting that the <super/> functionality makes quite a few "hook targets" present in the bundled buildfiles (See section 6. Supplied Build files.) unnecessary. These will probably be removed in time, but are left for the moment for backward compatibility.

5. Command Line Options

`-c, --clean'

outputs a clean build file. Essentially this just copies out the main file

`-h, --help'

outputs a help message

`-i, --installation_directory'

specifies the installation directory. Normally you don't need to do this.

`-m, --mainfiles'

Specifies the main file(s), defaults to build-su.xml. The main file can be placed in either the local directory, or in user directory, which defaults to `~/.antmerge', or one of the supplied build files.

`-n, --mergefile'

Specifies the merge file, defaults to build-in.xml

`-o, --output'

Specifies the output file, defaults to build.xml

`-v, --version'

outputs the version

6. Supplied Build files

A number of build files are provided.

`antmerge' provides very little information other than tags for ensuring that the `build.xml' file is up to date, with a specified merge file. You might use this file if you do not wish to use any of the default files provided by antmerge. This functionality can be accessed by defining two properties, as this example from antmerge's own build file shows. (I like to change the default merge file name from `build-in.xml', or I end up with many identically named files open in Emacs, and I don't know which applies to which project).

This file is automatically including in the mainfiles unless the -s option is used to prevent it.

<property name="antmerge.parent" value="default"/> <property name="antmerge.infile" value="antmerge-in.xml"/>

`default' provides most of the targets that an average project would require.

`tomcat' provides some support for developing tomcat applications. This isn't finished yet, and is not fully functional

`netbeans' generate and install a netbeans module

`mygrid' probably is not of interest to most people, but I include it because the mygrid (http://www.mygrid.org.uk) project paid for the development of antmerge

7. Avoiding dual builds

One of the irritations of using antmerge is the "dual build" problem. Every time antmerge generated build files are run, ant checks to see whether the build files are out of date, and re-generates them if necessary. Ant will, however, then run on the old build file, which it has already read. So the build is effectively wrong, because its based on an old version of the build file. The `antmerge' build file prints out a message when this happens.

A simple solution to this is the `antm' file. This is a simple script that launches ant twice, rebuilding the `build.xml' the first time, and then running ant for whatever task you need the second. This means that the build will always be up to date. However, you have to run ant twice, which has obvious performance difficulties.

To use `antm', first you need to make it available from your path (I do this by symlinking it into a directory already in the path). The alter your IDE to run "antm" instead of "ant". It should work seamlessly.

This solution has only be implemented for unix like systems at the current time.

8. The Future

There is now a beta release of ant 1.6, which includes a import task. This does some of what antmerge does, namely the basic inheritance, and target over riding. It does not allow property over riding, and has something like the "super" functionality, although it's somewhat different.

For the moment I plan to keep developing antmerge because of these differences.

9. Acknowledgements, and Contact

Antmerge was written by Phillip Lord (p.lord@russet.org.uk), and Nick Sharman (Nick.Sharman@cs.man.ac.uk), while at the Department of Computer Science, University of Manchester, as part of the myGrid project. If you use antmerge please let us know what your experiences have been.

Table of Contents

1. Overview
2. installation

2.1 Boot Installation

3. Usage
4. Special Tags
5. Command Line Options
6. Supplied Build files
7. Avoiding dual builds
8. The Future
9. Acknowledgements, and Contact

Short Table of Contents

1. Overview
2. installation
3. Usage
4. Special Tags
5. Command Line Options
6. Supplied Build files
7. Avoiding dual builds
8. The Future
9. Acknowledgements, and Contact

About this document

• 1. Section One
• 1.1 Subsection One-One
• ...
• 1.2 Subsection One-Two
• 1.2.1 Subsubsection One-Two-One
• 1.2.2 Subsubsection One-Two-Two
• 1.2.3 Subsubsection One-Two-Three     <== Current Position
• 1.2.4 Subsubsection One-Two-Four
• 1.3 Subsection One-Three
• ...
• 1.4 Subsection One-Four