Fiches / Articles

Cadre Fonctionnel

Utilisation d’un outil de déploiement

Cadre Technique

Ant

Identifiant 

SYS_ANT_01

Référent technique 


Version 

1.0

Auteur 

Alexandre Brillant

Date

04/01

Source

http://jakarta.apache.org

Ant permet :

  1. Décompresser le package ant dans un répertoire

  2. Mettre à jour la variable d'environnement ANT_HOME avec le répertoire d'installation

  3. Mettre à jour la variable d'environnement PATH pour contenir %ANT_HOME%\bin.

  4. Tester la commande "ant".

Cette dernière commande nécessite le fichier 'build.xml' pour fonctionner.

Répertoire

Rôle

bin

scripts d'utilisation de ant

doc

manuel

lib

ant.jar, jaxp.jar et parser.jar

La commande ant est suivie d'un nom de cible correspondant à une liste d'opérations à exécuter.

Un script 'build.xml' est composé :

Exemple de gestionnaire build.xml :



<?xml version="1.0" encoding="ISO-8859-1"?>




<!-- 


Exemple d'utilisation de Ant :

L'action par défaut "dist" compile les

sources présents dans le répertoire courant

"src" et déposent les classes dans le répertoire

"build". Elle construit ensuite un jar qu'elle

dépose dans le répertoire "dist/lib".

-->

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

<!-- Définition des propriétés utilisables
par toutes les taches -->

<property name="src" value="src"/>

<property name="build" value="build"/>

<property name="dist" value="dist"/>




<!-- Création d'un répertoire pour les .class -->

<target name="init">

<tstamp/>

<mkdir dir="${build}"/>

</target>




<!-- Compilation des sources présents dans src -->

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

<javac srcdir="${src}" destdir="${build}"/>

</target>




<!-- Création d'un jar pour une distribution, grâce à
la tâche tstamp, DSTAMP contient l'année, le mois et le
jour courant -->

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

<mkdir dir="${dist}/lib"/>

<jar jarfile="${dist}/lib/Test-${DSTAMP}.jar"
basedir="${build}"/>

</target>




<!-- Effacer les répertoires contenant les .class et les
distributions -->

<target name="clean">

<delete dir="${build}"/>

<delete dir="${dist}"/>

</target>

</project>

Cet exemple offre 4 types d'actions :

La cible par défaut est dist qui fait intervenir les tâches init et compile.

ant

ant clean

ant init

ant compile

ant dist

Il met en évidence la relation entre les principaux intervenants:

Ce fichier peut aussi être étendu pour prendre en compte un classpath plus sophistiqué.

La balise project peut contenir une balise path comprenant tous les répertoires utiles pour la compilation.

Exemple de changement du classpath :



<?xml version="1.0" encoding="ISO-8859-1"?>




<!-- 


Exemple d'utilisation de Ant :

L'action par défaut "dist" compile les sources
présents dans le répertoire courant

"src" et déposent les classes dans le répertoire
"build". Elle construit ensuite un jar qu'elle dépose
dans le répertoire "dist/lib".

-->

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

<!-- Définition des propriétés utilisables
par toutes les taches -->

<property name="src" value="src"/>

<property name="build" value="build"/>

<property name="dist" value="dist"/>




<path id="project.class.path">

<pathelement location="lib-ext/"/>

</path>




<!-- Création d'un répertoire pour les .class -->

<target name="init">

<tstamp/>

<mkdir dir="${build}"/>

</target>




<!-- Compilation des sources présents dans src -->

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

<javac srcdir="${src}" destdir="${build}">

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

</javac>

</target>




<!-- Création d'un jar pour une distribution, grace à
la tache tstamp, DSTAMP contient l'année, le mois et le jour
courant -->

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

<mkdir dir="${dist}/lib"/>

<jar jarfile="${dist}/lib/Test-${DSTAMP}.jar"
basedir="${build}"/>

</target>




<!-- Effacer les répertoires contenant les .class et les
distributions -->

<target name="clean">

<delete dir="${build}"/>

<delete dir="${dist}"/>

</target>


</project>

Dans l'exemple ci-dessus, le tag path fait référence par rapport au répertoire courant au répertoire lib-ext. Son identifiant project.class.path est ensuite exploité lors de la cible compile par la tâche javac.

Principales tâches :

Les répertoires et fichiers utilisés dans la syntaxe de certaines commandes peuvent être simplifiés par certains masques (**,*,?,…).

Exemple : com/**/hexadev/*.java correspondra à tous les répertoires contenus dans com et contenant un répertoire hexadev incluant des sources java.

Cela peut être exploité par le tag Fileset supporté par certaines tâches (copy, javac, …)

Exemple :


<copy todir="${dist}>

 <fileset dir="${src}>

  <include name="com/**/hexadev/*.java"/>

  <exclude name="**/*.gif"/>

 </fileset>

</copy>

Tâche

Attributs obligatoires

Rôle

Exemple

Ant


Exécution d'un autre script

<ant antfile="project1/build.xml" target="compile"/>

chmod

File ou dir

perm

Changement des droits utilisateurs

<chmod perm="g+w">

<fileset dir="/bin">

<exclude name="*.class"/>

</fileset>

</chmod>


copy

File ou fileset

ToFile ou toDir

Copier un ensemble de fichiers

<copy todir="distrib">

<fileset dir="**/*.class"/>

</copy>

echo

message

afficher un message

<echo message="compiling…"/>

cvs


exécuter une commande cvs

<cvs

cvsroot=":pserver:guest@djefer.com:/home/public" dest="${ws.dir}" command="update">

delete

file ou dir

effacer un ensemble de fichier et répertoire

<delete dir="build"/>

exec

exécutable

exécution d'une commande système

<exec executable="notepad"/>

jar

jarfile

compression de fichiers

<jar jarfile="${dist}/lib/aws.jar">

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

excludes ="**/CVS/*"/>

</jar>

javac

srcdir

Compilation java

<javac destdir="${build"

classpath="lib/hexadev.jar">

<src path="${src}">

<exclude name="**/test*.java"/>

</javac>

javadoc

sourcepath

ou sourcepathRef

génération de la documentation HTML

<javadoc

packagenames="hexadev.*" sourcepath="${src}" destdir="docs/api"/>

mkdir

dir

construction d'un répertoire

<mkdir dir="${build}"/>

move

File ou fileset

ToFile ou toDir

Déplacer un ensemble de fichier

<move todir="${src}"

<fileset dir="${old_src}"

<exclude name="**/*.bak"/>

</fileset>

</move>

replace

File ou dir

token

Remplacer toutes les occurrences d'une chaîne par une autre dans un ensemble de fichiers

<replace dir="${src}" value="hexamaj">

<replacetoken><![CDATA[dynamix]]></replacetoken>

</replace>

taskDef

Name ou classpath

Permet l'ajout d'une tâche conçue par un utilisateur

<taskdef name="check" classname="com.hexadev.test.Unit"/>

touch

file

Création d'un nouveau fichier

<touch file="log1.txt"/>

tstamp


permet de mettre à jour les variables d'environnement DSTAMP, TSTAMP et TODAY respectivement avec la date courante incluant l'année, l'heure courante et la date courante avec un formatage plus riche

<tstamp/>

<echo message="${DSTAMP}/>

unjar

src ou dest

Décompresser une archive jar

<unjar src="${dist}\lib\hexadev.jar" dest="${archive}"/>

Ajouter une nouvelle tâche nécessite d'implémenter l'interface org.apache.tools.ant.Task incluant la méthode execute() throws BuildException. Chaque méthode de type setUnAttribut( String valeur ) peut être utilisée pour recevoir des arguments à partir du script build.xml. Pour que la tâche soit incluse avec la distribution de ant, il suffit de décompresser le fichier ant.jar, d'y ajouter la nouvelle tâche et de modifier le fichier org/apache/tools/ant/taskdefs/default.properties en ajout une ligne de type 'nom de la tâche="classe" la réalisant'. En dernière étape, il suffit de reconstruire le jar ant.jar.

Exemple :


package com.mydomain;

import org.apache.tools.ant.BuildException;
import org.apache.tools.ant.Task;

/**
 * Nouvelle tâche pour ant à inclure dans
 * le fichier de propriété 'default.properties'
 * du package org.apache.tools.ant.taskdefs.
 * Cette tâche supporte l'attribut Error et
 * lève une exception dès son exécution
 */

public class ErrorTask extends Task {

    public void execute() throws BuildException {
	throw new BuildException( errorMessage );
    }

    public void setError( String errorMessage ) {
	this.errorMessage = errorMessage;
    }

    private String errorMessage;

}

Le fichier default.properties contient la ligne : "error=com.mydomain.errorTask".

Lors de l'utilisation, il suffira dans un target d'appeler la tâche error selon :

<error error="mon message d'erreur"> pour que ant fasse apparaître ce message et stoppe l'exécution de l'action.