\input texinfo

@comment $id: $

@setfilename antmerge

@settitle antmerge 1.0

@iftex
@afourpaper
@end iftex


@ifinfo
This file documents antmerge
@end ifinfo

@titlepage
@center @titlefont{Antmerge 0.1}
@end titlepage


@node Top, Overview, (dir), (dir)

Ant @url{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 0.1.


@menu
* Overview::                    
* installation::                
* Usage::                       
* Specials::                    
* Options::                     
* buildfiles::                  
* dual-build::                  
* future::                      
* acknowledgements::            
@end menu

@node Overview, installation, Top, Top
@comment  node-name,  next,  previous,  up
@chapter 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.



@node installation, Usage, Overview, Top
@comment  node-name,  next,  previous,  up
@chapter 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 @file{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
@ref{bootinstall}.


@menu
* bootinstall::                 
@end menu

@node bootinstall,  , installation, installation
@comment  node-name,  next,  previous,  up
@section 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.

@node Usage, Specials, installation, Top
@comment  node-name,  next,  previous,  up
@chapter Usage

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

@example
<project name="antmerge" default="compile"/>
@end example

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

In this case @file{default} refers to the file @file{default.xml}
provided with antmerge, which provides most of the basic targets that
you will for a project. The @file{build-in.xml} provides the project
name, and default targets. In this manual, the file @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

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

will override the property definition that the @file{default.xml} file
provides. Likewise you can override a target definition, so....

@example
  <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>
@end example

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.

@node  Specials, Options, Usage, Top
@comment  node-name,  next,  previous,  up
@chapter Special Tags

There is support for a number of "specials". Both of these provide
support for a @code{super} like functionality. At the moment these are a
little @i{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

@example
<property name="property" value="hello"/>
@end example

overridden with this one

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

will produce

@example
<property name="property" value="hello,goodbye"/>
@end example

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

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

@example
<target name="a">
  <hello/>
</target>
@end example

extended by 

@example
<target name="a">
  <super/>
  <goodbye/>
</target>
@end example

will produce

@example
<target name="a">
  <hello/>
  <goodbye/>
</target>
@end example


It's worth noting that the @code{<super/>} functionality makes quite a
few "hook targets" present in the bundled buildfiles (@xref{buildfiles}.)
unnecessary. These will probably be removed in time, but are left for
the moment for backward compatibility.

@node Options, buildfiles, Specials, Top
@comment  node-name,  next,  previous,  up
@chapter Command Line Options

@table @option
@item -c, --clean
outputs a clean build file. Essentially this just copies out the main
file
@item -h, --help
outputs a help message
@item -i, --installation_directory
specifies the installation directory. Normally you don't need to do
this.
@item -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 @file{~/.antmerge}, or one of the supplied build files.
@item -n, --mergefile
Specifies the merge file, defaults to build-in.xml
@item -o, --output
Specifies the output file, defaults to build.xml
@item -v, --version
outputs the version
@end table

@node buildfiles, dual-build, Options, Top
@comment  node-name,  next,  previous,  up
@chapter Supplied Build files

A number of build files are provided.

@file{antmerge} provides very little information other than tags for
ensuring that the @file{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 @command{antmerge}'s
own build file shows. (I like to change the default merge file name from
@file{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
@code{-s} option is used to prevent it. 

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

@file{default} provides most of the targets that an average project
would require. 

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

@file{netbeans} generate and install a netbeans module

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

@node dual-build, future, buildfiles, Top
@comment  node-name,  next,  previous,  up
@chapter 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 @file{antmerge} build file
prints out a message when this happens. 

A simple solution to this is the @file{antm} file. This is a simple
script that launches ant twice, rebuilding the @file{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 @file{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. 


@node future, acknowledgements, dual-build, Top
@comment  node-name,  next,  previous,  up
@chapter The Future

Recently, the ant developers have started work on a ``Import'' task
which may provide much of the same functionality as antmerge. However
this will not be available for some time. Migration between antmerge and
this future import task should be possible, although it's hard to be
sure before seeing the final specification of the task

@node acknowledgements,  , future, Top
@comment  node-name,  next,  previous,  up
@chapter Acknowledgements, and Contact

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

@bye
