build.xml

The build.xml file is to Ant what a makefile is to make.

Althoug build.xml is an xml file, there is no dtd nor a schema to validate it! The document, however, must be well formed.

Ant can be instructed to use a differently named build.xml file by using the -f option.

Sample build.xml

<project name="name of project" default="compile" basedir=".">

  <property file="build.properties"/>
  <property file="${user.home}/build.properties"/>

  <property name="app.name"      value="myapp"/>
  <property name="app.path"      value="/${app.name}"/>
  <property name="app.version"   value="0.1-dev"/>
  <property name="build.home"    value="${basedir}/build"/>
  <property name="catalina.home" value="../../../.."/> <!-- UPDATE THIS! -->
  <property name="dist.home"     value="${basedir}/dist"/>
  <property name="docs.home"     value="${basedir}/docs"/>
  <property name="manager.url"   value="http://localhost:8080/manager"/>
  <property name="src.home"      value="${basedir}/src"/>
  <property name="web.home"      value="${basedir}/web"/>

  <taskdef name="deploy"   classname="org.apache.catalina.ant.DeployTask"/>
  <taskdef name="list"     classname="org.apache.catalina.ant.ListTask"/>
  <taskdef name="reload"   classname="org.apache.catalina.ant.ReloadTask"/>
  <taskdef name="undeploy" classname="org.apache.catalina.ant.UndeployTask"/>
  
  <property name="compile.debug"       value="true"/>
  <property name="compile.deprecation" value="false"/>
  <property name="compile.optimize"    value="true"/>

  <property name="compile.debug"       value="true"/>
  <property name="compile.deprecation" value="false"/>
  <property name="compile.optimize"    value="true"/>

  <path id="compile.classpath">

    <pathelement location="${catalina.home}/common/classes"/>

    <fileset dir="${catalina.home}/common/endorsed">
      <include name="*.jar"/>
    </fileset>

    <fileset dir="${catalina.home}/common/lib">
      <include name="*.jar"/>
    </fileset>

    <pathelement location="${catalina.home}/shared/classes"/>

    <fileset dir="${catalina.home}/shared/lib">
      <include name="*.jar"/>
    </fileset>

  </path>

  <target name="all" depends="clean,compile"
   description="Clean build and dist directories, then compile"/>

  <target name="clean"
   description="Delete old build and dist directories">
    <delete dir="${build.home}"/>
    <delete dir="${dist.home}"/>
  </target>

  <target name="compile" depends="prepare"
   description="Compile Java sources">

    <!-- Compile Java classes as necessary -->
    <mkdir    dir="${build.home}/WEB-INF/classes"/>
    <javac srcdir="${src.home}"
          destdir="${build.home}/WEB-INF/classes"
            debug="${compile.debug}"
      deprecation="${compile.deprecation}"
         optimize="${compile.optimize}">
        <classpath refid="compile.classpath"/>
    </javac>

    <!-- Copy application resources -->
    <copy  todir="${build.home}/WEB-INF/classes">
      <fileset dir="${src.home}" excludes="**/*.java"/>
    </copy>
  </target>

  <target name="dist" depends="compile,javadoc"
   description="Create binary distribution">

    <!-- Copy documentation subdirectories -->
    <mkdir   dir="${dist.home}/docs"/>
    <copy    todir="${dist.home}/docs">
      <fileset dir="${docs.home}"/>
    </copy>

    <!-- Create application JAR file -->
    <jar jarfile="${dist.home}/${app.name}-${app.version}.war"
         basedir="${build.home}"/>

    <!-- Copy additional files to ${dist.home} as necessary -->

  </target>

  <target name="install" depends="compile"
   description="Install application to servlet container">

    <deploy url="${manager.url}"
       username="${manager.username}"
       password="${manager.password}"
           path="${app.path}"
       localWar="file://${build.home}"/>

  </target>

  <target name="javadoc" depends="compile"
   description="Create Javadoc API documentation">

    <mkdir          dir="${dist.home}/docs/api"/>
    <javadoc sourcepath="${src.home}"
                destdir="${dist.home}/docs/api"
           packagenames="*">
      <classpath refid="compile.classpath"/>
    </javadoc>

  </target>

  <target name="list"
   description="List installed applications on servlet container">

    <list    url="${manager.url}"
        username="${manager.username}"
        password="${manager.password}"/>

  </target>

  <target name="prepare">

    <!-- Create build directories as needed -->
    <mkdir  dir="${build.home}"/>
    <mkdir  dir="${build.home}/WEB-INF"/>
    <mkdir  dir="${build.home}/WEB-INF/classes"/>

    <!-- Copy static content of this web application -->
    <copy todir="${build.home}">
      <fileset dir="${web.home}"/>
    </copy>

    <!-- Copy external dependencies as required -->
    <!-- *** CUSTOMIZE HERE AS REQUIRED BY YOUR APPLICATION *** -->
    <mkdir  dir="${build.home}/WEB-INF/lib"/>
<!--
    <copy todir="${build.home}/WEB-INF/lib" file="${foo.jar}"/>
-->

    <!-- Copy static files from external dependencies as needed -->
    <!-- *** CUSTOMIZE HERE AS REQUIRED BY YOUR APPLICATION *** -->

  </target>

</project>

Tags

A build.xml file can contain the following tags:

project

The project tag is the root element of the build.xml file.

It can contain the following attributes:

name

This attribute names the project.

default

This attribute specifies the default target. That is, the target to be run if none is specified on the command line.

basedir

This attribute specifies the base directory that is used to construct absolute paths from relative paths.

basedir behaves like a property: it can be overriden on the command line:

ant -Dbasedir=c:\foo\bar

target

A target names a set of tasks that are executed when this target is run. A default target can be specified with the default attribute in the project element.

The following attributes can be specified:

name

Specifies the name of this target. In order to invoke a target, use this name on the command line:

ant name-of-target

This attribute is required.

default

???

if

The name of a property that must be set in order for a target to be executed. Consider the following file:

target_if

<project default="print_something">

  <target name="print_something" if="print_it">
    <echo message="print_it was set" />
  </target>
</project>

Just anting it:

ant -f target_if.xml

prints

Buildfile: target_if.xml

print_something:

BUILD SUCCESSFUL
Total time: 0 seconds

If, however, the property print_it is set:

ant -f target_if.xml -Dprint_it=1

Buildfile: target_if.xml

print_something:
     [echo] print_it was set

BUILD SUCCESSFUL
Total time: 0 seconds

depends

Lists (comma seperated) all targets on which this target depends. That is, it first makes all other targets (if necessary) before it makes this target.

description

????

javac

Invokes the java compiler (javac).

The following attributes can be specified:

srcdir

destdir

debug

deprecation

optimize

classpath

This element can occur within <javac> or <javadoc>

The following attributes can be specified:

refid

property

file

name

value

path

id

pathelement

location

fileset

dir

copy

todir

mkdir

dir

echo

Prints a message to the console.

message

Specifies the message to be printed.

echo.xml

<project default="print_something">
  <target name="print_something">
    <echo message="Here's a secret message" />
  </target>
</project>

If this file (named echo.xml) is invoked with Ant, it prints:

Buildfile: echo.xml

print_something:
     [echo] Here's a secret message

BUILD SUCCESSFUL
Total time: 0 seconds

A property's value can be echoed by placing like so:

echo_property.xml

<project default="print_something">

  <property name="foo" value="bar"/>

  <target name="print_something">
    <echo message="The value of foo is ${foo}" />
  </target>
</project>

Now, ant'ing this file:

ant -f echo_property.xml

Buildfile: echo_property.xml

print_something:
     [echo] The value of foo is bar

BUILD SUCCESSFUL
Total time: 0 seconds

echo_property.xml can be used to demonstrate the effect of ant's -D option:

ant -f echo_property.xml -Dfoo="overriding bar's default"

Buildfile: echo_property.xml

print_something:
     [echo] The value of foo is overriding bar's default

BUILD SUCCESSFUL
Total time: 0 seconds

javadoc

The following attributes can be specified:

sourcepath

destdir

packagenames

taskdef

name

????

classname

????