Java programming course (SIN

)

Pascal Perez (IN) – pascal.perez@epfl.ch 1/6

ant: a Java-based build tool “Apache Ant is a Java-based build tool. In theory, it is kind of like Make, but without Make's wrinkles. Why another build tool when there is already make, gnumake, nmake, jam, and others? Because all those tools have limitations that Ant's original author couldn't live with when developing software across multiple platforms. Make-like tools are inherently shell-based -- they evaluate a set of dependencies, then execute commands not unlike what you would issue in a shell. This means that you can easily extend these tools by using or writing any program for the OS that you are working on. However, this also means that you limit yourself to the OS, or at least the OS type such as Unix, that you are working on.” – Apache Ant developer team.
build tools

When developing a large scale project, the compilation, packaging and distribution generation can become very time consuming. Build tools offer a way of expressing a set of tasks which must be accomplished for a certain goal (e.g. documentation generation, full project compilation, etc…), and to write these in a build file. Tasks depend on other tasks so that an order of task execution can be computed automatically (removing that burden off the programmers!). For instance, suppose we want to generate a full distribution of a program, the set of tasks might be: (1) init: initialize the build process (2) compile-java { depends on init }: compile all the Java sources (3) compile-c { depends on init }: compile all the C sources (4) jar { depends on compile-java }: generate a jar file (5) zip { depends on jar, compile-java and compile-c }: generate a distribution in a zip file

From this information, it is possible to construct an oriented graph representing dependencies:

4 2 1 3 5

which has three possible ordering (1)→(3)→(2)→(4)→(5), (1)→(2)→(3)→(4)→(5) and (1)→(2)→(4)→(3)→(5).

Java programming course (SIN)

Pascal Perez (IN) – pascal.perez@epfl.ch 2/6

ant build files – xml & file layout

Ant build file, usually build.xml, is written in an XML dialect. For those who do not know XML, don’t panic, it’s very easy. An XML dialect is composed of tags (a name surrounded by ‘<’ and ‘>’). Every tag must be opened and closed: <hello></hello> or in short <hello /> the space before the ‘/>’ construct is not mandatory, but I recommend to adopt this convention. For a full explanation consult Java & XML [1]. A tag can have attributes which are of the form: <hello text="welcome" /> Tags can surround other tags or text: <hello text="welcome"> <image path="pub/welcome.png" /> </hello> And finally, comments are written: <!-- comment --> Bear in mind that this is a very short introduction to XML, for more information, consult the W3C Recommendations [2]. A complete build file is of the form <?xml version="1.0"?> <project name="Project Name" default="default target" basedir="."> <description>Project description</description> ... </project> Where the first line is called the prolog (specifying which version of XML we are using). The description is not mandatory but very strongly recommended.
ant build files – targets

A build file must contain a set of tasks to complete. In ant, these are grouped in targets which depend on one another. Targets are labeled by a name, usually have a list of dependencies and should have a description. These are written as <target name="target name" depends="comma separated list of targets’ name" description="a short description"> ... </target>

Java programming course (SIN)

Pascal Perez (IN) – pascal.perez@epfl.ch 3/6

ant build files – tasks

Ant has many built in tasks such as javac instantiation, zip archiving, jar creation (with automatic manifest generation) and so on. We are going to cover some of the more useful, for a full and detailed description consult ant’s documentation [3].
javac

Compile a Java source tree. <javac srcdir="${src}" destdir="${classes}" /> Where srcdir is the source directory and destdir is the destination directory. Many options are available.
javadoc

Generate the documentation from Java sources. <javadoc sourcepath="${src}" destdir="${javadoc}" packagenames="*" author="true" version="true" /> Where sourcepath is the source directory, destdir is the destination directory, packagenames describes (with the help of wildcards) the set of packages for which documentation will be generated, author and version specify whether the @author, respectively @version, fields’ information should be included.
jar

Generates a jar file. <jar destfile="${project}.jar" basedir="${classes}"> <manifest> <attribute name="Built-By" value="Authors" /> <attribute name="Main-Class" value="main class" /> </manifest> </jar> Note here that the jar’s manifest will be automatically generated.
mkdir

Create a directory. <mkdir dir="${classes}" />
delete

Delete a file of a directory. <delete dir="${classes}" /> <delete file="${project}.jar " />
zip

Compress a set of files and creates a zip archive. <zip destfile="${backup}/${project}-${DSTAMP}-${TSTAMP}.zip"> <zipfileset dir="${src}" prefix="src"> <include name="**/*" /> </zipfileset> </zip>

Java programming course (SIN)

Pascal Perez (IN) – pascal.perez@epfl.ch 4/6

ant build files – properties

You have probably noticed from the previous examples, the funny ${src} kind of notation. This actually represents a property named src. Properties can be used like variables in a programming language. There are defined as <property name="project" value="Project Name" /> or, if the property points to a location (directory, file) <property name="javadoc" location="doc" /> In addition, the time stamp (<tstamp />) task declares the two properties ${DSTAMP} and ${TSTAMP} which, by default, represent the day stamp in the yyyymmdd format and the time stamp in the hhmm format.
ant build files – a complete example: CirKuit 2D’s build file

CirKuit 2D [4] is a Java based game. It’s simplified build file is going to illustrate this tutorial: <?xml version="1.0"?> <project name="CirKuit 2D" default="compile" basedir="."> <description>CirKuit 2D build file</description> <!-- set global properties for this build --> <property name="project" value="CirKuit2D" /> <property name="version" value="2.0-alpha" /> <property name="src" location="src" /> <property name="classes" location="classes" /> <property name="javadoc" location="doc" /> <property name="backup" location="backup" /> <!-- Initialize the build --> <target name="init"> <tstamp /> <mkdir dir="${classes}" /> <mkdir dir="${javadoc}" /> <mkdir dir="${backup}" /> </target> <!-- Compile the java code from ${src} into ${classes} --> <target name="compile" depends="init" description="Compile the project"> <javac srcdir="${src}" destdir="${classes}" /> </target> <!-- Generate the .jar file --> <target name="jar" depends="compile" description="Generate the jar file"> <jar destfile="${project}.jar" basedir="${classes}"> <manifest> <attribute name="Built-By" value="Sven Gowal and Pascal Perez" /> <attribute name="Main-Class" value="cirkuit.CirKuit" /> </manifest> </jar> </target>

Java programming course (SIN)

Pascal Perez (IN) – pascal.perez@epfl.ch 5/6

<!-- Generate the javadoc --> <target name="doc" depends="init" description="Generating the javadoc"> <javadoc sourcepath="${src}" destdir="${javadoc}" packagenames="*" author="true" version="true" breakiterator="true"> <link href="http://java.sun.com/j2se/1.4.2/docs/api" /> </javadoc> </target> <!-- Backup .java files in a gzipped tar archive --> <target name="backup" depends="init" description="Make a backup of the source"> <zip destfile="${backup}/${project}-${DSTAMP}-${TSTAMP}.zip"> <zipfileset dir="${src}" prefix="src"> <include name="**/*" /> </zipfileset> <zipfileset dir="."> <include name="build.xml" /> </zipfileset> </zip> </target> <!-- Cleaning --> <target name="clean" description="Clean"> <delete dir="${classes}" /> </target> </project> It is then possible to type in a command line prompt: $ $ $ $ $ ant ant ant ant ant

jar doc backup and clean

Java programming course (SIN)

Pascal Perez (IN) – pascal.perez@epfl.ch 6/6

ant - installation

First of all, you must download ant from the Apache Ant website [3] or from a mirror. The binary distribution is easier to install… and the source distribution requires ant for its build process! Binary distribution is available in zip, tar.gz and tar.bz2 format. Extract all files of the archive and place them in a “reasonable” directory (further mentioned as installdir) for instance UNIX: /usr/ant, /usr/java/ant or other Windows: C:\Program Files\ant To be able to use the binaries in the command prompt, you must add to the PATH environment variable a path to installdir/bin and add a ANT_HOME variable.
bashrc

export ANT_HOME=installdir export PATH=${PATH}:${ANT_HOME}/bin
cshrc

set ANT_HOME installdir set PATH ${PATH}:${ANT_HOME}/bin Start > Parameters > Control Panel System and open the “Advanced” tab. A button label “environment variables” let’s you access the system’s environment’s variables.
Windows

bibliography

[1] [2] [3] [4]

McLaughlin, Brett. Java & XML. Trans. Alexandre Gachet. Paris: O’Reilly, 2002.

“Extensible Markup Language (XML) 1.0 (Second Edition).” 6 October 2000 <http://www.w3.org/TR/2000/REC-xml-20001006>. “Apache Ant.” 23 February 2005 <http://ant.apache.org>. “CirKuit 2D.” 21 February 2005 <http://projects.lha.ch>.