Issue
Many Java libraries have already been packaged in Debian, but they don't have any Maven descriptors (POMs) associated with them. The pkg-java team is working on a Maven builder package which helps packaging Java software built with Maven, but to work it requires that all dependencies have their Maven POMs installed in /usr/share/maven-repo.
In addition, smooth upgrade of Java libraries would imply some difficult search & replace operations in the Maven repository, unless the proposal in [Java/MavenRepoSpec|Maven Repo Specifiaction] is adopted. This proposal suggest creating a parent POM (org.debian:debian-parent) which holds installed library versions in properties. This parent POM must be the parent of all POMs, and those POMs should use the version properties for their dependencies instead of explicit version numbers.
The maven-repo-helper package aims to provide tools for installing and maintaining POMs and jars in /usr/share/maven-repo, and will have no dependency on Maven so it can be used for any library.
Features
At http://bazaar.launchpad.net/~ludovicc/uj/plexus-io/files you can find a library which uses maven-repo-helper for installing its POM and jar files in /usr/share/maven-repo.
The debian/rules contain
binary-post-install/lib$(PACKAGE)-java:: mh_installpoms -plib$(PACKAGE)-java mh_installjar -plib$(PACKAGE)-java -l pom.xml build/$(PACKAGE)-$(VERSION).jar binary-fixup/lib$(PACKAGE)-java:: mh_mavenrepo clean:: -rm -rf debian/tmp
and the Build-Depends are
Build-Depends-Indep: maven-repo-helper, maven-ant-helper, libplexus-utils-java, libplexus-container-default-java
No patches for the POM files are needed, all is taken care of by the mh_installpom script (which uses mh_cleanpom)
mh_installpom will install the POM file in /usr/share/maven-repo, mh_installjar will install the jar file in /usr/share/maven-repo and also add a link to the jar in /usr/share/java, with and without the version
Additional files which may be required are:
debian/$package.pom (for example, debian/libplexus-io-java.pom)
pom.xml --debian-parent
It simply lists the pom files in the source tree which need to be installed in the repository, and indicates with the --debian-parent option which POM files need to inherit directly from the Debian parent POM.
A more complex example from the modello package is:
pom.xml --debian-parent modello-core/pom.xml modello-test/pom.xml modello-plugins/pom.xml modello-plugins/modello-plugin-converters/pom.xml modello-plugins/modello-plugin-dom4j/pom.xml
debian/maven.spec:
org.apache.maven.*.*.debian org.apache.maven.wagon.*.*.debian org.codehaus.modello.*.*.debian
This file is taken from the modello package. It allow grouping related artifacts to use the same version once, and you can also define an alternative version from the default 'debian' version which can be used in cases where more than one version of the same library needs to be installed.
This example from the plexus-containers package contains a plexus-container-default library which needs to cohabit with the same library but with a different version defined in the package plexus-container-default. The later is associated with the 'debian' version, and the former with the 1_0_beta version. Note that version numbers need to be valid XML identifiers, so only alphanumeric characters and underscore are allowed.
org.codehaus.plexus.plexus-container-default.jar.1_0_beta org.codehaus.plexus.plexus-javadoc.jar.1_0_beta org.codehaus.plexus.plexus-containers.pom.1_0_beta org.codehaus.plexus.plexus-component-*.*.1_0_beta
Helper scripts
mh_lspoms
Usage:
ms_lspoms <binary package>
This script looks for all POM files defined in the source of the project. You need to execute it on the unpacked origianl source tree, merged with the debian/ folder. It will create the file debian/<binary package>.poms which contains all the POMs to deploy to the Maven repository and is used by dh_mavenrepo and mh_installpoms.
The contents of debian/<binary package>.poms should be:
- one POM file location per line,
- optionaly, the location is followed by the option --debian-parent to indicate that this POM should inherit directly from the Debian parent POM. All POMs which are installed in the Maven repository should inherit either directly or indirectly from org.debian:debian-parent:1.0-SNAPSHOT
mh_cleanpom
Usage:
mh_cleanpom [-d|--debian-parent] <pom>
This script cleans the original Maven POM, removes all unecessary elements, and replaces version numbers in dependencies by properties. It will also force the POM to inherit from org.debian:debian-parent:1.0-SNAPSHOT.
debian/maven.spec is used to alter the version properties for the library and its dependencies.
It is used by mh_installpom, normally you don't need to use it directly, except if you need to investigate an issue with the cleaning process for a POM file.
mh_installpom
Usage:
mh_installpom [-d|--debian-parent] [-s<spec>|--spec <spec>] -p<package> <pom>
This script installs the POM file in /usr/share/maven-repo, at the correct location for Maven. Before installing the POM, it prepares it with mh_cleanpom.
debian/maven.spec is used to alter the version properties for the library and its dependencies.
Prefer to use mh_installpoms as it reuses the information in debian/$package.poms and avoids repetition.
mh_installpoms
Usage:
mh_installpoms -p<package>
This script reads the file debian/$package.poms and installs each POM file listed in the .poms file.
mh_installjar
Usage:
mh_installjar -p<package>|--package=<package> [-s<spec>|--spec <spec>] [-l|--java-lib] [-n<name>|--name=<name>] [-r<version>|--version=<version>] <pom> <jar> [link1 link2...]
where
<pom> is the location of the POM associated with the jar to install. ?GroupId, artifactId and version will be extracted from this file.
<jar> is the path to the jar to install, usually located in the build/ folder
link<n> is an additional link to the jar to install, usually there should be a link to usr/share/java/$jar.jar and usr/share/java/$jar-$version.jar to comply with the Java packaging guidelines. There is no need to specify those links if the --java-lib option is used.
and options are:
- -p | --package: package to act on
- -s | --spec: gives the location of the Maven spec file for special properties. Optional, the default location is debian/maven.spec
- -l | --java-lib: Optional, if given it will create additional links into /usr/share/java to comply with the Java specification. More precisely, the links created will be /usr/share/java/$name-$version.jar and /usr/share/java/$name.jar
- -n | --name: Optional, the name to use when installing the library in /usr/share/java when --java-lib is used. Defaults to the artifact id found in the POM.
- -r | --version: Optional, the version to use when installing the library in /usr/share/java when --java-lib is used. Defaults to the version found in the POM.
This script installs the jar file in /usr/share/maven-repo, at the correct location for Maven. It can also create additional links to the jar, usually placed in /usr/share/java.
mh_mavenrepo
Usage:
mh_mavenrepo
This script generates the postinst and postrm scripts which are used to update the version properties in the Debian parent POM.
It uses the file debian/$package.poms to locate the POMs to install, and optionally debian/maven.spec to alter the version properties defined in Debian parent POM.
TODO: It may also provide ${java:Depends} substitution variables.
mh_genrules
Usage:
mh_genrules [-a|--use-ant] <binary package>
This script generates a skeleton for the debian/rules file which includes the installation of POMs and jars into the Maven repository. You need to execute it on the unpacked origianl source tree, merged with the debian/ folder. The -a or --use-ant option tries to configure Ant to build the library.
If debian/rules existed already, the generated file will be placed in debian/rules.new and you will have to merge it manually.
Typical workflow
- Get the original sources and unpack them, copy the debian/ folder if you are working on an existing package.
mh_lspoms <package>
- edit debian/$package.poms (to check that only the POM that are needed are present, and maybe to fix the --debian-parent options)
- mh_genrules -a
- edit debian/rules (to fix the last remaining packaging details)
- edit debian/control (to add maven-repo-helper to Build-Depends: )