Please update this wiki page to reflect recent events or newly available information.
Notes on the JPackage version of Maven2
Need for this page
The maven2 version released with JPackage has extensive modifications to ensure that it works smoothly in off-line mode. In order to facilitate easier maintainability, minimal changes have been made, and most have been kept in separate source files rather than patching into maven code. This page documents those changes, and how they can be used for maven-built packages.
Usage
Invocation
To invoke maven in jpp mode, simply type mvn-jpp with the -Dmaven2.jpp.depmap.file="..." argument if a separate depmap is needed. All options honored by upstream maven are honored by mvn-jpp. The command's action is almost the same as mvn -- only that it supplies -Dmaven2.offline.mode -Dmaven2.ignore.versions -Dmaven2.usejppjars prior to invoking maven.
Dependency Maps
To build a new project for a new rpm, a depmap may need to be created so as to allow finding of the new jars. The point of this tell the build tool where to find the required libraries.
The depmap has entries in the format:
<dependencies> .. <dependency> <maven> <groupId>OGROUPID</groupId> <artifactId>OARTIFACTID</artifactId> <version>OVERSION</version> </maven> <jpp> <groupId>NGROUPID</groupId> <artifactId>NARTIFACTID</artifactId> <version>NVERSION</version> </jpp> </dependency> .. <dependencies>
Where OGROUPID, OARTIFACTID and OVERSION are old group/artifact/versions (as they exist in your project) and NGROUPID, NARTIFACTID, NVERSION are the new ones. For example:
<dependency> <maven> <groupId>org.codehaus.plexus</groupId> <artifactId>plexus-ant-factory</artifactId> <version>1.0</version> </maven> <jpp> <groupId>JPP/plexus</groupId> <artifactId>ant-factory</artifactId> <version>1.0</version> </jpp> </dependency>
The above mapping indicates that if any of the poms need an artifact with groupid=org.codehaus.plexus, artifactid=plexus-ant-factory and version=1.0, it can be found at $REPOSITORY/JPP/plexus/ant-factory.jar Where $REPOSITORY is one of the active repositories with layout "jpp" ([#jpp-layout jpp] is a new layout that has been added to the JPackage Maven2 rpm).
If maven2.ignore.versions is specified (default with mvn-jpp, any requirement of groupid=org.codehaus.plexus, artifactid=plexus-ant-factory will be satisfied with $REPOSITORY/JPP/plexus/ant-factory.jar regardless of version.
If only a <maven> element is supplied and no <jpp>, it is assumed that the dependency is to be discarded. For example, some projects depend on the velocity-dep which has no equivalent jar in JPackage packages as velocity-dep is just a monolithic jar containing velocity dependencies. To remove velocity-dep then, you would add:
<dependency> <maven> <groupId>velocity</groupId> <artifactId>velocity-dep</artifactId> <version>1.4</version> </maven> </dependency>
to the depmap.
There are two system depmaps. An unversioned one is located at: /etc/maven/maven2-versionless-depmap.xml. This is used when -Dmaven2-ignore-versions is specified. A versioned one is located at /etc/maven/maven2-depmap.xml. This is an auto-generated map which is rebuilt each time the update_maven_depmap macro is called by an rpm. Finally, a custom one can be specified via -Dmaven2.jpp.depmap.file="..."
The versionless one contains depmap entries for items whose poms are installed by maven2-common-poms (for now). As time passes, more and more packages will start using the add_to_maven_depmap and update_maven_depmap macros and hopefully, the versionless can be phased out completely. If your project needs a mapping that is not already in there, you will have to create a separate file and use it via the above mentioned property.
The custom depmap has highest preference, followed by the versioned depmap, followed by the versionless one.
New properties
The maven2 rpm in Fedora provides the following new properties that can be passed to the mvn wrapper script.
maven2.offline.mode- This property tells maven to use the pre-configured jpackage repositories.maven2.ignore.versions- This property tells maven to ignore versions when looking at the dependency map.maven2.usejppjars- With this property supplied, maven will try to use jpackage jars whenever possible. It's main intention is to allow users to use /usr/share/java files when available, and fetch jars from the net if not. It may be combined with the above two.maven2.jpp.depmap.file- This option tells maven where to find custom dependency mappings
Additional steps when packaging maven built applications
POM file names
A package should install all the necessary poms that it supplies. Poms are installed to %{_datadir}/maven2/poms/ and their name follows a convention that allows maven to locate them easily. The name of the file should follow the following convention:
JPP[.<subdir name under %{_javadir}>]-jarname.pom, where jarname is the name of the jar without the .jar suffix.
For example, for plexus-ant-factory, the jar is %{_javadir}/plexus/ant-factory.jar, so the pom would be named JPP.plexus-ant-factory.pom.
For junit the jar is %{_javadir}/junit.jar, so the pom would be named JPP-junit.pom.
Packages adding their own depmaps
Packages from now on should add their own depmap fragments when they get installed. This is achieved by calling the add_to_maven_depmap macro for each jar/artifact being installed, followed by calling update_maven_depmap in the post and postun sections (note: this means that there will have to be a jpackage-utils post and postun requirement for all packages that do this, since jpackage-utils provides the macros). Finally, %{_mavendepmapfragdir} (=/etc/maven/fragments) should be added in the %files section of the main package. The idea is as follows:
The %install section of each package uses the add_to_maven_depmap macro for each jar/pom that the main package and it's subpackages install. The macro puts the resulting data in $RPM_BUILD_ROOT%{_mavendepmapfragdir}/%{name}. update_maven_depmap in the post and postun then cat's /etc/maven/fragments/* into /etc/maven/maven2-depmap.xml which is read whenever mvn-jpp is run. See the plexus-cdc spec for a simple example, and maven-doxia for a more complex one.
"jpp" Layout
The JPackage repository layout is a very simple layout. The group id translates to the subdirectory structure inside the repository, and the artifactid denotes the jar name, without the .jar at the end. For example, if /usr/share/maven2/repository is a repository marked with the "jpp" layout, then groupid=JPP/plexus, artifactId=ant-factory will cause maven to look for /usr/share/maven2/repository/JPP/plexus/ant-factory.jar