\documentclass[12pt,a4paper]{article}
\usepackage[panelright,sectionbreak,screen]{pdfscreen}
\usepackage{listings}

\margins{.65in}{.65in}{.65in}{.65in}
\screensize{8.5in}{8.5in}
\definecolor{white}{rgb}{1, 1, 1}
\backgroundcolor{white}

\newcommand{\textbftt}[1]{\textbf{\texttt{#1}}}

\title{
\begin{center}
\href{http://ant.apache.org}{\imageButton{2.2in}{!}{../ant_logo_large.jpg}}
\end{center}
\vspace{2cm}Ant Abilities for Building Large Projects
\begin{center}
\small Version V0-0-5
\end{center}
\vspace{.4cm}}
\author{Ivan Ivanov - \href{mailto:rambiusparkisanius@gmail.com}{rambiusparkisanius@gmail.com},\\
Petar Tahchiev - \href{mailto:paranoiabla@gmail.com}{paranoiabla@gmail.com}}

\begin{document}
\maketitle

\begin{slide}
\hypertarget{contents}{}
\tableofcontents
\end{slide}

\begin{slide}
\begin{center}
\begin{flushleft}
\section{Apache Ant: Introductory Words}
Apache Ant is a tool for building (compiling, packaging, testing) projects. Its main features are:
\end{flushleft}

\begin{itemize}
\item platform independence - as it is pure-Java application;
\item extensible - lots of new components can be added either by coding them in Java, or in other script languages as JavaScript, Python;
\item easy, but powerful XML syntax that is easy to master;
\item can build not only Java projects, but projects in other languages as well.
\end{itemize}

\end{center}

\end{slide}

\begin{slide}
\subsection{Structure of the build scripts}
\begin{itemize}
\item Ant uses \textbftt{build files}, which describe how an application is built, or packaged or tested. A build script is an XML file, containing the steps of the application build process.
Big projects can consist of smaller subprojects, each of which can have its own build script. Another main build script can coordinate the build processes of the subprojects.

\item Every build script contains several \textbftt{targets}, that can depend on
each other. In most cases we have target for compiling, target for packaging and target for testing, and the targets for testing and packaging naturally depends on the target for compiling.

\item Targets consist of \textbftt{tasks}, which perform some operation. For example, there is task \textbftt{<javac>}, which compiles Java files, as well as task \textbftt{<copy>}, which copies files.
\end{itemize}
\end{slide}

\begin{slide}
Here is a simple build script:
\lstset{
    basicstyle=\small,
    stringstyle=\ttfamily,
    showstringspaces=false
}
\lstinputlisting[language=Ant]{../../code/intro/build.xml}
\end{slide}

\begin{slide}
We call a target from this build script in the following manner:
\lstset{
    basicstyle=\small\ttfamily,
    showstringspaces=false
}
\begin{lstlisting}
$ ant print-date
\end{lstlisting}
The result is:
\begin{lstlisting}
Buildfile: build.xml

print-date:
     [echo] Current date is 20051006

BUILD SUCCESSFUL
Total time: 0 seconds
\end{lstlisting}
We can call ant without providing a target. In this case the default target is called, as specified in attribute \textbftt{default} of the project:
\lstset{
    basicstyle=\small\ttfamily,
    showstringspaces=false
}
\begin{lstlisting}
$ ant
Buildfile: build.xml

print-date:
     [echo] Current date is 20051006

print-time:
     [echo] Current time is 1919

all:

BUILD SUCCESSFUL
Total time: 0 seconds
\end{lstlisting}

\end{slide}

\begin{slide}
The example shows:
\begin{itemize}
\item The usage of task \textbftt{<echo>}, which print the given message. In this case parts of the message are the values of \textbftt{properties}, called
\textbftt{DSTAMP}, \textbftt{TSTAMP}. A property is name-value pair and the value can be retrieved by the name with the notation \verb+${prop_name}+; once the value of a property is set it cannot be changed;
\item The usage of task \textbftt{<tstamp>}, which sets the values of properties named \textbftt{DSTAMP}, \textbftt{TSTAMP} to the current date and time respectively;
\item It is not mandatory every task to be contained by a target. In our case task \textbftt{tstamp} is out of a target. Such tasks are always executed, 
regardless of the invoked target;
\item The dependencies of a target on other targets are specified by attribute \textbftt{depends}, for example target \textbftt{all} depends on \textbftt{print-date} and \textbftt{print-time} and they will be executed automatically when all is invoked;
\item The project can have nested tag \textbftt{<description>}, that describes its usage; targets can have attribute \textbftt{description} as well, that describes its action; this give us ability to document the script and to dump its documentation later with command
\textbftt{ant -projecthelp}.
\end{itemize}
\end{slide}

\begin{slide}
Ant has some built-in properties, i.e. they are populated automatically without being declared by the user. These are:
\begin{itemize}

\item the system properties of JVM - the same properties which we access with System.getProperties() method;
\item Ant specific properties as:
\begin{itemize}
\item \textbftt{basedir} - the absolute path of the project's basedir as defined in basedir attribute of $<$project$>$ tag;
\item \textbftt{ant.file} - the absolute path of the current build script;
\item \textbftt{ant.version} - the Ant version;
\item \textbftt{ant.project.name} - the name of the current project as specified in name attribute of the $<$project$>$ tag;
\item \textbftt{ant.java.version} - the version of the JVM, that is executing the build script.
\end{itemize}
\end{itemize}
Besides we have access to all environment variables, for example if we want to take the value of an environment variable called CATALINA\_HOME we use the following construction:
\lstset{
    basicstyle=\small,
    stringstyle=\ttfamily,
    showstringspaces=false
}
\lstinputlisting[language=Ant]{../../code/section2/env.xml}
\end{slide}

\begin{slide}
\subsection{Building and testing a HelloWorld application}
The next task is to create a HelloWorld application, that will be compiled, tested and packaged. The application consist of:
\begin{itemize}
\item Java code:

\lstset{
    basicstyle=\small,
    stringstyle=\ttfamily,
    showstringspaces=false
}
\lstinputlisting[language=Java]{../../code/HelloWorld/src/net/sourceforge/emaria/openfest/Message.java}

\lstset{
    basicstyle=\small,
    stringstyle=\ttfamily,
    showstringspaces=false
}
\lstinputlisting[language=Java]{../../code/HelloWorld/src/net/sourceforge/emaria/openfest/Main.java}
\end{itemize}
\end{slide}

\begin{slide}
\begin{itemize}
\item Unit test code:
\lstset{
    basicstyle=\small,
    stringstyle=\ttfamily,
    showstringspaces=false
}
\lstinputlisting[language=Java]{../../code/HelloWorld/tests/src/net/sourceforge/emaria/openfest/MessageTest.java}
\end{itemize}
\end{slide}

\begin{itemize}
\begin{slide}
Here is the very code of build.xml file, which:
\item compiles the application:
\lstset{
    basicstyle=\small,
    stringstyle=\ttfamily,
    showstringspaces=false
}
\lstinputlisting[language=Ant,firstline=29,lastline=35]{../../code/HelloWorld/build.xml}
\item compiles the unit tests:
\lstset{
    basicstyle=\small,
    stringstyle=\ttfamily,
    showstringspaces=false
}
\lstinputlisting[language=Ant,firstline=87,lastline=94]{../../code/HelloWorld/build.xml}
\end{slide}

\begin{slide}
\item starts the unit tests:
\lstset{
    basicstyle=\small,
    stringstyle=\ttfamily,
    showstringspaces=false
}
\lstinputlisting[language=Ant,firstline=96,lastline=121]{../../code/HelloWorld/build.xml}
\end{slide}
\end{itemize}

\begin{slide}
The examples demonstrate:\\
\begin{itemize}
\item Task \textbftt{<junit>}, that executes all unit tests, picked up by nested element \textbftt{<batchtest>};
\item Element \textbftt{formatter}, that transforms the test result in the form specified by attribute \textbftt{type};
\item Attributes \textbftt{haltonerror}, \textbftt{haltonfailure}, that specify whether the build execution will be stopped, if the tests are not successful;
\item Attributes \textbftt{failureproperty} and \textbftt{errorproperty} specify the names of the properties, that are set if the tests are not successful;
\item Task \textbftt{<junitreport>} transforms the test results from XML format to HTML format via XSLT transformation;
\item Task \textbftt{<fail>}, that stops the build as unsuccessful if a given condition is met;
\item In our example we specify the build to not stop if the tests fail, but we specify when they fail to initialize property \textbftt{test.error}, which we will help us to manually fail the build after the HTML results are generated with $<$junitreport$>$.
\end{itemize}
\end{slide}

\begin{enumerate}
\begin{slide}
\subsection{First Usage of \textbftt{<presetdef>}}
Task \textbftt{<presetdef>} creates a new definition of an already existing task, by predefining some of its attributes or elements.
A possible scenario of $<$presetdef$>$ usage is:
\item Task $<$javac$>$ by default do not generate debug information, which is needed during development for error tracing; as we saw in HelloWorld application that $<$javac$>$ is used at least twice in the build script: for compiling the very application and for unit tests compiling;
\item We can cite every time we use $<$javac$>$, to cite one and the same values of attributes \textbftt{debug}, \textbftt{debuglevel} and \textbftt{deprecation}, but this leads to literal repetition of code;
\item The solution is to use $<$presetdef$>$:
\begin{lstlisting}[language=Ant,basicstyle=\small,stringstyle=\ttfamily]
<presetdef name="javac">
    <javac debug="on" debuglevel="vars,lines,source"
        deprecation="on"/>
</presetdef>
\end{lstlisting}
In this way, every time we use $<$javac$>$, we use the above predefined version.
\item This leads to the following problem: debug information increases the size of the compiled classes, which is not desired for the official builds, and every use of $<$javac$>$ generates this information;
\end{slide}

\begin{slide}
\item The solution is to use properties instead of fixed values for the attributes. Since the value of the properties cannot be changed, all we need to do is to ensure that when we create official builds, the values of the debug properties should be set to off before everything else;
\item In our case we fulfill this by adding the target
\lstset{
    basicstyle=\small,
    stringstyle=\ttfamily,
    showstringspaces=false
}
\lstinputlisting[language=Ant,firstline=130,lastline=134]{../../code/HelloWorld/build.xml}
and we specify the target for creating the official distribution \textbftt{dist} to depend on \textbftt{-dist.init}:
\lstset{
    basicstyle=\small,
    stringstyle=\ttfamily,
    showstringspaces=false
}
\lstinputlisting[language=Ant,firstline=141,lastline=143]{../../code/HelloWorld/build.xml}
\end{slide}
\end{enumerate}

\begin{slide}
\section{Description of tasks \textbftt{<subant>}, \textbftt{<import>},
\textbftt{<macrodef>}}
These tasks, as well as $<$presetdef$>$ were introduced in Ant 1.6 to ease the create new tasks without coding them in Java, to simplify the build process in large projects and the reuse of existing build scripts.
\end{slide}

\begin{slide}
\subsection{Defining new tasks with \textbftt{<macrodef>}}
Task \textbftt{<macrodef>} defines new tasks and the input data of these new tasks task-��are specified with elements \textbftt{<attribute>} �
\textbftt{<element>}.\\
Here is a useful $<$macrodef$>$, that opens a given HTML file in the default browser, by using Linux command \textbftt{htmlview}:
\lstset{
    basicstyle=\small,
    stringstyle=\ttfamily,
    showstringspaces=false
}
\lstinputlisting[language=Ant,firstline=27,lastline=34]{../../code/section2/macrodef/browser.macrodef}
It is used as all other tasks:
\lstset{
    basicstyle=\small,
    stringstyle=\ttfamily,
    showstringspaces=false
}
\lstinputlisting[language=Ant,firstline=39,lastline=42]{../../code/section2/macrodef/browser.macrodef}
We can write a Windows version of this $<$macrodef$>$
\lstinputlisting[language=Ant,firstline=15,lastline=23]{../../code/section2/macrodef/browser.macrodef}
\end{slide}

\begin{slide}
These two version can be combined in one build script so that task $<$browse$>$ will work both on Windows and Linux:
\lstset{
    basicstyle=\small,
    stringstyle=\ttfamily,
    showstringspaces=false
}
\lstinputlisting[language=Ant,firstline=4,lastline=37]{../../code/section2/macrodef/browser.macrodef}
\end{slide}

\begin{slide}
\subsection{Reuse of the build scripts via \textbftt{<import>}}
In the example above we saw that after calling target \textbftt{browserDef}
macrodef $<$browse$>$ is defined for the corresponding operating system. It is natural to wish to use this macrodef in other build scripts.\\
One of the way to reuse Ant build scripts (or parts of them) is via XML entities. It is not related with Ant, but with the XML format of the build scripts.\\
The other way is to use task \textbftt{<import>}. An example of the syntax of this task is:
\lstset{
    basicstyle=\small,
    stringstyle=\ttfamily,
    showstringspaces=false
}
\begin{lstlisting}[language=Ant]
<import file="imported.xml" optional="true"/>,
\end{lstlisting}
where attribute \textbftt{file} points another build file, which we want to include in the current build scripts, and attribute \textbftt{optional} specifies whether the build will stop, if the imported file does not exist.
\end{slide}

\begin{slide}
The build script, containing macrodef $<$browse$>$, is imported in the following way:
\lstset{
    basicstyle=\small,
    stringstyle=\ttfamily,
    showstringspaces=false
}
\lstinputlisting[language=Ant]{../../code/section2/import/build.xml}
Target test-browser depends on target browserDef (the latter defined in the imported file), because macrodef $<$browse$>$ is created after target browserDef is executed. In this way $<$import$>$ allows the reuse of both macrodefs and targets.\\
In its foundation it works in the same way the XML entities work, i.e. $<$import$>$ adds in the importing file everything from the imported without tag $<$project$>$. The differences are that $<$import$>$ target overriding and some special property overriding.
\end{slide}

\begin{slide}
\subsection{Executing several build scripts with \textbftt{<subant>}}
Consider the following situation: let's have a given product, which consists of several projects, and building of the product requires building of the projects. In most cases, every project has its own build script and the product's build script calls the build scripts of the projects.\\
In the ancient ages before Ant 1.6 this is achieved with task \textbftt{<ant>}. Here is a piece of pseudocode that implements this idea:
\lstset{
    basicstyle=\small,
    stringstyle=\ttfamily,
    showstringspaces=false
}
\begin{lstlisting}[language=Ant]
<target name="compile-product">
    <ant target="compile" antfile="project1/build.xml"/>
    <ant target="compile" antfile="project2/build.xml"/>
    ...
    <ant target="compile" antfile="projectN/build.xml"/>
</target>
\end{lstlisting}
A convenient replacement of task $<$ant$>$ is task $<$subant$>$, which looks in the following way:
\lstset{
    basicstyle=\small,
    stringstyle=\ttfamily,
    showstringspaces=false
}
\begin{lstlisting}[language=Ant]
<target name="compile-product">
    <subant target="compile">
        <dirset dir="${basedir}">
            <include name="project*"/>    
        </dirset>
    </subant>
</target>
\end{lstlisting}
\end{slide}

\begin{slide}
\section{Demonstration of a project using \textbftt{<subant>}, \textbftt{<import>} and \textbftt{<macrodef>}}
The project, which will illustrate the ideas above is called \textbftt{antutils}. It implements some Ant extensions, separated in components, that are:
\begin{itemize}
\item FileInfo - an Ant task, that extracts information about a file - its length, if it is hidden, etc.;
\item JazzyTask - an Ant task, that spell checks files, using Java library Jazzy;
\item Input - this component allows masking of passwords entered in a text console;
\item MailAttachLogger - an Ant listener, that extends the original MailLogger and allows to attach files to the message with the build result.
\end{itemize}

\end{slide}

\begin{slide}
Each of these components should be compiled, tested and packaged. These three operations can be isolated in one common build script - \textbftt{common.xml}, that can be <import>ed in the build script of each component. If necessary the build script of a given component may predefine a property or a task from common.xml. We have also one main build script \textbftt{build.xml}, that uses <subant> to call the build scripts of the components.

The example with antutils shows the case, when the componets are independent of each other. The same technique, however, can be applied with some modifications when building projects, that depend on each other.
\end{slide}

\begin{slide}
\section{How to access the current presentation and the sample code}
You can download the presentation as an archive called \textbftt{OFP2005.tar.bz2} from\\ \small\url{http://sourceforge.net/project/showfiles.php?group_id=103509}
\normalsize

Its latest version can be downloaded from the CVS repository of SF.net via the commands:
\lstset{
    basicstyle=\small,
    stringstyle=\ttfamily,
    showstringspaces=false
}
\begin{lstlisting}[language=bash]
cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/emaria login
cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/emaria co -P \
OFP2005 
\end{lstlisting}

The source code of \textbftt{antutils} project can be downloaded again from the CVS repository of SF.net via the commands:
\lstset{
    basicstyle=\small,
    stringstyle=\ttfamily,
    showstringspaces=false
}
\begin{lstlisting}[language=bash]
cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/emaria login
cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/emaria co -P
antutils
\end{lstlisting}

When a password is requested for the CVS server, give an empty one, i.e. just press Enter.
\end{slide}

\end{document}

