Distribuer une librairie via maven

TUTORIEL www.antislashn.org
Distribuer une librairie via un dépôt Maven
Objectifs
Une fois une librairie Java au point, il est intéressant de la mettre à disposition d'autres
développeurs.
Pour cela les dépôts Maven sont tout indiqués.
Ce tuto explique comment :
• créer son projet pour qu'il soit accepté dans un dépôt Maven officiel
• comment s'enregistrer auprès d'un dépôt Maven
• comment déployer sa librairie dans le dépôt Maven
Le déploiement sera effectué dans le dépôt OSSRH (Open Source Software Repository Hosting),
prévu pour accueillir les projets individuels.
Prérequis
• Avoir un groupId qui identifie vos projets de manière unique. Il s'agit de votre nom de
domaine. La convention de nommage du groupId est la même que pour les packages Java :
utiliser le nom de domaine à l'envers.
▪ www.springframework.org → org.springframework
▪ antislashn.org → org.antislashn
◦ si vous n'avez pas de nom de domaine vous pouvez utiliser l'adresse github de votre
projet
▪ io.github.username
• Le nom du projet devient l'artifactId, tout en minuscule, en utilisant le tiret - comme
séparateur de mots
◦ mon-projet
• Numéroter les versions, au format X.Y.Z, où X, Y, et Z sont des entiers, séparés par un point.
Chaque entier s'incrémentant au fil des mises à jours des versions
◦ X : identifiant de version majeure
◦ Y : identifiant de version mineure
◦ Z : identifiant de version de correction
•
Franck SIMON Titre 1/15
franck.simon@antislashn.org 14/05/2019 - version 1.0
n

• L'ensemble de ces informations permettra de créer un dépendance du type :
<dependency>
<groupId>com.example.applications</groupId>
<artifactId>example-application</artifactId>
<version>1.4.7</version>
</dependency>
n

Inscription auprès de OSSRH
• cf. https://central.sonatype.org/pages/ossrh-guide.html
• vous devez :
◦ créer un compte JIRA
▪ https://issues.sonatype.org/secure/Signup!default.jspa
◦ créez un ticket décrivant votre projet et votre organisation
▪ si vous avez un domaine, il vous sera demandé de prouver que ce domaine vous
appartient
▪ vous devrez renseigner
• le group Id
• l'URL git du projet
• adresse mail
• description du projet
• tags
◦ vous serez suivi par un responsable qui communiquera avec vous via les commentaires
sur le projet
◦ tant que votre projet ne sera pas marqué comme résolu, vous ne pourrez pas le déployer
n

Préparation du projet pour le déploiement
En plus du jar de votre projet vous devez fournir
• la javadoc des classes
• les sources des classes
• le fichier pom.xml
Convention de nommage des fichiers à fournir.
Les exemples sont basés sur les prérequis suivants :
• groupId : com.example.application
• artifiactId : example-application
• version : 1.4.7
Fichiers à fournir :
• example-application-1.4.7.jar construit par Maven
• example-application-1.4.7-sources.jar construit par le plugin Maven
• example-application-1.4.7-javadoc.jar construit par le plugin Maven
• example-application-1.4.7.pom créé par Maven lors du déploiement
Les archives pour la javadoc et les sources peuvent être construits automatiquement en ajoutant les
plugins suivants dans le pom.xml de votre projet
Pour les sources :
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
<executions>
<execution>
<id>attach-sources</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
n

Pour la javadoc :
<plugin>
<artifactId>maven-javadoc-plugin</artifactId>
<executions>
<execution>
<id>attach-javadocs</id>
<goals>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
Le fichier pom.xml de votre projet doit contenir les métas données suivantes :
(cf. https://github.com/simpligility/ossrh-demo/blob/master/pom.xml )
• coordonnées du projet, appelées GAV
◦ groupId, artifactId, version
<groupId>com.simpligility.training</groupId>
<artifactId>ossrh-demo</artifactId>
<version>1.0</version>
<packaging>jar</packaging>
• le nom du projet, sa description et l'URL
<name>ossrh-demo</name>
<description>A demo for deployment via OSSRH</description>
<url>http://github.com/simpligility/ossrh-demo</url>
• le type de licence
<licenses>
<license>
<name>The Apache Software License, Version 2.0</name>
<url>http://www.apache.org/licenses/LICENSE-2.0.txt</url>
</license>
</licenses>
• les informations sur les développeurs
<developers>
<developer>
<name>Manfred Moser</name>
<email>manfred@sonatype.com</email>
<organization>Sonatype</organization>
<organizationUrl>http://www.sonatype.com</organizationUrl>
</developer>
</developers>
n

• Les informations SCM (Software Configuration Management)
<scm>
<connection>
scm:git:git://github.com/simpligility/ossrh-demo.git
</connection>
<developerConnection>
scm:git:ssh://github.com:simpligility/ossrh-demo.git
</developerConnection>
<url>http://github.com/simpligility/ossrh-demo/tree/master</url>
</scm>
• Les éventuelles dépendances, exclusions, plugin, ...
Les quatre fichiers doivent être signés par PGP.
• si nécessaire, téléchargez GnuPG
◦ https://www.gnupg.org/download/
• générez un paire de clés
◦ gpg --gen-key
◦ laisser RSA par défaut
◦ choisir une longueur de clé de 2048
◦ la durée préconisée est de 2 ans
◦ ensuite entrez les détails demandés
• signature d'un fichier
◦ gpg -ab mon-fichier.java
▪ -a spécifie un fichier de signature ASCII
▪ -b demande un fichier de signature détaché
◦ un fichier mon-fichier.java.asc est généré
• vérifier le fichier des clés
◦ gpg2 --list-keys
• distribuer la clé publique
gpg2 --keyserver hkp://pool.sks-keyservers.net --send-keys C6EED57A
◦ la clé privée signera les différents fichiers
◦ la clé publique permettra de vérifier que vous êtes bien à l'origine de ces signatures
• ATTENTION
◦ la distribution de la clé publique peut prendre du temps (plusieurs jours pour être
propagée sur tous les serveurs), pour vérifier qu'elle est accessible :
gpg2 --keyserver hkp://pool.sks-keyservers.net --recv-keys C6EED57A
n

◦ il faut que la clé publique soit accessible pour que la distribution de votre librairie soit
complètement effective
◦ sinon une erreur de vérification de clé interdira le passage dans le dépôt public
• https://central.sonatype.org/pages/releasing-the-deployment.html
Signer les fichiers avec Maven
• utilisez le plugin maven-gpg-plugin
<plugin>
<artifactId>maven-gpg-plugin</artifactId>
<executions>
<execution>
<id>sign-artifacts</id>
<phase>verify</phase>
<goals>
<goal>sign</goal>
</goals>
</execution>
</executions>
</plugin>
• pour déployer (cf. page suivante)
◦ mvn clean deploy -Dgpg.passphrase=yourpassphrase
• ou par Eclipse via le menu contextuel
n

Déployer dans un dépôt local
Les premiers tests de déploiement peuvent se faire dans un dépôt local
Dans le pom.xml du projet ajoutez
• une propriété pour l'URL de déploiement
◦ plus simple à gérer lorsqu'il faudra changer cette URL
<repository.url>file:///home/user/tmp</repository.url>
• dans l'élément <build> l'extension maven-wagon
◦ https://maven.apache.org/wagon/
<extensions>
<extension>
<groupId>org.apache.maven.wagon</groupId>
<artifactId>wagon-http</artifactId>
</extension>
</extensions>
• élément pour la destination du déploiement
<distributionManagement>
<repository>
<id>org.antislashn.maven</id>
<name>antislashn maven</name>
<url>${repository.url}</url>
</repository>
</distributionManagement>
Vous pouvez tester le bon déroulement du déploiement avec un goal "deploy".
Normalement vous devez avoir une suite de répertoires qui ont été créés. Ces répertoire
correspondent à vos groupId, artifactId et version.
Le répertoire de la version contient l'ensemble des fichiers.
Exemple page suivante.
n

Pour utiliser votre dépôt local, l'application cliente de votre librairie doit ajouter à son pom.xml
• la dépendance vers votre librairie
◦ exemple :
<dependency>
<groupId>com.example.applications</groupId>
<artifactId>example-application</artifactId>
</dependency>
• le dépôt où se trouve la librairie
<repositories>
<repository>
<id>com.example.applications.maven</id>
<name>example maven</name>
<url>file:///home/user/tmp</url>
</repository>
</repositories>
n

Déploiement dans un dépôt "officiel" Maven
Pour cela vous devez prendre un compte OSSRH
cf. https://central.sonatype.org/pages/ossrh-guide.html#deployment
• créez un compte JIRA
◦ https://issues.sonatype.org/secure/Signup!default.jspa
• puis créez un demande (ticket)
◦ https://issues.sonatype.org/secure/CreateIssue.jspa?issuetype=21&pid=10134
◦ pour prouver que le domaine que vous utilisez vous appartient bien, vous devrez ajouter
un champ TXT à votre référencement DNS
▪ la valeur de ce champ est l'URL de votre demande
Ensuite modifiez votre pom.xml
• pour ajouter le plugin de déploiement vers OSSRH
<plugin>
<groupId>org.sonatype.plugins</groupId>
<artifactId>nexus-staging-maven-plugin</artifactId>
<extensions>true</extensions>
<configuration>
<serverId>ossrh</serverId>
<nexusUrl>https://oss.sonatype.org/</nexusUrl>
<autoReleaseAfterClose>true</autoReleaseAfterClose>
</configuration>
</plugin>
• ou modifiez votre <distributionManagement>
<distributionManagement>
<snapshotRepository>
<id>ossrh</id>
<url>https://oss.sonatype.org/content/repositories/snapshots</url>
</snapshotRepository>
<repository>
<id>ossrh</id>
<url>https://oss.sonatype.org/service/local/staging/deploy/maven2/</url>
</repository>
</distributionManagement>
n

Quelque soit la configuration choisie vous devez ajouter un fichier Maven settings.xml qui
contiendra vos identifiant et mot de passe
• ce fichier settings.xml doit être positionné :
◦ dans le répertoire ${maven.home}/conf/settings.xml
◦ ou dans le répertoire de l'utilisateur ${user.home}/.m2/settings.xml
<settings>
<servers>
<server>
<id>ossrh</id>
<username>your-jira-id</username>
<password>your-jira-pwd</password>
</server>
</servers>
</settings>
Le déploiement s'effectue comme d'habitude
mvn clean deploy
Vous devriez voir dans les logs de maven le bon déroulement de l'opération
n

Utiliser Nexus Repository Manager
• l'objectif est de rendre disponible votre bibliothèque sur https://repo1.maven.org et
http://search.maven.org
• le déploiement précédant à entreposé votre bibliothèque dans le référentiel de transfert
◦ OSSRH
• votre clé publique doit avoir été publiée et vous devez vous assurer qu'elle est accessible
gpg2 --keyserver hkp://pool.sks-keyservers.net --recv-keys C6EED57A
• une fois connecté à OSSRH
◦ retrouvez votre repository dans la liste des "Staging Repositories"
◦ sélectionnez-le
◦ cliquez sur le bouton "Close"
▪ vérifiez qu'il n'y ait pas d'erreur
▪ s'il y en a, vous pouvez supprimer votre dépôt, corriger l'erreur et renvoyer votre
projet vers le dépôt
▪ attention aux erreurs de clé publique, attendez alors que votre clé soit accessible
avant de renvoyer le projet
◦ s'il n'y a aucune erreur alors :
▪ cliquez sur "Refresh"
▪ puis sur "Release"
• s'il s'agit du premier envoi vers le dépôt, laissez un message sur le ticket ouvert
pour votre projet pour préciser que cette première étape est finie.
▪ votre projet est maintenant disponible sur le dépôt https://repo1.maven.org/
n

• votre bibliothèque est maintenant disponible dans le repository Maven
◦ modifiez le README.md pour indiquer la dépendance Maven à utiliser
◦ pour l'utiliser ajoutez dans vos projets la dépendance adéquate
▪ exemple de dépendance
<dependency>
<groupId>votre-groupid</groupId>
<artifactId>votre-artifactid</artifactId>
<version>version</version>
</dependency>
n

Problèmes potentiels
La clé n'est pas reconnue lorsque le projet est déployé vers le dépôt officiel maven
• il est possible de passer par http://pool.sks-keyservers.net:11371 pour
◦ déployer la clé au format asc
gpg --armor --export you@example.com > mykey.asc
◦ vérifier que la clé publique est bien déployée
◦ serveurs utilisés :
▪ http://keyserver.ubuntu.com:11371/
▪ http://keys.gnupg.net:11371
▪ http://pool.sks-keyservers.net:11371/
n

Ressources
• documentation Maven
◦ https://maven.apache.org/
• gestion sémantique de version
◦ https://semver.org/lang/fr/spec/v1.0.0.html
• configurations
◦ https://central.sonatype.org/pages/requirements.html
◦ https://bitbucket.org/simpligility/ossrh-pipeline-demo/src
◦ https://github.com/simpligility/ossrh-demo/blob/master/pom.xml
• déploiement
◦ https://central.sonatype.org/pages/ossrh-guide.html#deployment
◦ http://weibeld.net/java/publish-to-maven-central.html
• PGP
◦ https://access.redhat.com/documentation/en-
US/Red_Hat_Enterprise_Linux/4/html/Step_by_Step_Guide/s1-gnupg-export.html
◦
n

Distribuer une librairie via maven

Recommandé

Recommandé

Contenu connexe

Tendances

Tendances (20)

Similaire à Distribuer une librairie via maven

Similaire à Distribuer une librairie via maven (20)

Plus de Franck SIMON

Plus de Franck SIMON (18)

Distribuer une librairie via maven