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:

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

and options are:

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

  1. Get the original sources and unpack them, copy the debian/ folder if you are working on an existing package.
  2. mh_lspoms <package>

  3. edit debian/$package.poms (to check that only the POM that are needed are present, and maybe to fix the --debian-parent options)
  4. mh_genrules -a
  5. edit debian/rules (to fix the last remaining packaging details)
  6. edit debian/control (to add maven-repo-helper to Build-Depends: )