Apache Ant

Ant jest narzędziem umożliwiającym automatyzację procesów związanych

z budowaniem programów. Jego podstawowe cechy to:

●

konfiguracja zadań zapisana w formacie XML,

●

wieloplatformowość – m. in. Linux, Unix (np. Solaris and HP-UX), Windows

9x i NT, OS/2 Warp, Novell Netware 6 oraz MacOS X.

●

rozszerzalność w oparciu o klasy napisane w Javie.

Ant jest rozwijany w ramach Apache Software Foundation. Strona domowa

projektu:

http://ant.apache.org

.

Wymagania:

●

parser XML'a zgodny z JAXP,

●

JDK w wersji 1.2 lub nowszej. W przypadku posiadania samego JRE część

zadań nie będzie działać.

1

Instalacja

Ant jest rozpowszechniany jako archiwum zip. Należy je rozpakować

w wybranym katalogu. Następnie należy:

●

dodać podkatalog

bin

do ścieżki poszukiwań,

●

ustawić zmienną środowiska

ANT_HOME

,

●

ew. ustawić zmienną

JAVA_HOME

,

np. (Windows).

set ANT_HOME=c:\ant
set JAVA_HOME=c:\jdk1.2.2
set PATH=%PATH%;%ANT_HOME%\bin

Zwykle należy też zwiększyć pamięć dla konsoli poleceniem:

shell=c:\command.com c:\ /p /e:32768

2

Wykorzystanie – tag project

Informacje na temat zadań są zapisane w pliku XML. Taki plik zawiera jeden

projekt (

project

) i co najmniej jeden cel (

target

). Cel składa się z zadań

(

task

).

Projekt posiada trzy opcjonalne atrybuty:

●

name

– nazwa projektu,

●

default

– nazwa domyślnego celu wykonywanego przy budowaniu projektu,

●

basedir

– katalog od którego będą ,,liczone” nazwy ścieżek.

Opcjonalnie projekt może posiadać opis umieszczeny w elemencie

<description>

.

Przykład:

<project name="MyProject" default="dist" basedir=".">
<description>
simple example build file
</description>

...

</project>

3

Wykorzystanie – tag target

Cel (

target

) może być zależny od innych celów. Pozwala to na określenie

kolejności wykonywania celów:

<target name="A"/>
<target name="B" depends="A"/>
<target name="C" depends="B"/>
<target name="D" depends="B,C,A"/>

Ant wykonuje cele ,,zależne” w kolejności od lewej do prawej.

W powyższym przykładzie, jeśli wywołać cel

D

, zadania zostaną wykonane w

kolejności

A

,

B

,

C

,

D

.

Należy zwrócić uwagę na możliwość wywołania celu jeszcze wcześniej, jeśli był

on zależny od innego wcześniej wykonanego celu.

4

Wykorzystanie – tag target

Cel może być wywoływany warunkowo, korzystając z następującej składni:

<target name="A" if="property"/>

Jeśli wartość

property

jest ustawiona cel

A

jest aktywny. Wartość własności

property jest bez znaczenia.

<target name="A" unless="property"/>

Jeśli wartość

property

jest nieustawiona cel

A

jest aktywny.

Cel (

target

) posiada następujące atrybuty:

●

name

- nazwa

●

depends

– zależności,

●

if

– jeśli

●

unless

– ,,jeśli nie”,

●

description

– dodatkowy, krótki opis zadania.

5

Wykorzystanie – zadania

Zadanie określa konkretny kod, który ma zostać wykonany. Zadania zwykle

definiuje się tagami w następującej postaci:

<taskname attribute1="value1" attribute2="value2" ... />

Wszystkie zadania posiadają nazwę – typ zadania. Liczba atrybutów zależy od

rodzaju zadania. Zadania dzielimy na wbudowane, opcjonalne i własne.

Zadanie może mieć także przyporządkowany identyfikator:

<taskname id="taskID" ... />

Dzięki temu można odwołać się do tego zadania z innych zadań. Przykład:

<script ... >
task1.setAttr("bar");
</script>

ustawia atrybut

attr

konkretnej instancji zadania. Z poziomu programu w Javie

dostęp do zadania uzyskujemy poprzez:

project.getReference("task1")

.

6

Wykorzystanie – własności

Z projektem może być związany zbiór własności. Aby je wykorzystać należy

wpisać

${nazwawlasosci}

. Ant umożliwia dostęp do wszystkich własności

systemowych (

System.getProperties()

). Ponadto udostępnione są także:

●

basedir

– bezwzględna ścieżka dla projektu (atrybut

basedir

),

●

ant.file

– bezwzględna scieżka do opisu XML (buildfile),

●

ant.version

– wersja Ant'a

●

ant.project.name

– nazwa wykonywanego projektu,

●

ant.java.version

– wersja Wirtualnej Maszyny Javy (obecnie

dopuszczalne wartości to "1.1", "1.2", "1.3", "1.4" oraz "1.5").

7

Wykorzystanie – przykład

<project name="MyProject" default="dist" basedir=".">

<description>

przykładowy buildfile

</description>
<!-- ustawienie właściwości globalnych -->
<property name="src" location="src"/>
<property name="build" location="build"/>
<property name="dist" location="dist"/>

<target name="init">

<!-- timestamp -->
<tstamp/>
<!-- Przygotowanie katalogów dla kompilacji -->
<mkdir dir="${build}"/>

</target>

<target name="compile" depends="init"

description="compilation" >
<!-- Kompilacja źródeł z ${src} do ${build} -->
<javac srcdir="${src}" destdir="${build}"/>

</target>

8

Wykorzystanie – przykład

<target name="dist" depends="compile"

description="generowanie dystrybucji" >
<!-- Przygotowanie katalogu -->
<mkdir dir="${dist}/lib"/>
<!-- Stworzenie archiwum MyProject-${DSTAMP}.jar -->
<jar jarfile="${dist}/lib/MyProject-${DSTAMP}.jar"

basedir="${build}"/>

</target>

<target name="clean" description="porzadki" >

<!-- Kasowanie katalogów ${build} i ${dist} -->
<delete dir="${build}"/>
<delete dir="${dist}"/>

</target>

</project>

9

Ścieżki

Często wymagane jest podanie zbioru plików (np. Zmienna

CLASPATH

). Można

tu skorzystać z elementów

pathelement

,

fileset

i

dirset

.

Przykład:

<classpath>

<pathelement path="${classpath}"/>
<fileset dir="lib">

<include name="**/*.jar"/>

</fileset>
<pathelement location="classes"/>
<dirset dir="${build.dir}">

<include name="apps/**/classes"/>
<exclude name="apps/**/*Test*"/>

</dirset>
<filelist refid="third-party_jars"/>

</classpath>

10

Referencje

<project ... >
<target ... >
<rmic ...>
<classpath>
<pathelement location="lib/"/>
<pathelement path="${java.class.path}/"/>
<pathelement path="${additional.path}"/>
</classpath>
</rmic>
</target>

<target ... >
<javac ...>
<classpath>
<pathelement location="lib/"/>
<pathelement path="${java.class.path}/"/>
<pathelement path="${additional.path}"/>
</classpath>
</javac>
</target>
</project>

11

Referencje

<project ... >
<path id="project.class.path">
<pathelement location="lib/"/>
<pathelement path="${java.class.path}/"/>
<pathelement path="${additional.path}"/>
</path>

<target ... >
<rmic ...>
<classpath refid="project.class.path"/>
</rmic>
</target>

<target ... >
<javac ...>
<classpath refid="project.class.path"/>
</javac>
</target>
</project>

12

Uruchamianie Ant'a

Aby uruchomić projekt należy wcześniej dodać do

CLASSPATH

katalog

ANT_HOME/lib

. Przykładowe uruchomienie programu:

ant

uruchamia domyslny cel ze skryptu

build.xml

z bierzącego katalogu,

ant -buildfile plik.xml

uruchamia domyslny cel ze skryptu

plik.xml

z bierzącego katalogu,

Można też uruchomić Ant'a poprzez wirtualną maszynę Javy:

java -Dant.home=c:\ant org.apache.tools.ant.Main [options]

[target]

lub

java -Dant.home=c:\ant org.apache.tools.ant.launch.Launcher

[options] [target]

13

Podstawowe zadania - javac

javac

– służy do kompilacji programów. Przykład zastosowania:

<javac

srcdir

="${src}"

// katalog z plikami

.java

destdir="${build}"

// katalog na pliki

.class

includes="d1/**,d2/**"

// dodatkowe źródła do kompilacji

excludes="${src}/test/**"

// pliki wykluczone z kompilacji

fork="true"

// do kompilacji użyty zostanie program

javac

source="1.2"

// źródla zgodne z wersją 1.2 javy

target="1.2"

// klasy zgodne z wersją 1.2 javy

classpath="xyz.jar"

// zbiór klas i bibliotek z których korzysta program

/>

14

Podstawowe zadania – jar, signjar

jar

– pozwala przykotować archiwum jar. Przykład zastosowania:

<jar

destfile

="${dist}/lib/mylib.jar">

//tworzymy bibliotekę

<fileset dir="${build}/classes"

excludes="**/Test.class"

/>
<fileset dir="${src}/resources"/>

</jar>

<jar

destfile

="${dist}/lib/mylibtest.jar">

// tworzymy test

<fileset dir="${build}/classes"/>
<fileset dir="${src}/resources"/>
<manifest>

<attribute name="Main-Class" value="com.myapp.Test" />

</manifest>

</jar>

<signjar

jar

="${dist}/lib/mylibtest.jar"

// podpisujemy aplikacje

alias

="myalias"

storepass

="mypass"

/>

15

Inne zadania – izpack

izpack

– jest zadaniem zdefiniowanym w pakiecie izpack i służy do

przygotowania wersji instalacyjnej programu. Przykład zastosowania:

<taskdef name="izpack"

classpath="${lib}/standalone-compiler.jar"
classname="com.izforge.izpack.ant.IzPackTask"

/>

...

<echo message="Makes the installer using IzPack"/>
<izpack

input="${basedir}/install.xml"
output="${basedir}/myapp-install.jar"
installerType="standard"
basedir="${basedir}"

/>

16

Tworzenie nowych własnych zadań

1. Utworzenie klasy rozszerzającej

org.apache.tools.ant.Task

.

2. Stworzenie publicznego setter'a dla każdego argumentu. Przykład – dla

argumentu

file

tworzymy metodę

setFile()

.

3. Jeśli zadanie może zawierać podzadania (jako elementy) klasa musi

implementować interfejs

org.apache.tools.ant.TaskContainer

. Takie

zadanie nie może zawierać innych elementów.

4. Jeśli zadanie może posiadać dane tekstowe pomiędzy tagiem otwierającym i

zamykającym należy zaimplementowac metodę

public void setText(String)

. Własności nie są wypełniane.

5. Dla każdego elementu (np.

field

) należy zaimplementowac odpowiednią

metodę:

createField()

,

addField()

lub

addConfiguredField()

.

6. Zaimplementowac metodę

public void execute() throws

BuildException

, która realizuje zadanie.

17

Prosty przykład

package pl.domena;
import org.apache.tools.ant.BuildException;
import org.apache.tools.ant.Task;

public class MyVeryOwnTask extends Task {

private String msg;
public void execute() throws BuildException {

System.out.println(msg);

}
public void setMessage(String msg) {

this.msg = msg;

}

}

<?xml version="1.0"?>
<project name="OwnTaskExample" default="main" basedir=".">
<taskdef name="mytask" classname="pl.domena.MyVeryOwnTask"/>
<target name="main">
<mytask message="Hello World! MyVeryOwnTask works!"/>
</target>
</project>

18

Cykl życia zadania

1.

Zadanie jest tworzone w momencie parsowania dokumentu. Oznacza to, że

zadanie istnieje nawet jeśli nie zostanie wywołane.

2. Zadanie otrzymuje referencje do projektu, pozycji i celu poprzez dziedziczone

pola:

project, location

i

target

(w trakcie parsowania).

3.

Jeśli użytkownik użyje atrybutu

id

projekt zapisuje referencje do zadania.

4. Wywoływana jest metoda

init()

(w trakcie parsowania).

5. Za pomocą metod

createXXX()

lub

addXXX()

tworzone są wszystkie

elementy zadania (w trakcie parsowania).

6. Za pomocą metod

setXXX()

is ew.

setText()

są ustawiane atrybuty

(w trakcie uruchomienia).

7. Ustawiane są atrybuty podzadań lub innych elementów (w trakcie

uruchomienia).

8. Wywoływana jest metoda

execute()

. Metoda może być wywołana więcej

niż raz (w trakcie uruchomienia).

19

Konwersje typów

Typowo metody

setXXX()

używają argumentu java.lang.String. Wtedy wartość

jest przekazywana do programu (po ew. wypełnieniu własności). Jednak istnieje

możliwość użycia innych typów:

●

boolean

- zostanie przekazane

true

jeśli w pliku konfiguracyjnym było

wpisane

true

lub

yes

. W przeciwnym przypadku zostanie przekazane

false

.

●

char

lub

java.lang.Character

– pierwsza litera wyrażenia określonego w

pliku konfiguracyjnym,

●

jakikolwiek inny typ podstawowy (

int

,

short

, ...) - zostanie wykonana

odpowiednia konwersja,

●

java.io.File

– najpierw zostanie ustalone czy podana ścieżka jest

bezwzględna, jeśli nie zostanie zinterpretowana jako względna w odniesieniu do

podanej w projekcie jako

basedir

,

20

Konwersje typów

●

org.apache.tools.ant.types.Path

- dane zostaną rozdzielone z

wykorzystaniem

:

i

;

jako separatorów. Względne ścieżki zostaną uzupełnione o

basedir

.

●

java.lang.Class

- klasa o podanej nazwie zostanie załadowana i

przekazana do metody,

●

jakikolwiek inny typ posiadający konstruktor, którego jedynym argumentem

jest typ

java.lang.String

- zostanie utworzona nawa instancja obiektu i

przekazana metodzie.

●

podklasa

org.apache.tools.ant.types.EnumeratedAttribute

–

zostanie wywołana metoda

setValue()

.

21

Elementy

Chcąc umożliwić używanie nowego elementu w zadaniu o nazwie

field

typu

FieldElement

należy zdefiniować jedną z metod:

1.

public FieldElement createField()

- tworzona jest nowa instancje

FieldElement

.

2.

public void addField(FieldElement value)

– przekazywany jest

argument utworzony po wywołaniu odpowiedniego konstruktora.

3.

public void addConfiguredField(FieldElement value)

–

dodatkowo tworzone są wszystkie elementy wewnętrzne za pomocą

odpowiednich konstruktorów.

W drugim i trzecim przypadku klasa

FieldElement

musi posiadć publiczny

bezargumentowy konstruktor lub publiczny jednoargumentowy konstruktor

korzystający z parametru typu oklreślającego projekt.

22

Typy

Aby umożliwić używanie nowego typu

Type

w zadaniu należy zdefiniować

jedną z metod:

1.

public void add(Type type)

- przekazywany jest argument utworzony

po wywołaniu odpowiedniego konstruktora.

2.

public void addConfigured(Type type)

– dodatkowo tworzone są

wszystkie elementy wewnętrzne za pomocą odpowiednich konstruktorów.

23

Typy – przykład

Zadanie

MyTask

zawiera elementy typu

Condition

:

public class MyTask extends Task {

private List conditions = new ArrayList();
public void add(Condition c) {

conditions.add(c); // dodanie zadania do listy

}
public void execute() {

// wykonanie zadania

}

}

Użycie zadania

MyTask

:

<taskdef name="mytask" classname="MyTask" classpath="classes"/>
<typedef name="condition.equals"
classname="org.apache.tools.ant.taskdefs.conditions.Equals"/>
<mytask>
<condition.equals arg1="${debug}" arg2="true"/>
</mytask>

24

Typy i elementy – przykład

public class Sample {

public static class MyFileSelector implements FileSelector {

public void setAttrA(int a) {}
public void setAttrB(int b) {}
public void add(Path path) {}
public boolean isSelected(File basedir,

String filename, File file) {
return true;

}

}
interface MyInterface {

void setVerbose(boolean val);

}

public static class BuildPath extends Path {

public BuildPath(Project project) {

super(project);

}

public void add(MyInterface inter) {}
public void setUrl(String url) {}

}

25

Typy i elementy – przykład

public static class XInterface implements MyInterface {

public void setVerbose(boolean x) {...}
public void setCount(int c) {...}

}

}

<typedef name="myfileselector" classname="Sample$MyFileSelector"
classpath="classes" loaderref="classes"/>
<typedef name="buildpath" classname="Sample$BuildPath"
classpath="classes" loaderref="classes"/>
<typedef name="xinterface" classname="Sample$XInterface"
classpath="classes" loaderref="classes"/>

<copy todir="copy-classes">
<fileset dir="classes">
<myfileselector attrA="10" attrB="-10">
<buildpath path="." url="abc">
<xinterface count="4"/>
</buildpath>
</myfileselector>
</fileset>
</copy>

26

Podzadania i zdarzenia

Zadanie posiadające podzadania posiada metodę

addTask()

, która powinna

uruchomić podzadanie za pomocą metody

perform()

z pakietu

org.apache.tools.ant. Metoda perform wywołuje odpowiednie zdarzenie

BuildEvent

i wykonuje metodę

execute()

.

Zdarzenia można przechwycić w obiekcie typu Project używając odpowienich

BuildListener'ow (

org.apache.tools.antBuildListener

). Listener

przechwytuje zdarzenia: rozpoczęcie i zakończenie dla projektu, celu oraz

logowanie komunikatów. Od wersji 1.6.2 pojawił się

SubBuildListener

pozwalający obsłużyć zadania

<ant>

i

<subant>

.

UWAGA: listener nie może korzystać bezpośrednio ze strumieni systemowych

ponieważ Ant przekierowuje te strumienie do systemu obsługi zdarzeń

BuildEvent

.

27

Podsumowanie

Wykorzystanie Ant'a umożliwia automatyzaję wielu procesów związanych

z tworzeniem oprogramowania. Narzędzie to jest powszechnie używane

szczególnie przez programistów urzywających Javy. Uniwersalność

i elastyczność Anta istotnie wpłynęła na popularnośc tego rozwiązania.

28