What appears below are my personal notes I wish were part of my long-term memory but don't always seem to fit. I strive for accuracy and clarity and appreciate feedback. If applying any of this information anywhere, confirm for youself the correctness of your work as what you see below might very well be, albeit unintentionally, incorrect or misleading. These notes are here as an easy reference for myself.

Information worthy of a more formal presentation will appear elsewhere than this "Scratch" area. - ksb

KSB's Ant Notes

Description

"Ant is a Java-based build tool. In theory, it is kind of like Make, but without Make's wrinkles."

Ant of course has wrinkles of it's own, but those apparently are better wrinkles than Make's. As a developer, I'm not too happy about needing to learn the idiosyncrasies of yet another build tool. Oh well, when in Rome...

Setup

• Make sure that ${ANT_HOME} is set such that ${ANT_HOME}/bin/ant is the main ant script.
• Add ${ANT_HOME}/bin onto your path.

Running ant

• ant -projecthelp is a handy flag that will list all targets that have a description.
• ant -v [target] to see details about what Ant is doing.
• ant -q [target] Be extra quiet, (appears to supresses stdout but not stderr).
• ant -emacs [target] output in a form that Emacs' compile mode will understand. (I suggest both -q -emacs for use in Emacs)

Writing build.xml files

• Give every main target a description so that it shows up via the -projecthelp flag.


• Make the usage target call Ant with the -projecthelp flag, then make the usage target the project default target, so that a simple ant command will display the list of main (described) targets:

  <project default="usage">
    <description>Sample Ant build.xml file</description>
  
    <target name="usage" description="Display main targets by running 'ant -projecthelp'">
      <java classname="org.apache.tools.ant.Main">
        <arg value="-projecthelp" />
      </java>
    </target>
  
  <!-- other targets -->
  
  </project>
  



• The <javac> task will by default include all of the internal Ant jars on the classpath unless you add the includeAntRuntime="no" attribute. And it will also, by default, compile without including line number information unless you add the debug="on" attribute. So a typical compile target will look like:

  <target name="compile" depends="init" description="Compile all java files">
    <javac srcdir="." includes="*.java" destdir="." includeAntRuntime="no" fork="yes" debug="on">
      <classpath refid="ccp" />
    </javac>
  </target>
  



• That <classpath refid="ccp"> means use for the classpath the path referenced by the id "ccp". That path is defined in the init target as follows:

  <target name="init">
    <tstamp/>
    <property name="Base" value="/path/to/base"/>
    <path id="ccp" description="The CLASSPATH for compiling and running">
      <pathelement location="${Base}/build/xmlsec.jar" />
      <pathelement location="${Base}/libs/xalan.jar" />
      <pathelement location="${Base}/libs/jakarta-log4j-1.2.6.jar" />
      <pathelement location="." />
    </path>
  </target>
  



• To pass a command line arg to a java program, you need to use an environment var. (Ugly, I know but I couldn't find another way.) For example, the command ant parse -DpFile=input.xml task will define the environment var pFile in build.xml so that you can use that in your target. For example the target for that command would be:

  <target name="parse" depends="compile" description="Parse the given XML file [parseme.xml]">
    <property name="pFile" value="parseme.xml"/>
    <java classname="parse" fork="yes" taskname="parse">
      <classpath refid="ccp" />
      <arg value="${pFile}"/>
    </java>
  </target>
  

  That property line is there so that the pFile variable has a resonable default value if it is not defined on the ant command line. It appears that Ant doesn't recognize that ${pFile} is intended to be a variable, and if not defined it's value becomes it's name, literally: ${pFile} (I hope I've missed something, because this is pretty annoying.)


• That taskname="parse" will give that task the given name and prefix any output from it with that name in square braces: [parse]

References

• Ant User Manual
• ant.apache.org
• Ant FAQ