Maven-assembly-plugin

Les différents types de packaging proposés par Maven (JAR, WAR, EJB, ..) sont bien utiles mais utilisent une structure pré-définie.
Dès lors qu’il s’agit de construire un dossier ou une archive avec une architecture particulière, comprenant le projet, ses dépendances, ses modules, sa documentation, et des fichiers organisés d’une manière précise … le plugin maven-assembly-plugin rend bien service !

Il propose quelques descripteurs de base, pratiques pour les cas standards, mais il permet également d’utiliser ses propres structures (des “descripteurs d’assembly” écrits en XML) pour les cas plus complexes.

Goals

Un seul goal est à utiliser avec ce plugin : assembly:single. Il effectue le travail souhaité, c’est à dire créer l’archive suivant la configuration définie.
Les autres goals existants (assembly:assembly, assembly:directory, assembly:directory-inline, assembly:single-directory) sont tous dépréciés.

Configuration

La configuration de maven-assembly-plugin est simple.

Dans sa balise <configuration>, on précise deux choses :
– Une liste de <descriptorRef>, correspondants soit à des descripteurs pré-définis, soit à des descripteurs d’assembly personnels. On peut donc effectuer plusieurs types d’assembly en une fois.
– La “MainClass” du Manifest, dans une balise <archive>.

Il reste à préciser à quelle phase du cycle de vie Maven l’assembly doit être lancé, dans la balise <execution>.

Une configuration assez basique peut donc ressembler à ça :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<plugin>
<artifactId>maven-assembly-plugin</artifactId>
<version>2.2</version>
<configuration>
<descriptors>
<descriptor>myAssemblyDescriptor.xml</descriptor>
<descriptor>jar-with-dependencies</descriptor>
</descriptors>
<archive>
<manifest>
<mainClass>test.mypackage.MainClass</mainClass>
</manifest>
</archive>
</configuration>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>single</goal>
</goals>
</execution>
</executions>
</plugin>

Avec ce petit bout d’XML ajouté au POM, à chaque fois que la phase “package” du cycle de vie Maven sera lancée, deux archives seront également construite. La première suivra la description du fichier myAssemblyDescriptor.xml, et la seconde utilise le descripteur jar-with-dependencies décrit par la suite.

Descripteurs pré-définis

bin

Ce descripteur, le plus simple, permet d’associer au jar du projet généré les fichiers LICENSE, README et NOTIC, en les ajoutant à la racine de l’archive générée.

jar-with-dependencies

jar-with-dependencies permet la construction d’un JAR contenant à la fois le projet, mais également l’ensemble de ses dépendances d’exécution. En configurant correctement la Main-Class du Manifest, on obtient ainsi un jar exécutable avec ses dépendances inclues.

src

src construit une archive contenant le code source du projet. L’archive produite contient l’ensemble du dossier /src/, les fichiers pom.xml et les éventuels fichier LICENSE, README et NOTICE situés à la racine du projet.

project

Ce descripteur construit une archive contenant l’ensemble du projet, suivant sa structure sur le disque, en omettant le dossier /target/.
Le but est d’obtenir une archive permettant de facilement reconstruire un projet Maven (ou Ant par exemple).

Descripteur d’assembly

Pour les cas ou des descripteurs décrits ci-dessus ne suffisent pas, on peut sortir un bon vieux fichier XML décrivant précisement ce qu’on veut dans l’archive construite.
Le descripteur d’assembly a accès à toutes les propriétés du POM.
Le fichier peut être très détaillé, je vais donc décrire seulement les éléments qui (à mon avis) servent le plus souvent.

Informations obligatoires

La balise <id>, qui indique le nom de l’archive produite.
La balise <format>, qui indique le format de l’archive produite, à choisir parmi : jar, zip, tar, bzip2, gzip, tar.gz, tar.bz2, rar, war, ear, sar, dir. On peut indiquer plusieurs formats différents, ce qui aura pour effet de produire plusieurs archives.

Un descripteur d’assembly peut ainsi commencer de la manière suivante :

1
2
3
4
5
6
<assembly>
<id>${project.version}</id>
<formats>
<format>zip</format>
</formats>
...

Le résultant sera donc un fichier .zip avec pour nom : LeNomDuProjet-LaVersionDuProjet.zip.

Description des fichiers à ajouter

Une fois cette simple configuration fait, il est temps d’attaquer la description du contenu de l’archive souhaitée.
Ceci se fait via 5 balises différentes : files, fileSets, dependencySets, moduleSets et Repositories.

Files

Cette balise, la plus simple, permet de décrire de manière exhaustive les fichiers à ajouter.
On y indique le fichier source (source), le nom du fichier cible (destName), le repertoire de destination (outputDirectory), et les droits du fichier cible (fileMode). (Plus de précisions sur ce qu’on peut indiquer dans la balise fileMode).

1
2
3
4
5
6
7
8
9
<files>
<file>
<source>target/MonProjet.jar</source>
<outputDirectory>.</outputDirectory>
<destName>MonProjetAvecUnNouveaNom.jar</source>
<fileMode>0755</fileMode>
</file>
<file> .. </file>
</files>
FileSets

FileSets permet d’ajouter des répertoires entiers, avec la possibilité de préciser quels fichier ajouter ou d’en filter certains.
On peut également utiliser un filtre de base, <useDefaultExcludes>, pour retirer un bon paquet de fichiers par défaut (SNV, CVS, ..).
La configuration est assez claire et parle d’elle même, donc voici un exemple simple :

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
<fileSets>
<fileSet>
<directory>MonDossierAAjouter</directory>
<outputDirectory>.</outputDirectory>
<excludes>
<exclude>**/*.log</exclude>
</excludes>
<useDefaultExcludes>true</useDefaultExcludes>
</fileSet>
<fileSet>
<directory>conf</directory>
<outputDirectory>conf</outputDirectory>
<includes>
<include>**/*.properties</include>
<include>**/*.xml</include>
</includes>
</fileSet>
</fileSets>
DependencySets

Cette balise permet d’ajouter les dépendances du projet.
Dans sa forme la plus simple, elle contient une simple balise <dependencySet /> indiquant qu’on souhaite ajouter l’ensemble des dépendances du projet à la racine de l’archive.
On peut préciser un peu les choses, en faisant par exemple un dependencySet par scope de dépendance, en excluant certaines dépendances, en précisant le répertoire cible …
Par défaut, l’artefact principal du projet est copié avec ses dépendances. Pour empêcher ça, on peut le préciser en mettant <useProjectArtifact> à false.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<dependencySets>
<dependencySet>
<scope>provided</scope>
<outputDirectory>lib</outputDirectory>
<useProjectArtifact>false</useProjectArtifact>
</dependencySet>
<dependencySet>
<scope>runtime</scope>
<outputDirectory>lib2</outputDirectory>
<excludes>
<exclude>*:zip</exclude>
</excludes>
<useProjectArtifact>false</useProjectArtifact>
</dependencySet>
</dependencySets>
ModuleSets

Pour les projets multi-modules, maven-assembly-plugin permet de gérer l’inclusion de sources ou de binaires à l’archive construite, pour chaque module de l’application.
De la même manière que pour FileSet et DependencySet, on peut inclure un ensemble de ressources d’un module.
Pour entrer dans les détails, je vous conseille de suivre ce lien : http://maven-guide-fr.erwan-alliaume.com/maven-guide-fr/site/reference/assemblies-sect-modulesets.html, très bien expliqué et détaillé.

Repositories

Cette balise permet d’ajouter des artefacts en provenance de notre repository local à l’archive générée.
Les artefacts seront alors copiés en suivant la structure de dossiers qu’ils avaient dans le repository local.
On pourra noter l’existance de la balise <includeMetadata>, permettant de préciser si les métadonnées doivent être inclues. Si c’est le cas, elles seront uniquement téléchargées à partir du repository Maven central.

Conclusion

Pour créer facilement des archives personnalisées, le plugin assembly est vraiment pratique.
Simple à mettre en place et à utiliser, il répond à quelques cas standards, que ce soit avec les descripteurs par défaut ou avec l’utilisation des descripteurs d’assembly.

Sources

 

VN:R_U [1.9.22_1171]
Rating: 0 (from 0 votes)
Share
Ce contenu a été publié dans Maven. Vous pouvez le mettre en favoris avec ce permalien.

Laisser un commentaire