98. Ant

Niveau :

Supérieur

Ant est un projet du groupe Apache-Jakarta. Son but est de fournir un outil écrit en Java pour permettre la construction d'applications (compilation, exécution de tâches post et pré compilation, ... ). Ces processus de construction d'applications sont très importants car ils permettent d'automatiser des opérations répétitives tout au long du cycle de développement de l'application (développement, tests, recettes, mises en production, ... ). Le site officiel de l'outil Ant est https://ant.apache.org/.

Ant pourrait être comparé au célèbre outil make sous Unix. Il a été développé pour fournir un outil de construction indépendant de toute plate-forme. Ceci est particulièrement utile pour des projets développés sur et pour plusieurs systèmes ou, pour migrer des projets d'un système sur un autre. Il est aussi très efficace pour de petits développements.

Ant repose sur un fichier de configuration XML qui décrit les différentes tâches qui devront être exécutées par l'outil. Ant fournit un certain nombre de tâches courantes qui sont codées sous forme d'objets développés en Java. Ces tâches sont donc indépendantes du système sur lequel elles seront exécutées. De plus, il est possible d'ajouter ses propres tâches en écrivant de nouveaux objets Java respectant certaines spécifications.

Le fichier de configuration contient un ensemble de cibles (targets). Chaque cible contient une ou plusieurs tâches. Chaque cible peut avoir une dépendance envers une ou plusieurs autres cibles pour pouvoir être exécutée.

Les environnements de développement intégrés proposent souvent un outil de construction propriétaire qui est généralement moins souple et moins puissant que Ant. Ainsi des plugins ont été développés pour la majorité d'entre-eux (JBuilder, Forte, Visual Age, ...) et ainsi leur permettre d'utiliser Ant, devenu un standard de fait.

Ant possède donc plusieurs atouts : multiplate-forme, configurable grâce à un fichier XML, open source et extensible.

Pour obtenir plus de détails sur l'utilisation de l'outil Ant, il est possible de consulter la documentation de la version courante à l'url suivante : https://ant.apache.org/manual/index.html

Une version 2 de l'outil Ant est en cours de développement.

Ce chapitre contient plusieurs sections :

• L'installation de l'outil Ant
• L'exécution de l'outil Ant
• Le fichier build.xml
• Les tâches (task)

98.1. L'installation de l'outil Ant

Pour pouvoir utiliser Ant, il faut avoir un JDK 1.1 ou supérieur et installer Ant sur la machine.

98.1.1. L'installation sous Windows

Le plus simple est de télécharger la distribution binaire de l'outil Ant pour Windows : jakarta-ant-version-bin.zip sur le site de Ant.

Il suffit ensuite de :

• décompresser le fichier (un répertoire jakarta-ant-version contenant l'outil et sa documentation est créé)
• ajouter le chemin complet du répertoire bin de l'outil Ant à la variable système PATH (pour pouvoir facilement appeler Ant n'importe où dans l'arborescence du système)
• s'assurer que la variable JAVA_HOME pointe sur le répertoire contenant le JDK
• créer une variable d'environnement ANT_HOME qui pointe sur le répertoire jakarta-ant-version créé lors de la décompression du fichier
• il peut être nécessaire d'ajouter les fichiers .jar contenus dans le répertoire lib de l'outil Ant à la variable d'environnement CLASSPATH

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

98.2. L'exécution de l'outil Ant

Ant s'utilise en ligne de commandes avec la syntaxe suivante :

ant [options] [cible]

Par défaut, Ant recherche un fichier nommé build.xml dans le répertoire courant. Ant va alors exécuter la cible par défaut définie dans le projet de ce fichier build.xml.

Il est possible de préciser le nom du fichier de configuration en utilisant l'option -buildfile et en la faisant suivre du nom du fichier de configuration.

ant -buildfile monbuild.xml

Il est possible de préciser une cible à exécuter. Dans ce cas, Ant exécute les cibles dont dépend la cible précisée et exécute cette dernière.

ant clean

Ant possède plusieurs options dont voici les principales :

98.3. Le fichier build.xml

Le fichier build est un fichier XML qui contient la description du processus de construction de l'application.

Comme tout document XML, le fichier débute par un prologue :

<?xml version="1.0">

L'élément principal de l'arborescence du document est le projet représenté par le tag <project> qui est donc le tag racine du document.

A l'intérieur du projet, il faut définir les éléments qui le composent :

• les cibles (targets) : des étapes du projet de construction
• les propriétés (properties) : des variables qui contiennent des valeurs utilisables par d'autres éléments (cibles ou tâches)
• les tâches (tasks) : des traitements unitaires à réaliser dans une cible donnée

Pour permettre l'exécution sur plusieurs plates-formes, les chemins de fichiers indiqués dans le fichier build.xml doivent utiliser le caractère slash '/' comme séparateur, et ce, même sous Windows qui utilise le caractère anti-slash '\'.

98.3.1. Le projet

Il est défini par le tag racine <project> dans le fichier build.

Ce tag possède plusieurs attributs :

• name : précise le nom du projet
• default : précise la cible par défaut à exécuter si aucune cible n'est précisée lors de l'exécution
• basedir : précise le répertoire qui servira de référence pour l'utilisation d'une localisation relative des autres répertoires.

  <project name="mon projet" default="compile" basedir=".">

98.3.2. Les commentaires

Les commentaires sont inclus dans un tag <!-- -->.

  <!-- Exemple de commentaires -->

98.3.3. Les propriétés

Le tag <property> permet de définir une propriété qui pourra être utilisée dans le projet : c'est souvent la définition d'un répertoire ou d'une variable qui sera utilisée par certaines tâches. Sa définition, en tant que propriété, permet de facilement définir sa valeur qui pourra être ensuite utilisée plusieurs fois dans le projet.

  <property name= "nom_appli" value= "monAppli"/> 

Les propriétés sont immuables et peuvent être définies de deux manières :

• avec le tag <property>
• avec l'option -D sur la ligne de commandes lors de l'appel de la commande ant

Pour utiliser une propriété sur la ligne de commandes, il faut utiliser l'option -D immédiatement suivie du nom de la propriété puis du caractère =, suivi lui-même de la valeur, le tout sans espace.

Le tag <property> possède plusieurs attributs :

• name : définit le nom de la propriété
• value : définit la valeur de la propriété
• location : permet de définir un fichier avec son chemin absolu. Peut être utilisé à la place de l'attribut value
• file : permet de préciser le nom d'un fichier qui contient la définition d'un ensemble de propriétés. Ce fichier sera lu et les propriétés qu'il contient seront définies.

L'utilisation de l'attribut file est particulièrement utile car il permet de séparer la définition des propriétés du fichier build. Le changement d'un paramètre ne nécessite alors pas de modification dans le fichier xml build.

  <property file="mesproprietes.properties" />
  <property name="repSources" value="src" />
  <property name="projet.nom" value="mon_projet" />
  <property name="projet.version" value="0.0.10" />

L'ordre de définition des propriétés est très important : Ant gère cet ordre. La règle est la suivante : la première définition d'une propriété est prise en compte, les suivantes sont ignorées.

Ainsi, les propriétés définies par la ligne de commandes sont prioritaires par rapport à celles définies dans le fichier build. Il est aussi préférable de mettre le tag <property> contenant un attribut file avant les tags <property> définissant des variables.

Pour utiliser une propriété définie dans le fichier, il faut utiliser la syntaxe suivante :
${nom_propriete}

  ${repSources} 

Il existe aussi des propriétés prédéfinies par Ant et utilisables dans chaque fichier build :

98.3.4. Les ensembles de fichiers

Le tag <fileset> permet de définir un ensemble de fichiers. Cet ensemble de fichiers sera utilisé dans une autre tâche. La définition d'un tel ensemble est réalisée grâce à des attributs du tag <fileset> :

L'expression **/ permet de désigner tous les sous-répertoires du répertoire défini dans l'attribut dir.

<fileset dir="src" includes="**/*.java">

98.3.5. Les ensembles de motifs

Le tag <patternset> permet de définir un ensemble de motifs pour sélectionner des fichiers.

La définition d'un tel ensemble est réalisée grâce à des attributs du tag <patternset> :

L'expression **/ permet de désigner tous les sous-répertoires du répertoire définit dans l'attribut dir. Le caractère ? représente un unique caractère quelconque et le caractère * représente zéro ou n caractères quelconques.

<fileset dir="src">
  <patternset id="source_code">
    <includes="**/*.java"/>
  </patternset>
</fileset>

98.3.6. Les listes de fichiers

Le tag <filelist> permet de définir une liste finie de fichiers. Chaque fichier est nommément ajouté dans la liste, séparé du suivant par une virgule. La définition d'un tel élément est réalisée grâce à des attributs du tag <filelist> :

<filelist dir="texte" files="fichier1.txt,fichier2.txt" />

98.3.7. Les éléments de chemins

Le tag <pathelement> permet de définir un élément qui sera ajouté à la variable classpath. La définition d'un tel élément est réalisée grâce à des attributs du tag <pathelement> :

<classpath>
  <pathelement location="bin/mabib.jar">
  <pathelement location="lib/">
</classpath>

Il est préférable, pour assurer une meilleure compatibilité entre plusieurs systèmes, d'utiliser des chemins relatifs au répertoire de base du projet.

98.3.8. Les cibles

Le tag <target> définit une cible. Une cible est un ensemble de tâches à réaliser dans un ordre précis. Cet ordre correspond à celui des tâches décrites dans la cible.

Le tag <target> possède plusieurs attributs :

• name : contient le nom de la cible. Cet attribut est obligatoire
• description : contient une brève description de la cible. Cet attribut est optionnel mais il est recommandé de l'utiliser car la plupart des IDE l'affichent lors de l'utilisation de l'outil ant
• if : permet de conditionner l'exécution à l'existence d'une propriété. Cet attribut est optionnel
• unless : permet de conditionner l'exécution à l'inexistence de la définition d'une propriété. Cet attribut est optionnel
• depends : permet de définir la liste des cibles dont dépend la cible. Cet attribut est optionnel

Il est possible de faire dépendre une cible d'une ou plusieurs autres cibles du projet. Lorsqu'une cible doit être exécutée, Ant s'assure que les cibles dont elle dépend ont été complètement exécutées préalablement. Une dépendance est définie grâce à l'attribut depends. Plusieurs cibles dépendantes peuvent être listées dans l'attribut depends. Dans ce cas, chaque cible doit être séparée de la suivante avec une virgule.

98.4. Les tâches (task)

Une tâche est une unité de traitements contenue dans une classe Java qui implémente l'interface org.apache.ant.Task. Dans le fichier de configuration, une tâche est un tag qui peut avoir des paramètres pour configurer le traitement à réaliser. Une tâche est obligatoirement incluse dans une cible.

Ant fournit en standard un certain nombre de tâches pour des traitements courants lors du développement en Java :

Certaines de ces tâches seront détaillées dans les sections suivantes : pour une référence complète de ces tâches, il est nécessaire de consulter la documentation de l'outil Ant.

98.4.1. echo

La tâche <echo> permet d'écrire dans un fichier ou d'afficher un message ou des informations durant l'exécution des traitements.

Les données à utiliser peuvent être fournies dans un attribut dédié ou dans le corps du tag <echo>.

Cette tâche possède plusieurs attributs dont les principaux sont :

<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="Test avec Ant" default="init" basedir="."> 
  <!-- =================================================================== --> 
  <!-- Initialisation --> 
  <!-- =================================================================== --> 
  <target name="init"> 
    <echo message="Debut des traitements" /> 
    <echo> 
      Fin des traitements du projet ${ant.project.name} 
    </echo> 
    <echo file="${basedir}/log.txt" append="false" message="Debut des traitements" /> 
    <echo file="${basedir}/log.txt" append="true" > 
Fin des traitements 
    </echo> 
  </target>  
</project> 

C:\java\test\testant>ant
Buildfile: build.xml

init:
     [echo] Debut des traitements
     [echo]
     [echo]       Fin des traitements du projet Test avec Ant
     [echo]

BUILD SUCCESSFUL
Total time: 2 seconds
C:\java\test\testant>type log.txt
Debut des traitements
Fin des traitements

C:\java\test\testant>

98.4.2. mkdir

La tâche <mkdir> permet de créer un répertoire avec éventuellement ses répertoires pères si ceux-ci n'existent pas.

Cette tâche possède un seul attribut:

<?xml version="1.0" encoding="ISO-8859-1"?> 
<project name="Test avec Ant" default="init" basedir="."> 
  <!-- =================================================================== --> 
  <!-- Initialisation --> 
  <!-- =================================================================== --> 
  <target name="init"> 
    <mkdir dir="${basedir}/gen" /> 
  </target>  
</project>

C:\java\test\testant>ant
Buildfile: build.xml

init:
    [mkdir] Created dir: C:\java\test\testant\gen

BUILD SUCCESSFUL
Total time: 2 seconds
C:\java\test\testant>

98.4.3. delete

La tâche <delete> permet de supprimer des fichiers ou des répertoires.

Cette tâche possède plusieurs attributs dont les principaux sont :

<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="Test avec Ant" default="init" basedir=".">
  <!-- =================================================================== -->
  <!-- Initialisation -->
  <!-- =================================================================== -->
  <target name="init">
    <delete dir="${basedir}/gen" />
    <delete file="${basedir}/log.txt" />
    <delete>
      <fileset dir="${basedir}/bin" includes="**/*.class" />
    </delete>
  </target>
</project>

C:\java\test\testant>ant
Buildfile: build.xml

init:
   [delete] Deleting directory C:\java\test\testant\gen
   [delete] Deleting: C:\java\test\testant\log.txt

BUILD SUCCESSFUL
Total time: 2 seconds
C:\java\test\testant>

98.4.4. copy

La tâche <copy> permet de copier un ou plusieurs fichiers dans le cas où ils n'existent pas dans la cible ou s'ils sont plus récents dans la cible.

Cette tâche possède plusieurs attributs dont les principaux sont :

L'ensemble des fichiers concernés par la copie doit être précisé avec un tag fils <fileset>.

<project name="utilisation de hbm2java" default="init" basedir=".">

  <!-- Definition des proprietes du projet -->
  <property name="projet.sources.dir"    value="src"/>
  <property name="projet.bin.dir"        value="bin"/>

  <!-- Initialisation des traitements -->
  <target name="init" description="Initialisation">
    <!-- Copie des fichiers de mapping et parametrage -->
    <copy todir="${projet.bin.dir}" >
      <fileset dir="${projet.sources.dir}" >
        <include name="**/*.properties"/>
        <include name="**/*.hbm.xml"/>
        <include name="**/*.cfg.xml"/>
      </fileset>
    </copy>
  </target>
</project>

C:\java\test\testhibernate>ant
Buildfile: build.xml

init:
     [copy] Copying 3 files to C:\java\test\testhibernate\bin

BUILD SUCCESSFUL
Total time: 3 seconds

98.4.5. tstamp

La tâche <tstamp> permet de définir trois propriétés :

• DSTAMP : initialisée avec la date du jour au format AAAMMJJ
• TSTAMP : initialisée avec l'heure actuelle sous la forme HHMM
• TODAY : initialisée avec la date du jour au format long

Cette tâche ne possède pas d'attribut.

<?xml version="1.0" encoding="ISO-8859-1"?>
<project name="Test avec Ant" default="init" basedir=".">
  <!-- =================================================================== -->
  <!-- Initialisation -->
  <!-- =================================================================== -->
  <target name="init">
    <tstamp/>
    <echo message="Nous sommes le ${TODAY}" />
    <echo message="DSTAMP = ${DSTAMP}" />
    <echo message="TSTAMP = ${TSTAMP}" />
  </target> 
</project>

C:\java\test\testant>ant
Buildfile: build.xml

init:
     [echo] Nous sommes le August 25 2004
     [echo] DSTAMP = 20040825
     [echo] TSTAMP = 1413

BUILD SUCCESSFUL
Total time: 2 seconds

98.4.6. java

La tâche <java> permet de lancer une machine virtuelle pour exécuter une application compilée.

Cette tâche possède plusieurs attributs dont les principaux sont :

Le tag fils <arg> permet de fournir des paramètres à l'exécution.

Le tag fils <classpath> permet de définir le classpath à utiliser lors de l'exécution

<project name="testhibernate1" default="TestHibernate1" basedir=".">  

  <!-- Definition des proprietes du projet --> 
  <property name="projet.sources.dir"    value="src"/> 
  <property name="projet.bin.dir"        value="bin"/> 
  <property name="projet.lib.dir"        value="lib"/>
       
  <!-- Definition du classpath du projet -->
  <path id="projet.classpath">
    <fileset dir="${projet.lib.dir}">
      <include name="*.jar"/>
    </fileset>
    <pathelement location="${projet.bin.dir}" />
  </path>
    
  <!-- Execution de TestHibernate1 -->
  <target name="TestHibernate1" description="Execution de TestHibernate1" >
    <java classname="TestHibernate1" fork="true">
      <classpath refid="projet.classpath"/>
    </java>
  </target>
</project>

98.4.7. javac

La tâche <javac> permet la compilation de fichiers sources contenus dans une arborescence de répertoires.

Cette tâche possède plusieurs attributs dont les principaux sont :

<project name="compiltation des classes" default="compile" basedir=".">
  <!-- Definition des proprietes du projet -->
  <property name="projet.sources.dir" value="src"/>
  <property name="projet.bin.dir" value="bin"/>
  <property name="projet.lib.dir" value="lib"/>

  <!-- Definition du classpath du projet -->
  <path id="projet.classpath">
    <fileset dir="${projet.lib.dir}">
      <include name="*.jar"/>
    </fileset>
    <pathelement location="${projet.bin.dir}" />
  </path>
 
  <!-- Compilation des classes du projet -->
  <target name="compile" description="Compilation des classes">
    <javac srcdir="${projet.sources.dir}" 
	          destdir="${projet.bin.dir}" 
			  debug="on" 
			  optimize="off" 
			  deprecation="on">
      <classpath refid="projet.classpath"/>
    </javac>
  </target>
</project>

C:\java\test\testhibernate>antBuildfile: build.xmlcompile:
    [javac] Compiling 1 source file to C:\java\test\testhibernate\bin
    [javac] C:\java\test\testhibernate\src\TestHibernate1.java:9: cannot resolve symbol
    [javac] symbol : class configuration
    [javac] location: class TestHibernate1
    [javac] Configuration config = new configuration();
    [javac] ^
    [javac] 1 error

BUILD FAILED
file:C:/java/test/testhibernate/build.xml:22: Compile failed; see the compiler e
rror output for details.

Total time: 9 seconds

98.4.8. javadoc

La tâche <javadoc> permet de demander la génération de la documentation au format javadoc des classes incluses dans une arborescence de répertoires.

Cette tâche possède plusieurs attributs dont les principaux sont :

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

<project name="Test avec Ant" default="javadoc" basedir=".">
  <!-- ================================================-->
  <!-- Génération de la documentation Javadoc          -->
  <!-- ================================================-->
  <target name="javadoc">
    <javadoc sourcepath="src"
                destdir="doc" >
      <fileset dir="src" defaultexcludes="yes">
        <include name="**" />
      </fileset>
    </javadoc>
  </target> 
</project>

C:\java\test\testant>ant
Buildfile: build.xml

javadoc:
  [javadoc] Generating Javadoc
  [javadoc] Javadoc execution
  [javadoc] Loading source file C:\java\test\testant\src\MaClasse.java...
  [javadoc] Constructing Javadoc information...
  [javadoc] Standard Doclet version 1.4.2_02
  [javadoc] Building tree for all the packages and classes...
  [javadoc] Building index for all the packages and classes...
  [javadoc] Building index for all classes...

BUILD SUCCESSFUL
Total time: 9 seconds

98.4.9. jar

La tâche <jar> permet la création d'une archive de type jar.

Cette tâche possède plusieurs attributs dont les principaux sont :

<?xml version="1.0" encoding="ISO-8859-1"?>
  <project name="Test avec Ant" default="packaging" basedir=".">
  
  <!-- =================================================================== -->
  <!-- Génération de l'archive jar                           -->
  <!-- =================================================================== -->
  <target name="packaging">
    <jar jarfile="test.jar" basedir="src" />
  </target> 
</project>

C:\java\test\testant>ant
Buildfile: build.xml

packaging:
      [jar] Building jar: C:\java\test\testant\test.jar

BUILD SUCCESSFUL
Total time: 2 seconds

La suite de ce chapitre sera développée dans une version future de ce document