This is antmerge, produced by makeinfo version 4.0b from antmerge.texi.

   This file documents antmerge


File: antmerge,  Node: Top,  Next: Overview,  Prev: (dir),  Up: (dir)

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

* Menu:

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


File: antmerge,  Node: Overview,  Next: installation,  Prev: Top,  Up: Top

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.


File: antmerge,  Node: installation,  Next: Usage,  Prev: Overview,  Up: Top

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 *Note
bootinstall::.

* Menu:

* bootinstall::


File: antmerge,  Node: bootinstall,  Prev: installation,  Up: installation

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.


File: antmerge,  Node: Usage,  Next: Specials,  Prev: installation,  Up: Top

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.


File: antmerge,  Node: Specials,  Next: Options,  Prev: Usage,  Up: Top

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>

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


File: antmerge,  Node: Options,  Next: buildfiles,  Prev: Specials,  Up: Top

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


File: antmerge,  Node: buildfiles,  Next: dual-build,  Prev: Options,  Up: Top

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


File: antmerge,  Node: dual-build,  Next: future,  Prev: buildfiles,  Up: Top

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.


File: antmerge,  Node: future,  Next: acknowledgements,  Prev: dual-build,  Up: Top

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


File: antmerge,  Node: acknowledgements,  Prev: future,  Up: Top

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 (http://www.cs.man.ac.uk), University of Manchester,
as part of the myGrid (http://www.mygrid.org.uk) project. If you use
antmerge please let us know what your experiences have been.



Tag Table:
Node: Top106
Node: Overview658
Node: installation2388
Node: bootinstall3051
Node: Usage3500
Node: Specials5757
Node: Options7181
Node: buildfiles7992
Node: dual-build9356
Node: future10569
Node: acknowledgements11016

End Tag Table
