![]()
Powered by![]() | Sweet Ant Tools 1.0Michel CASABIANCA - casa@sweetohm.netSweet Ant Tools est un ensemble de tâches pour Ant sous licence Apache. Elles sont, pour l'essentiel, dédiées à la construction de pages HTML à partir de fichiers XML.
Installer SATPour installer SAT, vous devez au préalable installer une machine virtuelle Java 1.2 ou plus récente. On peut en télécharger une gratuitement sur le site web de Sun. La dernière version de SAT est disponible sur ma page personnelle. Pour installer SAT, dézipper l'archive dans le répertoire de votre choix. Copier ensuite les fichiers du répertoire lib dans le répertoire lib de votre installation de Ant. Compiler SATPour compiler SAT, vous devez installer Ant version 1.3 ou 1.4. Vous pouvez le télécharger sur le site d'Apache. On devra aussi installer les jars de Ant (ant.jar) et d'un parser JAXP (par exemple, celui que l'on peut télécharger sur le site de Sun) dans le répertoire lib de SAT. Pour générer le fichier jar contenant les classes de SAT, se placer à la racine de votre installation de SAT taper ant jar sur la ligne de commande. Placer ensuite le fichier jar généré (sat.jar du répertoire lib) dans le répertoire lib de Ant. On pourra alors générer les documentations et l'archive zip en tapant ant (SAT s'utilise lui même pour compiler les documentations et l'archive zip). Console AntCet outil permet de lancer Ant en mode console (dans un terminal ou la console d'un IDE par exemple). On y tape des commande qui sont interprêtées par la console pour lancer les targets du build file chargé. L'intérêt de cette console est d'accélérer grandement la vitesse d'exécution car on économise le temps de lancement de la machine virtuelle, de compilation par le JIT, de chargement du projet, etc. On peut ainsi espérer des gains d'un facteur 5. Il va sans dire que le gain est d'autant plus important que le temps d'exécution de ma target est court. InstallationAller dans le répertoire bin de votre installation de Ant. Recopier le fichier ant (ou ant.bat pour les handicapés de l'OS) sous le nom antc (ou antc.bat). Remplacer, dans ce nouveau fichier, toutes les occurences de org.apache.tools.ant.Main par net.cafebabe.sat.ant.Console. Ce script lancera alors la console Ant en lieu et place de Ant lui même. S'assurer que ce ficher est dans votre PATH. Il faut bien entendu installer SAT. Pour ce faire, recopier le fichier sat.jar dans la répertoire lib de votre installation de Ant. UtilisationPour lancer la console Ant, se placer dans le répertoire de son projet (où se trouve votre fichier de projet build.xml) et taper antc. On obtient une aide sur les paramètres en ligne de commande en tapant antc -help :
Lorsqu'on lance la console Ant, on obtient une invite du type :
![]() Figure 1: Console Ant en action Pour obtenir de l'aide sur les commandes que l'on peut lancer dans la console, taper help à l'invite. On obtient la page d'aide suivante :
On notera que pour lancer l'exécution d'un target, il suffit de taper son nom à l'invite (c'est un raccourci pour la commande target si le nom de la target n'est pas celui d'une commande de la console). On notera aussi que l'on peut répéter la dernière commande en tapant simplement ENTER. Il possible de charger un autre build file avec la commande load (le chemin du fichier est alors relatif au répertoire courant) et de rechercher récusivement le build file dans le système de fichier avec la commande find (comparable au paramètre -find sur la ligne de commande de Ant). Il est aussi possible de recharger le projet courant avec la commande reload. C'est nécessaire lorsque le build file a changé sur le disque ou lorsqu'un projet a un comportement étrange (ce qui arrive parfois à la suite d'une erreur de build, certaines tâches supportant mal d'être relancées après une erreur). La commande desc affiche une description du projet en cours (comme avec le paramètre -projecthelp de Ant). Enfin, on peut afficher les temps d'exécution avec la commande timer ayant pour paramètre on ou off. C'est utile pour se convaincre que la console est bien plus rapide (c'est pour cela que j'affiche le résultat en millisecondes :o) NotesDans la mesure où l'on économise le temps d'initialisation de la VM, de la compilation par le JIT et le temps de chargement du projet, il est clair que l'on obtient de meilleurs résultats pour des builds courts. Par exemple, l'exécution d'une tache qui ne fait rien, la console met une trentaine de millisecondes contre près de 5 secondes dans Ant (un gain de perfs d'un facteur 100 environ). Cependant le gain reste appréciable pour de vrais builds. Par exemple, la génération du projet SAT prend environ 12 secondes dans la console contre 25 secondes anviron avec Ant. Ma tache server permet d'obtenir les memes résultats, mais sa mise en oeuvre est plus complexe et je ne l'intègre plus dans les dernières versions de SAT (on pourra encore la trouver dans la version 0.7). La console a été développée avec la dernière version stable de Ant, soit la 1.5.3-1. Faites moi savoir si vous avez testé avec une autre version. Description des tâchesSAT est un ensemble de tâches optionnelles pour Ant, pour chaque tâche est donc associé un élément XML et une déclaration taskdef (pour indiquer quelle classe Java définit la tâche). File, dir et filesetToutes ces tâches manipulent des fichiers et utilisent les attributs file et dir ainsi que l'élément encapsulé fileset pour la sélection des fichiers à traiter. Tous ces attributs ou élément ont la même syntaxe que voici:
Les fichiers ou répertoires dont les chemins sont relatifs le sont par rapport au script Ant. Donc un attribut file="foo" dans le script /home/casa/build.xml désigne le fichier /home/casa/foo. Il est possible, dans une même tâche, d'utiliser toute combinaison d'attributs file et dir et de l'élément fileset. Par exemple, l'élément:
Sélectionne le fichier file, les fichiers du répertoire dir et les fichiers XML du répertoire dir2. BshDescriptionCette tâche exécute un script Beanshell. Ce script peut être contenu dans un fichier ou encapsulé dans l'élément de la tâche. On peut aussi passer des arguments au script avec l'attribut args ou une expression dans un script encapsulé. La déclaration de la tâche (sous l'élément <project>) est la suivante:
La tâche Beanshell a été testée avec succès avec la version 1.1a18 (la version dont le jar est distribuée dans ce package). Elle ne fonctionne pas avec les versions 1.1a12 ou antérieures (l'interface bsh.ConsoleInterface était différente avant la version 1.1a16) et avec la version 1.2b1 (pour cause de bug). Paramètres
Éléments encapsulésOn peut sélectionner les script à exécuter à l'aide d'un élément <fileset> encapsulé. Voire la documentation de Ant pour de plus amples détails sur l'élément fileset. Contenu textuelUn script peut être écrit directement dans un élément <bsh>. Propriétés AntUn script Beanshell peut accéder aux propriétés Ant à l'aide des commandes setAntProperty() et getAntProperty(). Voir plus bas pour un exemple. Commandes BeanshellCe package propose des commandes Beanshell permettant d'accéder aux propriétés Ant (définies à l'aide d'éléments property) à l'intérieur d'un script Beanshell. Ces commandes ont la signature suivante:
Une autre commande permet de résoudre un fichier relativement au script Ant en cours d'exécution. En effet, un chemin relatif dans un script Ant doit être interprété par rapport au répertoire du script (et non par rapport au répertoire courant). La signature de cette commande est la suivante:
On notera que cette tâche définit une variable antProject dans l'interpréteur Beanshell. Cette variable contient une référence vers le projet Ant en cours d'exécution. ExemplesPour exécuter un script bsh.bsh du répertoire test, on écrira l'élément suivant:
On peut aussi écrire le script directement dans l'élément <bsh>, comme suit:
On notera qu'un script encapsulé dans un élément bsh est parsé lors de l'exécution du script Ant. Il ne doit donc pas contenir les caractères < et & ou bien il doit être contenu dans un marqueur CDATA, comme suit:
Pour passer les arguments foo et bar au script, (comme s'ils lui étaient passés par la ligne de commande) on utilisera un attribut args:
Pour finir, un exemple plus complexe:
Où le script test/bsh.bsh est le suivant:
Cet exemple produit l'affichage suivant:
Cette trace indique l'ordre d'évaluation du code beanshell:
Le script suivant affiche la valeur de la propriété foo et donne une valeur à bar:
XTaskDescriptionCette tâche utilise le processeur XT de James Clark pour effectuer une transformation XSLT d'un document XML. Ce processeur (dont le développement a été arrêté par l'auteur) est tenu pour le plus rapide des processeurs XSLT implémentés en Java. La déclaration de la tâche (sous l'élément <project>) est la suivante:
Paramètres
Éléments encapsulésOn peut sélectionner le ou les fichiers XML à transformer à l'aide d'un élément <fileset>. Voire la documentation de Ant pour plus de détails sur cet élément. On peut de plus passer des paramètres au processeur XSLT à l'aide d'éléments <arg>. Par exemple, pour passer la valeur bar au paramètre foo, on inclura dans l'élément <xtask> l'élément:
L'élément <xtask> ne prend pas en compte de contenu textuel. ExemplesPour transformer le fichier foo.xml en bar.html à l'aide de la feuille de style transfo.xsl, on écrira l'élément suivant:
Pour passer la valeur bar au paramètre foo, on invoquera la transformation par:
Pour transformer les fichiers XML du répertoire xml en HTML avec la feuille de style page.xsl et placer les fichiers générés dans le répertoire html, on écrira:
NoteCette tâche était auparavant distribuée indépendemment sur ma page (en version 0.1). Elle est maintenant partie intégrante de SAT. ValidDescriptionCette tâche permet de valider des fichiers XML. Elle offre la possibilité de valider la conformité du document à une DTD ou bien de ne vérifier que la syntaxe XML (que le document est bien formé). On peut choisir d'arrêter la compilation Ant sur une erreur, le niveau d'erreur ou encore le nombre maximal d'erreurs à afficher par fichier. La déclaration de la tâche (sous l'élément <project>) est la suivante:
Paramètres
Éléments encapsulésOn peut sélectionner un ou plusieurs fichiers XML à valider à l'aide d'un élément <fileset>. Voire la documentation de Ant pour plus de détails sur cet élément. Cet élément ne prend pas en compte de contenu textuel. ExemplesPour valider les fichiers XML d'un répertoire, recopier dans ce dernier le buildfile suivant:
Puis lancer Ant (taper ant sur la ligne de commande). On notera que les attributs de la tâche de validation sont ceux par défaut. Adapter ce fichier pour vos besoins. Si l'on souhaite valider les fichiers Ant de son disque, on lancera à la racine:
L'attribut dtd est sur false car les buildfile sont réputés ne pas avoir de DTD, on demande à ne pas arrêter le parsing lorsque l'on rencontre des erreurs de manière à scanner tout le disque, on place le niveau d'erreur au minimum de manière à détecter tous les problèmes et enfin, on demande à n'afficher qu'une erreur de manière à ne pas être noyé sous le nombre d'erreurs (qui peut être très important). MergeDescriptionCet élément permet de fusionner des fichiers XML pour n'en former qu'un (contenant les éléments racine des fichiers fusionnés dans un élément englobant). La déclaration de la tâche (sous l'élément <project>) est la suivante:
Par exemple, cet élément permet de fusionner les deux documents XML suivants:
et:
En un seul fichier ci-dessous:
Cet élément est utile pour générer des documents composites issus de la fusion d'autres documents XML. Par exemple, c'est le cas de la page d'accueil de mon site. Elle comporte un texte d'introduction, des nouvelles brèves et des liens qui sont de petits fichiers fusionnés en un seul. Ce fichier résultant est ensuite transformé en HTML (en utilisant XSLT) pour donner la page d'accueil. Paramètres
Éléments encapsulésOn peut sélectionner un ou des fichiers XML à fusionner à l'aide d'un élément <fileset>. Voire la documentation de Ant pour plus de détails sur cet élément. Cet élément ne prend pas en compte de contenu textuel. ExemplesPour fusionner les fichiers XML du répertoire index d'encodage ISO 8859-1 en un fichier index.xml de type index, on utilisera l'élément suivant:
Pour fusionner tous les fichiers XML du répertoire xml et de ses sous répertoires en un fichier index.xml, on pourra écrire:
InsertDescriptionCette tâche permet de remplacer une instruction de traitement par le contenu d'un fichier. On peut ainsi inclure un fragment de fichier dans une page HTML par exemple. C'est ainsi que les menus sont inclus dans les pages de mon site. La déclaration de la tâche (sous l'élément <project>) est la suivante:
Paramètres
Éléments encapsulésOn peut sélectionner les fichiers à traiter à l'aide d'éléments <fileset> encapsulés. Voire la documentation de Ant pour de plus amples informations. Cet élément ne prend pas en compte de contenu textuel. ExemplesPour remplacer les instructions de traitement <?menu ?> des fichiers du répertoire html par le contenu du fichier menu.html, on écrira l'élément suivant:
NestDescriptionCette tâche permet d'encapsuler des fichiers dans un fichier, à l'emplacement d'une instruction de traitement. On peut ainsi inclure des fragments de HTML dans un même corps de document. La déclaration de la tâche (sous l'élément <project>) est la suivante:
Paramètres
Éléments encapsulésOn peut sélectionner les fichiers à traiter à l'aide d'éléments <fileset> encapsulés. Voire la documentation de Ant pour de plus amples informations. Cet élément ne prend pas en compte de contenu textuel. ExemplesPour encapsuler les fichiers du répertoire html dans le fichier page.html, à l'emplacement de l'instruction de traitement <?body ?, on écrira l'élément suivant :
SplitDescriptionCette tâche permet de découper des fichiers selon des instructions de traitement. Le nom des fichiers générés est indiqué dans les instructions de traitement délimitant le fichier. La déclaration de la tâche (sous l'élément <project>) est la suivante:
Par exemple, le fichier suivant:
Sera découpé en deux fichiers (page1.html et page2.html):
Si la plupart des processeurs XSLT (comme XT ou Xalan) proposent des extensions pour générer plusieurs documents, cette tâche permet de s'abstraire de ces particularités et de générer des documents multiples sans polluer son code XSLT de particularités propre à l'un ou l'autre de ces processeurs. Paramètres
Éléments encapsulésOn peut sélectionner les fichiers à traiter à l'aide d'éléments <fileset> encapsulés. Voire la documentation de Ant pour de plus amples précisions. Cet élément ne prend pas en compte de contenu textuel. ExemplesPour découper un fichier foo selon les instructions de traitement de la forme <?decoupe file="bar"?>, on écrira l'élément suivant:
XML Word CountDescriptionCette tâche compte les mots de documents XML. Très utile lorsqu'on écrit un article calibré. Par défaut, le texte contenu dans tout élément du document est pris en compte alors que le texte contenu dans les attributs est ignoré. Il est possible de changer ce comportement par défaut (voir les paramètres de la tâche). La déclaration de la tâche (sous l'élément <project>) est la suivante:
Paramètres
Éléments encapsulésOn peut sélectionner les fichiers à traiter à l'aide d'éléments <fileset> encapsulés. Voire la documentation de Ant pour de plus amples précisions. Cet élément ne prend pas en compte de contenu textuel. ExemplesSupposons que nous voulions compter le nombre de mots des fichiers XML du répertoire courant, sauf le fichier build.xml en excluant l'élément source du décompte. Nous pouvons écrire la target suivante :
Ce qui produira la sortie suivante :
Supposons que nous voulions indiquer les règles du décompte dans un fichier de propriétés, document.properties comme suit :
Ce fichier indique les règles suivantes :
Pour compter les mots des documents XML du répertoire xml en utilisant ces règles et placer le résultat dans la propriété Ant wc, on pourra écrire :
LinkDescriptionCette tâche permet de vérifier la validité des liens de fichiers HTML. Elle distingue deux types de liens: les liens locaux (qui appartiennent à un même site et sont relatifs) et les liens externes (qui pointent vers d'autres sites et qui commencent par http:, ftp: ou autre déclaration de protocole). La déclaration de la tâche (sous l'élément <project>) est la suivante:
Paramètres
Éléments encapsulésOn peut sélectionner les fichiers à traiter à l'aide d'éléments <fileset> encapsulés. Voire la documentation de Ant pour de plus amples précisions. Cet élément ne prend pas en compte de contenu textuel. ExemplesSupposons que l'on génère des pages HTML dans le répertoire html et ses sous répertoires. On veut vérifier les liens internes de ce site et interrompre la compilation en cas d'erreur. On pourra écrire:
En cas de lien brisé, la compilation sera interrompue avec un message indiquant le fichier concerné et le lien fautif. On veut maintenant vérifier les liens externes (ce qui est bien plus long) et ne pas interrompre la compilation en cas de lien brisé, mais les lister dans un fichier (links.txt). On pourra écrire:
Mode EmacsAnt est généralement utilisé pour générer des projets Java et est intégré de ce fait dans la plupart des outils de développement Java (comme JDE, un mode Emacs pour le développement Java). Il peut cependant être très utile en d'autres occasions, par exemple pour générer des documents HTML à partir de sources XML. C'est pourquoi j'ai développé ce mode qui permet de lancer Ant pour générer tout type de projet. Pour installer ce mode Ant, copier le fichier el/ant.el dans le répertoire de votre choix où Emacs sera capable de le retrouver, puis ajouter les lignes suivantes à votre fichier de configuration .emacs :
Lorsque vous relancez Emacs, il apparait un menu Ant comportant les entrées suivantes :
Le résultat du build est affiché dans un buffer de compilation, ce qui permet de cliquer sur les erreurs pour ouvrir le fichier fautif dans Emacs. Il peut être très commode d'affecter ces appels à Ant à des touches du clavier. Par exemple, mon fichier .emacs comporte les affectations suivantes :
LicenceCe logiciel est distribué sous licence Apache Software License. Vous trouverez une copie de cette licence dans le répertoire d'installation de SAT, dans le fichier LICENSE. HistoriqueVersion 1.0 (2003-07-15)Les modifications sont les suivantes :
Version 0.9 (2003-07-14)Les modifications sont les suivantes :
Version 0.8 (2003-07-13)Les modifications sont les suivantes :
Version 0.7 (2002-11-11)La documentation a été passée à ma nouvelle DTD et mise à jour. Nouvelles tâches :
Corrections et améliorations multiples :
Version 0.6 (2001-10-27)Optimisation de la tâche Merge (par utilisation de StringBuffers). On peut espérer un gain de performances d'un facteur 30 ! Version 0.5 (2001-10-17)Nouvelle tâche Valid pour validation des fichiers XML. Version 0.4 (2001-09-22)Nouvelle tâche Link permettant de tester les liens de fichiers HTML. Version 0.3 (2001-09-18)Test des attributs des tâches. Les attributs de fichier (file et dir) sont testés. Correction de bugs (les chemins des fichiers sont maintenant relatifs au répertoire du fichier de projet). Dans une tâche BSH, on peut maintenant lire et écrire des propriétés Ant avec les commandes setAntProperty() et getAntProperty(). Les tâches ne sont plus exécutables en tant que programme indépendant (il est beaucoup plus pratique des les exécuter dans Ant et c'est très pénible à maintenir). Le code a été adapté aux dernières versions de Beanshell (version 1.1a18 supportée, la 1.2b1 ne fonctionne pas à cause d'un bug). Implémentation de tests unitaires (dans le répertoire prj/test). Version 0.2 (2001-08-20)Adoption de l'API JAXP pour la tâche XTask. Permet d'instancier le parser XML de manière générique (la tâche est maintenant indépendante du parser SAX utilisé pourvu qu'il implémente l'API JAXP). Version 0.1 (2001-06-06)Les tâches ont été remaniées (après usage intensif pour construire mon site) de manière à être plus efficaces/ergonomiques. Les changements sont les suivants:
Il ne devrait plus intervenir de changements concernant la syntaxe des tâches. Les versions futures ne feront que stabiliser le code (il reste à tester intensivement es tâches et à coder des tests sur les attributs des tâches pour afficher des messages d'erreur clairs). Version 0.0 (2001-05-28)Première version de SAT. Comporte les tâches Bsh, XTask, Merge, Insert et Split. Enjoy ! Dernière mise à jour : 2003-07-14 |