17 августа, 2007

Вступление, или несколько слов о том, зачем это надо
Устанавливаем Ant, и разрабатываем структуру проекта
Создаем файл build.xml, и учимся им пользоваться
Скачать архив с файлами проекта
Заключение

Теперь нам нужно создать файл build.xml (вообще-то название может быть любое, но тогда при вызове Ant его придётся указывать явно). Как вы уже, наверное, догадались, этот файл имеет xml формат, информации о котором более чем достаточно в Internet. Но глубокие знания этого формата в данном случае не нужны. В документации для каждой задачи приводится необходимый xml- фрагмент с описанием параметров. Вам остаётся только вставить свои значения параметров.

Любой xml- документ начинается со строки:

Code (xml)
<?xml version="1.0" encoding="windows-1251"?>

в которой указываются номер версии xml и кодировка, которая используется в файле.
Все задачи, описанные в build- файле должны находится внутри тега

Code (xml)
<project name="myProject" basedir="." default="run"> . . . </project>

который, в нашем случае, имеет 3 параметра:
name – имя проекта;
basedir – имя папки, относительно которой рассчитываются все пути в проекте (точка означает текущую папку);
default – имя задачи, которая будет выполнена по умолчанию.

Теперь перейдём непосредственно к написанию задач. Но, прежде всего, создадим несколько свойств.

Code (xml)
<property name="src" location="src"/>
<property name="buildSrc" location="build/classes"/>
<property name="buildTest" location="build/tests"/>
<property name="dist" location="dist"/>
<property name="test" location="test"/>

Свойства в Ant – это аналог переменных в программировании. Каждое свойство имеет два параметра:
name – имя свойства;
location – значение (в данном случае мы указываем название папки).
Использовать свойства очень просто, для этого нужно имя свойства написать между символами ${ и }.
Например, выражение:
myProject/${buildTest} будет преобразовано в myProject/build/classes.

Итак, свойства у нас есть, теперь перейдём к созданию задач.
В первую очередь нам нужна задача, которая создаёт папки build/classes, build/tests и dist. Назовём её init (инициализация).

Code (xml)
<target name="init">
    <mkdir dir="${buildSrc}"/>
    <mkdir dir="${buildTest}"/>
    <mkdir dir="${dist}"/>
</target>

Описание каждой задачи должно находиться внутри тега target. Этот тег имеет несколько параметров, но в данном случае мы используем только один – name, который задаёт имя задачи.
Тег mkdir – создаёт папку, а его параметр dir – указывает какую именно.

Следующая задача compile.

Code (xml)
<target name="compile" depends="init">
    <javac srcdir="${src}" destdir="${buildSrc}">
    <javac srcdir="${test}" destdir="${buildTest}">
        <classpath>
            <pathelement path="C:/junit3.8.1/junit.jar"></pathelement>
            <pathelement path="${buildSrc}"></pathelement>
        </classpath>
    </javac>
    </javac>
</target>

Здесь появляется ещё один параметр тега target, depends, в котором мы указываем имена задач, от которых зависит данная задача. То есть, в данном случае, при вызове задачи compile сначала будет выполнена задача init. Можно указать любое количество задач, от которых зависит данная, например: depends="init, task1, task2".
Следующим у нас идет тег javac. Как не трудно догадаться он вызывает компилятор javac. С параметрами тоже все просто. srcdir – папка, в которой находятся исходники (т.е. файлы с расширением java), destdir – папка, в которой будут размешены скомпилированные файлы (т.е. файлы с расширением class).
В следующей строке у нас опять тег javac, но теперь он имеет вложенный тег classpath. Зачем он нужен? В этом теге мы компилируем файлы тестов, которые написаны с использованием библиотеки JUnit (её описание можно почитать на сайте www.junit.org). Естественно нам нужно указать размещение этой библиотеки, что мы и делаем в теге pathelement, который является вложенным в тег classpath. В параметре path мы указываем размещение библиотеки. Во втором теге pathelement мы указываем путь к файлам, которые нужно протестировать. Вообще, тег classpath используется, когда нужно указать размещение различных библиотек.

Сейчас у нас уже есть скомпилированные файлы, и нам нужно упаковать их в jar- архив. Следующая наша задача как раз для этого и предназначена.

Code (xml)
<target name="dist" depends="compile" description="Create jar-file">
    <jar jarfile="${dist}/myProject.jar" basedir="${buildSrc}"
        manifest="${src}/manifest.mf"/>
</target>

Тут в теге target мы использовали еще один параметр description. Этот параметр не обязательный, он просто задает описание задачи.

Упаковку файлов в архив выполняет тег jar, в котором мы задаем три параметра:
jarfile – имя и размещение jar- файла, который мы хотим создать;
basedir – папка в которой находится скомпилированная программа;
manifest – размещение и имя манифеста (напомню, в этом файле можно задать ряд параметров, которые использоваться при запуске программы из jar- архива).

Теперь напишем задачу для запуска только что созданного jar- файла.

Code (xml)
<target name="run" depends="dist" description="Run program">
    <java jar="${dist}/myProject.jar" fork="true"/>
</target>
 
Обратите внимание, тут параметр depends имеет значение dist, потому что пока архив не создан, нам нечего запускать. Запуск программы осуществляет тег <code>java</code> (кто бы мог подумать:-)). Его параметр jar указывает, что мы хотим запустить программу из jar- архива. Параметр fork имеет значение true, это означает, что для запуска программы мы используем отдельную виртуальную машину (обязательное требование при запуске из jar- файла).
 
Следующая задача запускает наши тесты (действительно, мы же их зачем-то написали).
<pre lang="xml"><target name="test" depends="compile">
    <junit fork="yes" haltonfailure="yes">
        <classpath>
            <pathelement location="${buildTest}"/>
            <pathelement location="${buildSrc}"/>
        </classpath>
    <formatter type="plain" usefile="false" />
    <test name="tools.utils.Class1Test"/>
    <test name="tools.utils.Class2Test"/>
    </junit>
</target>

Внимание. Для того, чтобы работала эта задача нам нужно рассказать Ant где находится библиотека junit.jar. В документации к Ant описывается три различных способа, которые позволяют это сделать. Я использовал самый простой: скопировал файл junit.jar в папку ANT_HOME/lib.Тестирование выполняется в теге junit, который имеет два параметра:

fork – запускает тесты в отдельной виртуальной машине;

haltonfailure – останавливает выполнение, в случае если тест не проходит.

Теги classpath задают размещение скомпилированных тестов и классов, которые они трестируют.

Тег formatter задает параметры отображения результатов тестирования. Параметр type="plain" указывает, что результаты тестирования должны отображаться в виде обычного текста, а параметр usefile="false" обеспечивает вывод результатов на экран, а не в файл.

С помощью тегов test мы запускаем наши тесты. С помощью параметра name мы указываем название теста.Так, программу мы протестировали, теперь подготовим её исходный код к размещению в Internet. Для этого, упакуем его в обычный zip архив.

Code (xml)
<target name="packSrc">
    <zip destfile="myProject_Src.zip">
        <fileset dir="." includes="**/*.java, **/*.mf,
            **/*.xml"/>
    </zip>
</target>

Создание архива выполняется с помощью тега zip. С помощью параметра destfile задаем имя архива. А вложенный тег fileset позволяет указать перечень файлов, которые войдут в архив. Тут нужны некоторые пояснения. Во-первых, в архив нам нужно включить только те файлы, которые мы создали сами, а именно: файлы с расширениями java, mf, xml. Во-вторых, поиск файлов, которые нужно включить в проект, мы начинаем с папки myProject. Для этого мы используем параметры dir и includes. dir – задает стартовую папку, includes – указывает шаблоны выбора файлов в архив (”**” - означают любую папку, “*” - любое количество любых символов в имени файла).
И, наконец, наша последняя задача – clean. С её помощью мы можем удалить результаты работы всех предыдущих задач (останутся только исходники).

Code (xml)
<target name="clean">
    <delete dir="build"/>
    <delete dir="${dist}"/>
    <delete file="myProject_Src.zip"/>
</target>

Тут все просто. Мы используем тег delete для удаления папки и её содержимого. Параметр dir задает имя папки. В последнем теге параметр file задает имя файла.

Обратите внимание, в первом теге delete мы указываем имя папки явно (не используя параметры), что позволяет за один раз удалить папки build/classes и build/tests.
Ладно, задачи мы написали. Теперь разберемся как ими пользоваться. Для этого открываем консоль

(в Windows: Пуск->Выполнить… cmd). Переходим в папку с проектом (тут же находится наш файл build.xml), и пишем команду
ant <имя_задачи>
Например: ant compile, ant clean и т.д.

Если имя задачи не задано, будет выполнена задача по-умолчанию (та, что задана в параметре default тега project), в нашем случае run.
Теперь посмотрим весь файл целиком.

Code (xml)
<?xml version="1.0" encoding="windows-1251"?>
 
<project name="myProject" basedir="." default="run">
    <!–Устанавливаем глобальные свойства для данного проекта–>
    <property name="src" location="src"/>
    <property name="buildSrc" location="build/classes"/>
    <property name="buildTest" location="build/tests"/>
    <property name="dist"  location="dist"/>
    <property name="test" location="test"/>
 
    <!–Эта задача создает папки для размещения скомпилированных
        исходников и дистрибутива–>
    <target name="init">
        <mkdir dir="${buildSrc}"/>
        <mkdir dir="${buildTest}"/>
        <mkdir dir="${dist}"/>
    </target>
 
    <!–Эта задача выполняет компиляцию проекта–>
    <target name="compile" depends="init">
        <javac srcdir="${src}" destdir="${buildSrc}"/>
        <javac srcdir="${test}" destdir="${buildTest}">
            <classpath>
                <pathelement path="C:/junit3.8.1/junit.jar"/>
                <pathelement path="${buildSrc}"/>
            </classpath>
        </javac>
    </target>
 
    <!– Эта задача упаковывает программу в jar-архив –>
    <target name="dist" depends="compile" description="Create jar-file">
        <jar jarfile="${dist}/myProject.jar" basedir="${buildSrc}"
            manifest="${src}/manifest.mf"/>
    </target>
 
    <!– Эта задача запускает программу –>
    <target name="run" depends="dist" description="Run program">
        <java jar="${dist}/myProject.jar" fork="true"/>
    </target>
 
    <!– Эта задача упаковывает файлы с исходными кодами и ресурсами
        в zip-архив –>
    <target name="packSrc">
        <zip destfile="myProject_Src.zip">
            <fileset dir="." includes="**/*.java, **/*.mf, **/*.xml"/>
        </zip>
    </target>
 
    <!– Эта задача выполняет тестирование проекта –>
    <target name="test" depends="compile">
        <junit fork="yes" haltonfailure="yes">
            <classpath>
                <pathelement location="${buildTest}"/>
                <pathelement location="${buildSrc}"/>
            </classpath>
            <formatter type="plain" usefile="false" />
            <test name="tools.utils.Class1Test"/>
            <test name="tools.utils.Class2Test"/>
        </junit>
    </target>
 
    <!– Эта задача удаляет все, кроме исходников –>
    <target name="clean">
        <delete dir="build"/>
        <delete dir="${dist}"/>
        <delete file="myProject_Src.zip"/>
    </target>
</project>