Ivy est outil de gestion de dépendances très utilisé et très flexible. Parmis ses fonctionnalités, nous allons illustrer son utilisation pour récupérer des artefacts dans un repository distant de type Maven. Dans l’exemple de ce billet, nous utiliserons Ivy avec le builder Ant.
Dans le cadre d’un repository distant de type Maven, il est très simple de récupérer l’artefact binaire avec ses dépendances transitives, grâce à la lecture par Ivy du descripteur Maven. Néanmoins, il est souvent méconnu de savoir comment récupérer depuis Ivy les artefacts des sources, les artefacts de la javadoc ou un artefact d’un type ou d’un classifier particulier.
Nous allons utiliser pour notre exemple les artefacts du plugin gradle de Hudson, localisés dans le repository Maven java.net. Nous récupérerons la version 1.2. Dans le cadre du builder Maven, chaque projet produit un seul artefact. Des notions supplémentaires de types et de classifiers (ou de natures) permettent de produire plusieurs livrables par projet. En Ivy, c’est légèrement différent avec pour un module, la production possible de plusieurs artefacts.
La liste des artefacts à récupérer sont aux adresses suivantes :
- http://download.java.net/maven/2/org/jvnet/hudson/plugins/gradle/1.2/gradle-1.2-javadoc.jar
- http://download.java.net/maven/2/org/jvnet/hudson/plugins/gradle/1.2/gradle-1.2-sources.jar
- http://download.java.net/maven/2/org/jvnet/hudson/plugins/gradle/1.2/gradle-1.2.hpi
- http://download.java.net/maven/2/org/jvnet/hudson/plugins/gradle/1.2/gradle-1.2.jar
Nous avons l’artefact des sources, l’artefact de la documentation javadoc, un binaire avec une extension « jar » et un binaire avec une extension « hpi ». Nous avons donc en Ivy la valeur « org.jvnet.hudson.plugins » pour l’organisation, la valeur « gradle » pour le nom du module et la valeur « 1.2 » pour la version.
Pour notre besoin, nous devons réaliser les étapes suivantes
- Écriture du fichier de configuration globale de Ivy spécifiant le repository java.net
- Écriture du descripteur Ivy décrivant les module avec les différents artefacts à récupérer.
- Écriture du script de build Ant pour mettre en oeuvre Ivy
- Invocation du script Ant pour la récupération des artefacts
Écriture du fichier de configurations globale de Ivy
-
<?xml version=« 1.0 »?>
-
<ivysettings>
-
<settings defaultResolver=« java.net2 »/>
-
<resolvers>
-
<ibiblio name=« java.net2 » root=« http://download.java.net/maven/2/ » m2compatible=« true »/>
-
</resolvers>
-
</ivysettings>
Nous spécifions que Ivy va rechercher et récupérer par défaut les dépendances dans le repository java.net de type Maven2.
Écriture du descripteur Ivy décrivant le module avec ses artefacts à récupérer.
-
<!– fichier ivysettings.xml –>
-
<ivy-module version=« 2.0 » xmlns:m=« http://ant.apache.org/ivy/maven »>
-
<info organisation=« net.boissinot » module=« artifact-example » >
-
<description>
-
Complex Artifact Example
-
</description>
-
</info>
-
<configurations>
-
<conf name=« bin »/>
-
<conf name=« source »/>
-
<conf name=« javadoc »/>
-
</configurations>
-
<dependencies>
-
<dependency org=« org.jvnet.hudson.plugins » name=« gradle » rev=« 1.0 »
-
conf=« bin,sources,javadoc->master »>
-
<artifact name=« gradle » conf=« bin » />
-
<artifact name=« gradle » type=« hpi » conf=« bin » />
-
<artifact name=« gradle »
-
type=« source »
-
ext=« jar »
-
m:classifier=« sources »
-
conf=« source »/>
-
<artifact name=« gradle »
-
type=« javadoc »
-
ext=« jar »
-
m:classifier=« javadoc »
-
conf=« javadoc »/>
-
</dependency>
-
</dependencies>
-
</ivy-module>
Premièrement, nous déclarons 3 configurations nommées « bin », « source » et « javadoc ». Chaque configuration va contenir un ensemble de fichiers définissant un classpath. Nous souhaitons que la configuration « bin » contienne les artefacts binaires, la configuration « source » contienne les artefacts de sources et la configuration « javadoc » contienne les artefacts de javadoc. En terme de post traitement, il est recommandé de faire des espaces différents.
Puis nous déclarons notre dépendance vers le module Gradle avec explicitement les artefacts du module.
Détail des dépendances
Au niveau du module en dépendance, nous avons la configuration suivante
conf="bin,sources,javadoc->master"
Côté gauche de la « → », nous spécifions les configurations de notre module courant. Ce sont les configurations qui vont contenir les artefacts récupérés. Côté droit, nous spécifions la configuration du module cible. Dans le cadre de Maven, la clé logique « master » spécifie que nous souhaitons récupérer uniquement l’artefact.
Remarque: pour récupérer l’artefact et ses dépendances transitives de compilation et de d’exécution, nous aurions utiliser la configuration « default ».
Détail des artefacts
Pour chaque élément <artifact>, nous devons préciser :
- Un attribut « name » décrivant le nom de l’artefact Ivy. En maven, ce nom est toujours le même pour un module donné.
- Un attribut « conf » sélectionnant la configuration dans la quel sera stockée l’artefact. L’élément est optionnel si nous avions spécifié une configuration par défaut.
- Un attribut « type ». La valeur par défaut est « jar ».
- Un attribut d’extension « ext » qui a pour défaut la valeur de l’attribut « type ».
- Et un classifier si besoin. Il est importé depuis l’espace de noms Maven. Il permet de sélectionner notre artefact Maven avec le bon classifier.
Écriture du script de build Ant
-
<project name=« example » default=« ivy-retrieve » xmlns:ivy=« antlib:org.apache.ivy.ant »>
-
<property name=« settings.dir » location=« settings »/>
-
<property name=« ivy.lib.dir » value=« lib »/>
-
<target name=« ivy-init »>
-
<ivy:settings file=« ${settings.dir}/ivysettings.xml »/>
-
</target>
-
<target name=« ivy-resolve » depends=« ivy-init »>
-
<ivy:resolve file=« ${basedir}/ivy.xml » />
-
</target>
-
<target name=« ivy-retrieve » depends=« ivy-resolve »>
-
<ivy:retrieve pattern=« ${ivy.lib.dir}/[type]s/[artifact]-[revision](-[classifier]).[ext] » sync=« true » />
-
</target>
-
</project>
Nous avons trois cibles Ant.
- La cible Ant « ivy-init » va initialiser et charger notre fichier Ivy de configuration globale déclarant le repository java.net.
- La cible Ant « ivy-resolve » va analyser le fichier descripteur Ivy « ivy.xml » et résoudre toutes les dépendances. Ces dépendances seront téléchargées dans le cache local de Ivy. L’emplacement du cache est spécifié à travers la propriété « ivy.cache.dir »; sa valeur par défaut est « USER_HOME/.ivy2 ».
- La cible Ant « ivy-retrieve » va copier les artefacts dans un réperoire définit par la propriété « ivy.lib.dir » avec pour organisation le pattern « [type]s/[artifact]-[revision](-[classifier]).[ext] ». Nous allons donc avoir par exemple « lib/javadocs/gradle-1.2-javadoc.jar »
Et nous spécifions que la cible « ivy-retrieve » sera invoquée par défaut.
Invocation de la récupération des artefacts
Le simple appel de la commande ant invoquera la cible par défaut « ivy-retrieve », déclenchant l’initialisation de la configuration, la récupération des artefacts dans le cache Ivy, puis la copie de ces artefacts dans le répertoire définit par la propriété « ivy.lib.dir ».
