Assembly plugin Maven

Pour les projets Maven, le plugin maven-assembly-plugin permet de générer des disributions. Cet article présente l'utilisation pour générer des distributions avec les dépendances déclarées.

Les exemples décrits sont disponibles sous ce lien : http://www.svn.jouvinio.net/study/trunk/maven/maven-assembly-plugin

Votre avis

Nobody voted on this yet  You need to enable JavaScript to vote

Tweet

Génération distribution

Objectifs

Dans le cadre de cet exemple, l'objectif est de compiler le projet et de construire une distribution, au format tar.gz, contenant les éléments suivants.

• Les scripts depuis le répertoire src/main/scripts à la racine de la distribution;
• Les fichiers depuis le répertoire src/main/config dans le sous répertoire config;
• Les fichiers depuis le répertoire src/main/filtered.config, avec remplacement des variables, dans le sous répertoire config;
• Les dépedances dans le sous répertoire libs de la distribution;
• Le paquet compilé à la racine de la distribution.

Configuration plugin assembly

Le plugin doit être déclaré dans le fichier pom.xml avec les instructions suivantes.

  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-assembly-plugin</artifactId>
        <version>3.1.0</version>
        <executions>
          <execution>
            <id>distribution-by-assembly</id>
            <phase>package</phase>
            <goals>
              <goal>single</goal>
            </goals>
            <configuration>
              <descriptors>
                <descriptor>src/main/assembly/assembly-config.xml</descriptor>
              </descriptors>
              <appendAssemblyId>false</appendAssemblyId>
            </configuration>
          </execution>
        </executions>        
      </plugin>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <version>3.0.2</version>
        <configuration>
          <archive>
            <manifest>
              <addDefaultImplementationEntries>true</addDefaultImplementationEntries>
              <addClasspath>true</addClasspath>
              <classpathPrefix>libs/</classpathPrefix>
              <mainClass>fr.ejn.tutorial.maven.mavenAssemblyPlugin.Tutorial</mainClass>
            </manifest>
          </archive>
        </configuration>
      </plugin>
    </plugins>
  </build>

A noter, le plugin maven-jar-plugin est utilisé pour compléter le fichier MANIFEST.MF avec la classe de démarrage ainsi que la définition du classpath avec les dépendances, dans le sous répertoire libs.

Les éléments important de la déclaration du plugin maven-assembly-plugin sont l'emplacement de la définition de la distribution, valeur du noeud descriptor, et la valeur false dans le noeud appendAssemblyId. Ce dernier permet de ne pas ajouter l'identifiant de la distribution, spécifié dans la description, en tant que prefixe du fichier.

Configuration distribution

Dans le cadre de cet exemple, la configuration est définie dans le fichier src/main/assembly/assembly-config.xml, référencé dans le noeud descriptor.

<assembly
  xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 http://maven.apache.org/xsd/assembly-1.1.3.xsd">

  <id>assembly-study</id>

  <formats>
    <format>tar.gz</format>
  </formats>

  <fileSets>
    <fileSet>
      <directory>src/main/config</directory>
      <outputDirectory>config</outputDirectory>
      <includes>
        <include>*</include>
      </includes>
    </fileSet>
    <fileSet>
      <directory>src/main/filtered.config</directory>
      <outputDirectory>config</outputDirectory>
      <includes>
        <include>*</include>
      </includes>
      <filtered>true</filtered>
    </fileSet>
    <fileSet>
      <directory>src/main/scripts</directory>
      <outputDirectory></outputDirectory>
      <includes>
        <include>*.sh</include>
      </includes>
      <fileMode>0744</fileMode>
      <lineEnding>unix</lineEnding>
    </fileSet>
  </fileSets>

  <dependencySets>
    <!-- All dependencies go in sub folder libs. -->
    <dependencySet>
      <outputDirectory>libs</outputDirectory>
      <!-- Exclude the current project. -->
      <useProjectArtifact>false</useProjectArtifact>
    </dependencySet>

    <dependencySet>
      <outputDirectory></outputDirectory>
      <outputFileNameMapping>maven-assembly-plugin.jar</outputFileNameMapping>
      <!-- This will include only the current project. -->
      <includes>
        <include>${project.groupId}:${project.artifactId}</include>
      </includes>
    </dependencySet>
  </dependencySets>

</assembly>

Identifiant

La balise id permet de spécifier un identifiant de la configuration. Ceci peut être pratique lorsque la valeur true est spécifiée dans le noeud appendAssemblyId de référencement du plugin.

Pour les cas simples, cet identifiant n'est pas très important.

Format

La balise format permet de spécifier le format de la distribution. Pour cet exemple, seul le format tar.gz est spécifié. Mais il serait possible d'en configurer plusieurs, entraînant la configuration de plusieurs distributions.

Contenu

3 fileSet sont mis en place.

Le premier permet de copier tous les fichiers src/main/config vers le sous répertoire config.

    <fileSet>
      <directory>src/main/config</directory>
      <outputDirectory>config</outputDirectory>
      <includes>
        <include>*</include>
      </includes>
    </fileSet>

Le second permet de copier tous les fichiers src/main/filtered.config vers le sous répertoire config, mais avec remplacement des variables, grace à la valeru true dans la balise filtered.

    <fileSet>
      <directory>src/main/filtered.config</directory>
      <outputDirectory>config</outputDirectory>
      <includes>
        <include>*</include>
      </includes>
      <filtered>true</filtered>
    </fileSet>

Ainsi pour cet exemple, le contenu du fichier version_resources.properties sera modifié pour injecter le numéro de version du projet.

version=${project.version}

Enfin le troisième est spécifique pour des scripts contenu dans le répertoire src/main/scripts. La valeur de la balise outputDirectory est laissée à vide, permettant de placer les copies à la racine de la distribution.

    <fileSet>
      <directory>src/main/scripts</directory>
      <outputDirectory></outputDirectory>
      <includes>
        <include>*.sh</include>
      </includes>
      <fileMode>0744</fileMode>
      <lineEnding>unix</lineEnding>
    </fileSet>

A noter la définition de la balise include pour ne prendre que les fichiers avec l'extension sh. De plus, la balise lineEnding permet de forcer le format Unix, et la balise fileMode de spécifier les permissions à destination d'un environnement Unix.

Librairies

Enfin, la section dependencySets va permettre d'organiser les librairies dans la distribution.

La première définition indique simplement de copier tous les dépendances dans le sous répertoire libs. Le project est échappé gràce à la valeur false dans la balise useProjectArtifact.

    <!-- All dependencies go in sub folder libs. -->
    <dependencySet>
      <outputDirectory>libs</outputDirectory>
      <!-- Exclude the current project. -->
      <useProjectArtifact>false</useProjectArtifact>
    </dependencySet>

La seconde va permettre de copier uniquement le projet compilé à la racine de la distribution.

    <dependencySet>
      <outputDirectory></outputDirectory>
      <outputFileNameMapping>maven-assembly-plugin.jar</outputFileNameMapping>
      <!-- This will include only the current project. -->
      <includes>
        <include>${project.groupId}:${project.artifactId}</include>
      </includes>
    </dependencySet>
  </dependencySets>

Le filtre s'effectue en spécialisant les inclusions à l'aide de la balise include.

De plus, le nom de la librairie est forcée avec la valeur maven-assembly-plugin.jar définie dans la balise outputFileNameMapping.

Exécution

La génération de la distribution s'effectue avec la commande package

#mvn clean package -DskipTests=true
.
.
.
[INFO] --- maven-assembly-plugin:3.1.0:single (distribution-by-assembly) @ maven-assembly-plugin ---
[INFO] Reading assembly descriptor: src/main/assembly/assembly-config.xml
[INFO] Building tar: C:\workspaces\studyMaven\maven-assembly-plugin\target\maven-assembly-plugin-0.0.1-SNAPSHOT.tar.gz
.
.
.

Pour cette exécution, les tests unitaires sont échappés. La console indique la génération de l'archive à l'emplacement target\maven-assembly-plugin-0.0.1-SNAPSHOT.tar.gz.

Autres configurations

Nom fichier distribution

Par défaut, le nom du fichier généré est similaire à celui du paquet généré, soit par exemple maven-assembly-plugin-0.0.1-SNAPSHOT.tar.gz. Il peut être souhaité de forcer le nom du fichier à l'aide de la balise finalName dans la section configuration de la déclaration du plugin. L'exemple suivant permet de générer la distribution dans le fichier finalDistribution.tar.gz, l'extension étant prise depuis la définition de l'assembly.

      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-assembly-plugin</artifactId>
        <version>3.1.0</version>
        <executions>
          <execution>
            <id>distribution-by-assembly</id>
            <phase>package</phase>
            <goals>
              <goal>single</goal>
            </goals>
            <configuration>
              <descriptors>
                <descriptor>src/main/assembly/assembly-config.xml</descriptor>
              </descriptors>
              <appendAssemblyId>false</appendAssemblyId>
              <finalName>finalDistribution</finalName>
            </configuration>
          </execution>
        </executions>        
      </plugin>

Modification répertoire racine

Par défaut, le répertoire racine de la distribution correspond au nom du projet, soit par exemple maven-assembly-plugin-0.0.1-SNAPSHOT pour le projet example. IL peut être souhaité de modifier ce nom de répertoire à l'aide de la balise baseDirectory dans la définition de la distribution.

L'exemple suivant permet d'annuler le répertoire racine dans la distribution.

<assembly
  xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 http://maven.apache.org/xsd/assembly-1.1.3.xsd">

  <id>assembly-study</id>
  
  <baseDirectory></baseDirectory>

  .
  .
  .

</assembly>

Le second exemple permet d'annuler de forcer le nom du répertoire avec la valeur root.

<assembly
  xmlns="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/plugins/maven-assembly-plugin/assembly/1.1.3 http://maven.apache.org/xsd/assembly-1.1.3.xsd">

  <id>assembly-study</id>
  
  <baseDirectory>root</baseDirectory>

  .
  .
  .

</assembly>

Voir aussi

Documentation officielle: https://maven.apache.org/plugins/maven-assembly-plugin/