Differences between revisions 17 and 18
Revision 17 as of 2009-01-14 19:32:17
Size: 7141
Comment: start the specification section
Revision 18 as of 2009-01-14 19:33:43
Size: 7142
Comment:
Deletions are marked like this. Additions are marked like this.
Line 139: Line 139:
{{{<scope>system</copy>}}} and {{{<scope>system</scope>}}} and

Maven Repository Specification

This page specifies how to install Java libraries in Maven compatible way which makes it possible to use Maven for Debian packaging: [wiki:Java/MavenBuilder ?MavenBuilder]. This specification is intended to be

  • as short as possible,
  • easy to understand,
  • easy to use, and
  • compatible with the Debian Java policy.

Status

The specification is not completed yet. After completion it needs to be discussed in the mailing list.

Motivation: advantages of using Maven

Maven has advantages for the upstream developers that won't be repeated here. That is the reason why more and more projects are switching to Maven as their primary build tool. Detailed information about maven can be found at [http://maven.apache.org Maven's homepage ] and in the book [http://books.sonatype.com/maven-book/ Maven: The Definitive Guide].

Maven maintains a model of a project in a file pom.xml: the developer can assign attributes to a project such as:

  • name
  • description
  • URL
  • information about developers and contributors
  • license
  • mailing lists
  • issue tracker
  • source code management (like subversion)
  • dependencies

Most of those attributes can directly be used for Debian packaging but the most interesting ones are the dependencies.

Imagine a project 'a' that depends on 2 other projects 'b' and 'c' where 'b' itself depends on 'd', 'e', 'f' and 'c' depends on 'f', 'g', 'h'.

a ---> b ---> d
   |      |
   |      |-> e
   |      |
   |       -> f
   |
    -> c ---> f
          |
          |-> g
          |
           -> h

In a later upstream version 'c' adds another depends 'i' and that means that we have to change all reverse depends of 'c' including 'a' (like adding i.jar to DEB_JARS in debian/rules). But Maven will do this automatically for us and we do not have to touch reverse depends of any package when the dependencies change.

Problems with upstream's repository (central)

There is one central repository for Maven artifacts at [http://repo2.maven.org/maven2/] that ships all releases of an artifact. The artifact log4j:log4j has 12 different versions at [http://repo2.maven.org/maven2/log4j/log4j/] and maven downloads one of them during building a package that declares log4j:log4j as a dependency. Sometimes it is difficult to predict which version gets downloaded by maven and that is why it is hard to use maven in offline mode but for building Debian packages the offline mode is essential. All dependencies must be available as Debian packages and it is not acceptable to download artifacts during the build process from the central Maven repository.

The package [wiki:Java/MavenBuilder maven-debian-helper] tries to solve this problem by providing a local repository below the following directory:

REPO=/usr/share/maven-repo

We will reference this location as $REPO in the specification.

Alternatives

JPackage

The documentation of JPackage can be found at [http://www.jpackage.org/cgi-bin/viewvc.cgi/src/jpackage-utils/doc/jpackage-1.5-policy.xhtml?root=jpackage&view=co]. There is no information there on how to use maven. JPackage uses a patched Maven that understands the package layout in /usr/share/java. As a maintainer you have to learn the toolset - and that is why JPackage fails the 'easy to use' requirement.

JPackage cheats on version numbers - whenever a pom requests a specific version like 1.2.3 its Maven just delivers what is has in /usr/share/java without considering the requested version all. They obviously did not solved the problem of having multiple versions of an artifact installed at the same time but we have various versions of asm, commons-collections, junit, and more in Debian and we must have a solution for that.

Ubuntu

Ubuntu has its own specification at [https://wiki.ubuntu.com/JavaTeam/Specs/MavenSupportSpec]. There is no (nontrivial) package yet that follows the specification. All the Maven plugins and helper libraries mentioned in the specification hasn't been packaged in Ubuntu yet but they are packaged in Debian. Trying to use the Ubuntu toolset for packaging things like jetty looks very hard. It might be worth checking the spec again later. We are in contact we the Ubuntu developers and we are trying to cooperate as much as possible.

Targets

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [http://www.ietf.org/rfc/rfc2119.txt RFC 2119].

This specification is targeted at the following types of packages:

  1. Packages that use Maven for building SHALL install their artifacts into $REPO. Those packages SHOULD use maven-debian-helper which will do most of the work automatically.

  2. Packages that don't use Maven (yet) but their upstream developers are using Maven: they SHALL install their artifacts into $REPO after making sure they follow the specification. Patching of the pom.xml files might be necessary. Maven-debian-helper MAY be used to check the conformance to the spec.

  3. Package where the upstream developers don't use Maven but pom.xml are provided for Maven users: the artifacts SHOULD be installed into $REPO after making sure they follow the specification. Patching of the pom.xml files might be necessary. Maven-debian-helper MAY be used to check the conformance to the spec.

  4. All other packages: pom.xml files from other sources (central, mvnrepository.com or hand written) MAY be installed into $REPO after making sure the artifacts follow the specification. Patching of the pom.xml files might be necessary. Maven-debian-helper MAY be used to check the conformance to the spec.

For packages that are used very often by Maven based packages (example: junit) the MAY or SHOULD used above SHOULD by upgraded to a SHALL.

Specification

Artifacts MUST be installed into $REPO/$GROUPID/$ARTIFACTID/$VERSION/ where $GROUPID is the result of groupId.replace( '.', '/' ). The pom.xml files MUST be installed as $ARTIFACTID-$VERSION.pom and jar files as $ARTIFACTID-$VERSION.jar. A unversioned symlink $ARTIFACTID.jar to the jar file SHOULD be installed into /usr/share/java/.

All compile and run time dependencies MUST be resolved by packages that are available in Debian. Test dependencies need not be resolvable except if you want to build and run the test code. Dependencies that are not yet following this specification can be referred with <scope>system</scope> and <systemPath>/usr/share/java/$ARTIFACTID.jar</systemPath> but this SHOULD be avoided if possible.

Hard coded version number in dependencies SHOULD be avoided and replaced by properties: $GROUPID.$ARTIFACTID.version. For instance jetty's version can be referenced as <version>${org.mortbay.jetty.jetty.version}</version>.


CategoryJava