[repository specification](repository.html) | [reference](reference.html) | [tutorial](tutorial.html) Packaging Java and Maven projects with Maven Repo Helper ======================================================== The maven-repo-helper package provides tools for installing and maintaining Maven POMs and jars installed in /usr/share/maven-repo. Maven is a comprehensive build tool for Java and other languages based around the concept of plugins and a repository accessible normally from internet (a la CPAN), and providing access to the libraries used by a project. To satisfy the requirement that all software must be built from the Debian repository and that no access to Internet is allowed during a build, we have re-created a Maven repository for Debian. This repository is located in /usr/share/maven-repo and Maven POM files installed there must follow some special requirements. The Debian policy mandates that Java libraries are installed in /usr/share/java, so we have many Java libraries have already been packaged in Debian, but they don't have any Maven descriptors (POMs) associated with them. maven-repo-helper can help by installing those libraries also in /usr/share/maven-repo with their POM files. The Maven repository maintained by Debian has some special characteristics which make it difficult to use directly upstream POM files without any changes. To allow a smooth upgrade of Java libraries, we create both native and Debian versions of the artifacts, and replace all versions in the dependencies with Debian versions - see the [repository specification](repository.html) document for more informations about this process. In addition, entries in the POM file which are not needed anymore, such as build information, are removed. mh\_make provides the scripts mh\_patchpom and mh\_cleanpom which patch dependencies versions and clean up the POM file respectively. Other scripts often make use of those two scripts to provide more advanced functionality. maven-repo-helper has no dependency on Maven, so it can be used for any library, including libraries used by Maven itself. It provides the foundations for maven-debian-helper. Its goal is to manage the /usr/share/maven-repo folder properly, and cannot be used alone to build a Java library from source. You will normally use it either with Ant (started by a cdbs rule or dh 7 rule or anything you like), or with javahelper which will take care of building the binaries for your project. **Important:** If you want your build to use Maven itself, then run mh\_make from the maven-debian-helper package on the upstream sources. mh\_make will guide you for that process and generate all necessary debian files for you. You can also use mh\_make --ant to speed up the packaging of a project which uses Ant as the build tool and needs to install its artifacts into the Maven repository. Quick start =========== This section presents some of the recommanded packaging styles: DH 7 + Ant + maven-repo-helper ------------------------------ The build uses dh 7 style, it runs Ant for the build and uses maven-repo-helper to install all jars both in /usr/share/java and in /usr/share/maven-repo with the POM files. debian/control: Source: bnd Section: java Priority: optional Maintainer: Debian Java Maintainers Uploaders: Ludovic Claude Build-Depends: debhelper (>= 8), maven-repo-helper (>= 1.7), default-jdk Build-Depends-Indep: junit, libosgi-ee-minimum-api-java (>= 1.2.1) Standards-Version: 3.9.2 Homepage: http://www.aqute.biz/Code/Bnd Package: bnd Architecture: all Depends: ${misc:Depends} Description: A tool to create and diagnose OSGi R4 bundles [...] Note the Build-Depends on debhelper and maven-repo-helper debian/rules: #!/usr/bin/make -f export JAVA_HOME=/usr/lib/jvm/default-java %: dh $@ --buildsystem=ant --with maven_repo_helper We use here dh 7 for the build, with ant as the build system, and the maven_repo_helper plugin which will install all generated artifacts in the Maven repository. Ant is run with the upstream build.xml file and the default target. bnd.poms: biz.aQute.bndlib/tmp/pom.xml --has-package-version --artifact=biz.aQute.bndlib/tmp/biz.aQute.bndlib.jar --java-lib --usj-name=bndlib Deploy the jar built in biz.aQute.bndlib/tmp folder (--artifact option) as bndlib.jar (--usj-name option) in /usr/share/java (--java-lib option) and deploy it as well in the Maven repository. We use the POM file created by the build (biz.aQute.bndlib/tmp/pom.xml) as it contains the metadata for the bndlib jar. The option --has-package-version tells maven-repo-helper that the version of the POM matches the version of the Debian package, which is a useful hint for mh\_make when packaging another project which uses this library. maven.rules: biz.aQute s/bnd/bndlib/ Change the name of the artifact from bnd to bndlib in the Maven POM. The current version of bndlib will be replaced by a generic 'debian' version. You can use mh\_lspoms from the maven-debian-helper package to help you locate POM files in your sources and generate both the .poms and maven.rules files. DH 7 + Ant + maven-ant-helper + maven-repo-helper ------------------------------------------------- A variant of the previous solution, where we don't use the upstream build script, but an Ant script which works on something which looks like a Maven project and tries to emulate Maven as best as it can. This is quite handy when you are working on a package used by Maven itself and cannot use Maven during the build. debian/control: Source: plexus-utils2 Section: java Priority: optional Maintainer: Debian Java Maintainers Uploaders: Ludovic Claude Build-Depends: debhelper (>= 7), default-jdk, maven-repo-helper (>= 1.7), ant-optional, maven-ant-helper (>= 7) Build-Depends-Indep: libplexus-parent-java (>= 2.0.6), junit (>= 3.8.2), default-jdk-doc Standards-Version: 3.9.2 Vcs-Svn: svn://svn.debian.org/svn/pkg-java/trunk/plexus-utils2 Vcs-Browser: http://svn.debian.org/wsvn/pkg-java/trunk/plexus-utils2 Homepage: http://plexus.codehaus.org/plexus-utils Package: libplexus-utils2-java Architecture: all Depends: ${misc:Depends}, libplexus-parent-java (>= 2.0.6) Suggests: libplexus-utils2-java-doc Description: Plexus Common Utilities [...] Package: libplexus-utils2-java-doc Architecture: all Section: doc Depends: ${misc:Depends}, default-jdk-doc Suggests: libplexus-utils2-java Description: Documentation for Plexus Common Utilities [...] We define a binary package which will contain the jars and the fragment of the Maven repository for this package (libplexus-utils2-java), and a documentation package containing the Javadoc folder (installed in /usr/share/doc) and the Javadoc jar installed in the Maven repository (libplexus-utils2-java-doc). Note the Build-Depends on debhelper, maven-repo-helper and maven-ant-helper. debian/rules: #!/usr/bin/make -f DEB_SOURCE_PACKAGE := $(shell dpkg-parsechangelog | grep '^Source:' | cut -f 2 -d ' ') DEB_UPSTREAM_VERSION := $(shell dpkg-parsechangelog | egrep '^Version:' | cut -f 2 -d ' ' | cut -d: -f2- | sed 's/-[^-]*$$//') export JAVA_HOME=/usr/lib/jvm/default-java export CLASSPATH=$(shell for jar in `cat debian/build-classpath`; do if [ -f "$$jar" ]; then echo -n "$${jar}:"; fi; done) export ANT_ARGS=-Dbasedir=$(realpath .) -Dpackage=$(DEB_SOURCE_PACKAGE) -f /usr/share/maven-ant-helper/maven-build.xml %: dh $@ --buildsystem=ant --with maven_repo_helper We use here dh 7 for the build, with ant as the build system, and the maven\_repo\_helper plugin which will install all generated artifacts in the Maven repository We configure ant to use the maven-ant-helper build script (/usr/share/maven-ant-helper/maven-build.xml) and the classpath defined in debian/build-classpath libplexus-utils2-java.poms: pom.xml --has-package-version --artifact=target/plexus-utils-*.jar --java-lib --usj-name=plexus-utils2 Install the jar as plexus-utils2.jar (--usj-name option) in /usr/share/java (--java-lib option) and install it as well in /usr/share/maven-repo with its POM file. The jar is coming from the target/ folder used by Maven (and the maven-repo-helper script) for its builds, and we use a glob pattern (*) to match any version of the jar (--artifact option). The option --has-package-version tells maven-repo-helper that the version of the POM matches the version of the Debian package, which is a useful hint for mh\_make when packaging another project which uses this library. libplexus-utils2-java-doc.poms: target/plexus-utils.javadoc.pom --has-package-version --artifact=target/plexus-utils.javadoc.jar --classifier=javadoc --ignore-pom Install the javadoc jar into /usr/share/maven-repo, without a POM file (--ignore-pom option) because that's the way Maven works - javadoc jars have no dedicated POM files for them. Instead, there is a classifier which tells Maven that this jar contains Javadoc (--classifier option). The javadoc jar is packaged in libplexus-utils2-java-doc package. libplexus-utils2-java-doc.install: target/apidocs/* usr/share/doc/libplexus-utils2-java/api Install the javadoc folder into /usr/share/doc/libplexus-utils2-java/api. This folder is packaged in libplexus-utils2-java-doc package. maven.rules: junit junit jar s/3\..*/3.x/ * * org.codehaus.plexus plexus-utils jar s/2\..*/2.x/ * * org.codehaus.plexus plexus pom s/2\..*/2.x/ * * Adapt versions for Debian in the Maven POMs, as it ease small upgrades. - junit:junit jar dependencies with a version starting with 3. will use version 3.x instead (and libjunit-java contains a similar rule which install version 3.x in the Maven repository) - org.codehaus.plexus:plexus-utils jar dependencies with a version starting with 2. will use version 2.x instead - org.codehaus.plexus:plexus pom dependencies with a version starting with 2. will use version 2.x instead DH 7 + javahelper + maven-repo-helper ------------------------------------- debian/control: Source: httpunit Maintainer: Debian Java Maintainers Uploaders: Miguel Landaeta , Michael Koch Section: java Priority: optional Build-Depends: default-jdk, ant (>= 1.7.0-6), javahelper (>= 0.28), debhelper (>= 7.0.50~), rhino (>= 1.7R1-2), libjtidy-java (>= 7+svn20070309-2), libgnujaf-java (>= 1.1.1-4), junit (>= 3.8.2), libgnumail-java (>= 1.1.2-2), libservlet2.4-java (>= 5.0.30-8), libxerces2-java (>= 2.9.1-2), libnekohtml-java (>= 0.9.5+dfsg-1.1), maven-repo-helper (>= 1.7) Standards-Version: 3.9.2 Homepage: http://httpunit.org/ Vcs-Browser: http://svn.debian.org/wsvn/pkg-java/trunk/httpunit/ Vcs-Svn: svn://svn.debian.org/svn/pkg-java/trunk/httpunit Package: libhttpunit-java Architecture: all Section: java Priority: optional Depends: ${java:Depends}, libxerces2-java (>= 2.9.1-2), libnekohtml-java (>= 0.9.5+dfsg-1.1), rhino (>= 1.7R1-2), libjtidy-java (>= 7+svn20070309-2), libservlet2.4-java (>= 5.0.30-8), ${misc:Depends} Recommends: junit (>= 3.8.2) Suggests: libhttpunit-java-doc (= ${binary:Version}) Description: automated web site testing toolkit [...] Note the Build-Depends on debhelper, javahelper, ant and maven-repo-helper debian/rules: #!/usr/bin/make -f %: dh --with javahelper --with jh_maven_repo_helper $@ We use here dh 7 for the build, with javahelper as the build system (which in turn will launch Ant because build.xml exists), and the jh\_maven\_repo\_helper plugin which is adapted to work with javahelper and will install all generated artifacts in the Maven repository. libhttpunit-java.jlibs: lib/httpunit.jar We tell javahelper to install the httpunit.jar file located in lib into /usr/share/java libhttpunit-java.poms: debian/pom.xml --usj-name=httpunit Create a link for the jar /usr/share/java/httpunit.jar into the Maven repository and use debian/pom.xml as its companion metadata file CDBS + maven-repo-helper using mh\_install ----------------------------------------- debian/control: Source: maven-debian-helper Section: java Priority: optional Maintainer: Debian Java Maintainers Uploaders: Torsten Werner , Ludovic Claude , Michael Koch , Damien Raude-Morvan Build-Depends: cdbs, debhelper (>= 7), default-jdk, maven-ant-helper (>= 7), maven-repo-helper (>= 1.7), ant-optional, help2man Build-Depends-Indep: junit, libmaven-plugin-tools-java, libplexus-velocity-java Standards-Version: 3.9.2 Vcs-Svn: svn://svn.debian.org/svn/pkg-java/trunk/maven-debian-helper Vcs-Browser: http://svn.debian.org/wsvn/pkg-java/trunk/maven-debian-helper/ Homepage: http://wiki.debian.org/Java/MavenBuilder Package: maven-debian-helper Architecture: all Depends: ${misc:Depends}, default-jdk, maven-repo-helper (>= 1.5), maven2 (>= 2.2.1-5), libmaven-clean-plugin-java, libmaven-resources-plugin-java, libmaven-compiler-plugin-java, libmaven-jar-plugin-java, libmaven-site-plugin-java, libsurefire-java, velocity, libplexus-velocity-java Suggests: libmaven-javadoc-plugin-java, apt-file, devscripts, subversion Description: Helper tools for building Debian packages with Maven [...] Note the Build-Depends on cdbs and maven-repo-helper. maven-ant-helper and ant-optional are also needed for this package, as it's quite complex but this is not important for this tutorial. debian/rules: #!/usr/bin/make -f include /usr/share/cdbs/1/rules/debhelper.mk include /usr/share/cdbs/1/class/ant.mk PACKAGE := $(DEB_SOURCE_PACKAGE) VERSION := $(shell echo ${DEB_UPSTREAM_VERSION} | sed -r 's/([0-9\.]+).*/\1/') JAVA_HOME := /usr/lib/jvm/default-java DEB_JARS := ant-nodeps classworlds maven-core maven-artifact maven-artifact-manager maven-model \ maven-compat maven-plugin-api maven-project maven-scm-api velocity file-management plexus-utils \ plexus-container-default-alpha maven-repo-helper DEB_ANT_BUILD_TARGET := package DEB_ANT_BUILDFILE := debian/build.xml DEB_ANT_ARGS := -Dpackage=$(PACKAGE) -Dbin.package=$(PACKAGE) API_DOCS := target/api install/$(PACKAGE):: mh_install -p$(PACKAGE) clean:: mh_clean This is a simplified version of debian/rules, which shows how to use the mh\_install and mh\_clean scripts from maven-repo-helper with CDBS and Ant. mh\_install performs the installation of the built jars into /usr/share/maven-repo and /usr/share/java. It uses the configuration defined in maven-debian-helper.poms. mh\_clean does the clean up of files left behind during the execution of mh\_install. maven-debian-helper.poms: pom.xml --no-parent --has-package-version maven-debian-helper/pom.xml --has-package-version --artifact=maven-debian-helper/target/maven-debian-helper-*.jar --java-lib maven-debian-plugin/pom.xml --has-package-version --artifact=maven-debian-plugin/target/maven-debian-plugin-*.jar --java-lib maven-build-nodocs/pom.xml --has-package-version --artifact=maven-build-nodocs/target/maven-build-nodocs-*.jar --java-lib maven-packager-utils/pom.xml --has-package-version --artifact=maven-packager-utils/target/maven-packager-utils-*.jar --java-lib Here we tell mh\_install to deploy the maven-debian-helper project and its sub projects into /usr/share/maven-repo, and to deploy all jars also into /usr/share/java (--java-lib option) CDBS + maven-repo-helper using mh\_installpoms and mh\_installjar ----------------------------------------------------------------- debian/control: Source: plexus-io Section: java Priority: optional Maintainer: Debian Java Maintainers Uploaders: Torsten Werner , Ludovic Claude Build-Depends: debhelper (>= 5), cdbs (>= 0.4.5.3), default-jdk Build-Depends-Indep: maven-repo-helper (>= 1.7), maven-ant-helper (>= 7), ant, ant-optional, libplexus-utils-java, libplexus-containers-java Standards-Version: 3.8.1 Vcs-Svn: svn://svn.debian.org/svn/pkg-java/trunk/plexus-io Vcs-Browser: http://svn.debian.org/wsvn/pkg-java/trunk/plexus-io/ Homepage: http://plexus.codehaus.org/plexus-components/plexus-io/ Package: libplexus-io-java Architecture: all Depends: ${misc:Depends}, libplexus-utils-java, libplexus-containers-java Description: Plexus IO Components [...] Note the Build-Depends on cdbs and maven-repo-helper. debian/rules: #!/usr/bin/make -f include /usr/share/cdbs/1/rules/debhelper.mk include /usr/share/cdbs/1/class/ant.mk PACKAGE := $(DEB_SOURCE_PACKAGE) VERSION := $(DEB_UPSTREAM_VERSION) JAVA_HOME := /usr/lib/jvm/default-java DEB_JARS := ant-nodeps plexus-utils plexus-container-default DEB_ANT_BUILD_TARGET := package #javadoc DEB_ANT_BUILDFILE := /usr/share/maven-ant-helper/maven-build.xml DEB_ANT_ARGS := -Dbasedir=$(realpath .) -Dpackage=$(PACKAGE) -Dversion=$(VERSION) API_DOCS := build/api binary-post-install/lib$(PACKAGE)-java:: mh_installpoms -plib$(PACKAGE)-java mh_installjar -plib$(PACKAGE)-java -l pom.xml build/$(PACKAGE)-$(VERSION).jar clean:: mh_clean No patches for the POM files are needed, all is taken care of by the mh\_installpom script (which uses mh\_cleanpom) mh\_installpoms will install all POM files registered in debian/lib$package-java.pom into /usr/share/maven-repo, mh\_installjar will install the jar file associated with the POM into /usr/share/maven-repo and also add a link to the jar in /usr/share/java, with and without the version debian/libplexus-io-java.pom pom.xml --no-parent It simply lists the pom files in the source tree which need to be installed in the repository, and indicates with the --no-parent option that if the POM inherits from a parent POM, then this inheritance relationship will be removed in the cleaned POM. Removing the parent inheritence can often simplify the packaging, as the parent POM mostly does not contain any useful information - we need only the list of dependencies in our repository, the other details for the build are irrelevant. There is less configuration here because we are using the low-level mh_installpoms and mh_installjar scripts which place the configuration on their command line options. Typical workflow for packaging a project from source ---------------------------------------------------- 1. Get the original sources and unpack them, copy the debian/ folder if you are working on an existing package. 1. mh\_make --ant 1. edit debian/rules (to fix the last remaining packaging details) 1. edit debian/control (to add maven-repo-helper to Build-Depends: )