Translation(s): English

Maven

Maven is a framework with several different plugins and mainly used as a project management tool. Maven uses conventions. Every Maven project looks very similar since source and compiled code is located in the same places. Maven is declarative and all information are stored in pom.xml files.

mh_make

The mh_make helper tool must be run manually and it is located in the maven-debian-helper package. If executed in the root directory of the upstream sources, it is capable of producing a complete debian directory. The idea is to almost automate Maven packaging. Currently the tool has some flaws. Build-dependencies and Maven plugins must be installed on the system before mh_make is run. It happens quite frequently that the tool fails to produce a complete debian directory.

It is recommended to use it but extra work is required to finalize the Debian package. In most cases it makes sense to model a new package after already existing ones.

Blog article about how to use mh_make video tutorial in French

libtwelvemonkeys-java

libtwelvemonkeys-java is a rather simple Maven-based Java library. The most important Java specific files are libtwelvemonkeys-java.poms, maven.rules, maven.ignoreRules and maven.properties.

debian/maven.properties:

The maven.properties file can be used to override values of variables inside pom.xml files. The most common use case is to disable or enable the tests with:

maven.test.skip=true

Other options include changing the source/target level or the file encoding.

project.build.sourceEncoding=UTF-8
maven.compiler.source=1.5
maven.compiler.target=1.5

maven.rules and maven.ignoreRules:

Those files are for changing Maven coordinates in pom files without having to patch them. The most important use case is changing the artifact version to the unversioned debian. The specification is explained in more detail inMavenRepoHelper.

libtwelvemonkeys-java.poms:

# List of POM files for the package
# Format of this file is:
# <path to pom file> [option]*
# where option can be:
#   --ignore: ignore this POM and its artifact if any
#   --ignore-pom: don't install the POM. To use on POM files that are created
#     temporarily for certain artifacts such as Javadoc jars. [mh_install, mh_installpoms]
#   --no-parent: remove the <parent> tag from the POM
#   --package=<package>: an alternative package to use when installing this POM
#      and its artifact
#   : to indicate that the original version of the POM is the same as the upstream part
#      of the version for the package.
#   --keep-elements=<elem1,elem2>: a list of XML elements to keep in the POM
#      during a clean operation with mh_cleanpom or mh_installpom
#   --artifact=<path>: path to the build artifact associated with this POM,
#      it will be installed when using the command mh_install. [mh_install]
#   --java-lib: install the jar into /usr/share/java to comply with Debian
#      packaging guidelines
#   --usj-name=<name>: name to use when installing the library in /usr/share/java
#   --usj-version=<version>: version to use when installing the library in /usr/share/java
#   --no-usj-versionless: don't install the versionless link in /usr/share/java
#   --dest-jar=<path>: the destination for the real jar.
#     It will be installed with mh_install. [mh_install]
#   --classifier=<classifier>: Optional, the classifier for the jar. Empty by default.
#   --site-xml=<location>: Optional, the location for site.xml if it needs to be installed.
#     Empty by default. [mh_install]
#
pom.xml --no-parent
common/pom.xml
common/common-lang/pom.xml
common/common-io/pom.xml
common/common-image/pom.xml
servlet/pom.xml
imageio/pom.xml
imageio/imageio-core/pom.xml
imageio/imageio-metadata/pom.xml
imageio/imageio-clippath/pom.xml
imageio/imageio-bmp/pom.xml
imageio/imageio-hdr/pom.xml
imageio/imageio-icns/pom.xml
imageio/imageio-iff/pom.xml
imageio/imageio-jpeg/pom.xml
imageio/imageio-pcx/pom.xml
imageio/imageio-pdf/pom.xml --ignore
imageio/imageio-pict/pom.xml
imageio/imageio-pnm/pom.xml
imageio/imageio-psd/pom.xml
imageio/imageio-sgi/pom.xml
imageio/imageio-tga/pom.xml
imageio/imageio-thumbsdb/pom.xml
imageio/imageio-tiff/pom.xml
imageio/imageio-batik/pom.xml
imageio/imageio-reference/pom.xml --ignore
contrib/pom.xml
bom/pom.xml

The debian/*.poms file includes every pom file in our source package. Here you can decide whether you want to build a certain module or ignore it. You can manipulate certain aspects of the build process. For instance you can change the final name of the resulting jar file with the --usj-name option. The --java-lib option will install Maven artifacts also into /usr/share/java which is useful for Ant projects.

maven.rules

Override a dependency in pom.xml by specifying the correct coordinates in Debian's /usr/share/maven-repo directory. Taken from libmbassador-java

<dependency>
            <groupId>javax.el</groupId>
            <artifactId>el-api</artifactId>
            <scope>provided</scope>
            <version>2.2</version>
</dependency>

This artifact is provided by libservlet3.1-java but artifactId and version are different. The scope "provided" means that libmbassador-java does not need a runtime dependency on libservlet3.1-java. It is expected that the application that makes use of libmbassador-java may or may not add a dependency on libservlet3.1-java.

maven.rules:

javax.el s/el-api/javax.el-api/ jar s/.*/3.0/

Note that the artifactId "el-api" was changed to Debian's "javax.el-api" and the version from 2.2 to 3.0. API packages usually don't use the "debian" version but a strict version like 3.0 to ensure compatibility.

PDFsam (a Maven application)

PDFsam is a complex application managed and built with Maven. It consists of multiple submodules. The Maven specific Debian files maven.properties, maven.rules, maven.ignoreRules and pdfsam.poms distinguishes PDFsam from non-Maven projects.

In pdfsam.poms one module has been ignored:

 pdfsam-msi-installer/pom.xml --ignore 

because the Microsoft installer is useless on Debian systems. The maven.ignoreRules file contains mostly test dependencies which are not needed because the tests are disabled in maven.properties. As you can see a Maven application is not very different from a Maven library. The interesting part is how the application is started and where the jar files reside on a Debian system.

It is very common in the Java world to create big or "fat" jars that include all dependencies. This is very convenient for distribution purposes because your whole program can be bundled in one file.

On Debian systems jar files for libraries are installed into /usr/share/java and|or /usr/share/maven-repo. It makes sense for applications to create a subdirectory in /usr/share to separate applications from pure libraries.

In this case the jar files are installed into /usr/share/pdfsam and external runtime dependencies are symlinked into /usr/share/pdfsam/lib. Please note that upstream already provides a launch script, pdfsam.sh, which is patched to point to Debian's system installation of PDFsam. An alternative approach is to either use java-wrappers or jarwrapper.

In short: Maven applications look very similar to Maven library projects. Most important differences are: a launch script, the installation into a subdirectory of /usr/share/ and either symlinking external runtime dependencies into this subdirectory or writing a MANIFEST file that sets the CLASSPATH correctly. You can also usually remove any files that are automatically installed into /usr/share/maven-repo because those artifacts are rarely needed by other Maven projects.

Maven relocations

Maven relocations are a mechanism like symlinks but for Maven dependencies. If a project formerly used foo:bar (groupID:ArtifactID) and then switched to org.foo:bar it is possible to redirect projects to the new coordinates. See also this post on debian-java for more details.