maven-jpp-readme.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html>
   3 <head>
   4 <title>JPackage Maven2</title>
   5 </head>
   6 <body>
   7 <h1>Notes on the JPackage version of Maven2 (2.0.4)</h1>
   8 <p>
   9 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.
  10 <p>
  11
  12 <p>
  13 <u><b>How to use it:</b></u><br/>
  14
  15 Previously, when one needed to create a new rpm, for the build part they needed to set up a depmap, run all poms in a project via an xsl transformation that used the depmap to rewrite groupid's/artifactid's/etc., supply repository locations, and then call maven. Most of that has now been done away with.
  16 </p>
  17
  18 <p>
  19 Starting with the 9jpp release, to invoke maven in jpp mode, simply type 'mvn-jpp' with the -Dmaven2.jpp.depmap.file="..." argument if a separate depmap is needed. The command action is almost the same as "mvn" -- only that it supplies '-Dmaven2.offline.mode -Dmaven2.ignore.versions -Dmaven2.usejppjars' prior to invoking maven.
  20 </p>
  21
  22 <p>
  23 <b><u>Dependency maps/'depmaps':</b></u><br/>
  24
  25 To build a new project for a new JPackage rpm, a depmap still needs to be created so as to allow finding of the new jars. But this is not too different from the old way of using build-jar-repository with ant. The idea is the same -- tell the build tool where to find the required libraries.<br/><br/>
  26
  27 The depmap has entries in the format:<br/>
  28 <pre>
  29 &lt;dependencies&gt;
  30 ..
  31     &lt;dependency&gt;
  32         &lt;maven&gt;
  33             &lt;groupId&gt;OGROUPID&lt;/groupId&gt;
  34             &lt;artifactId&gt;OARTIFACTID&lt;/artifactId&gt;
  35             &lt;version&gt;OVERSION&lt;/version&gt;
  36         &lt;/maven&gt;
  37         &lt;jpp&gt;
  38             &lt;groupId&gt;NGROUPID&lt;/groupId&gt;
  39             &lt;artifactId&gt;NARTIFACTID&lt;/artifactId&gt;
  40             &lt;version&gt;NVERSION&lt;/version&gt;
  41         &lt;/jpp&gt;
  42     &lt;/dependency&gt;
  43 ..
  44 &lt;dependencies&gt;
  45 </pre>
  46
  47 <br/><br/>
  48 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:<br/>
  49 <pre>
  50     &lt;dependency&gt;
  51         &lt;maven&gt;
  52             &lt;groupId&gt;junit&lt;/groupId&gt;
  53             &lt;artifactId&gt;junit&lt;/artifactId&gt;
  54             &lt;version&gt;3.8.1&lt;/version&gt;
  55         &lt;/maven&gt;
  56         &lt;jpp&gt;
  57             &lt;groupId&gt;JPP&lt;/groupId&gt;
  58             &lt;artifactId&gt;junit&lt;/artifactId&gt;
  59             &lt;version&gt;3.8.1&lt;/version&gt;
  60         &lt;/jpp&gt;
  61     &lt;/dependency&gt;
  62 </pre>
  63 The above mapping indicates that if any of the poms need an artifact with groupid=junit, artifactid=junit and version=3.8.1, it can be found at $REPOSITORY/JPP/junit.jar
  64 </p>
  65
  66 Where $REPOSITORY is one of the active repositories with layout="jpp" ("jpp" is a new layout that has been added to our maven2 rpm).<br/><br/>
  67
  68 If maven2.ignore.versions is specified, any requirement of  groupid=junit, artifactid=junit will be satisfied with $REPOSITORY/JPP/junit.jar (i.e. version will be ignored even if mentioned in the depmap).<br/><br/>
  69
  70 If only a &lt;maven&gt; element is supplied and no &lt;jpp&gt;, 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:<br/>
  71
  72 <pre>
  73     &lt;dependency&gt;
  74         &lt;maven&gt;
  75             &lt;groupId&gt;velocity&lt;/groupId&gt;
  76             &lt;artifactId&gt;velocity-dep&lt;/artifactId&gt;
  77             &lt;version&gt;1.4&lt;/version&gt;
  78         &lt;/maven&gt;
  79     &lt;/dependency&gt;
  80 </pre>
  81
  82 to the depmap.<br/><br/>
  83
  84 There are two system depmaps. An unversioned one is located at: <tt>/etc/maven/maven2-versionless-depmap.xml</tt>. This is used when -Dmaven2-ignore-versions is specified. A versioned one is located at <tt>/etc/maven/maven2-depmap.xml</tt>. This is an autogenerated map which is rebuilt each time the <tt>update_maven_depmap</tt> macro is called by an rpm.
  85
  86 Finally, a custom one can be specified via -Dmaven2.jpp.depmap.file="..."<br/><br/>
  87
  88 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 <tt>add_to_maven_depmap</tt> and <tt>update_maven_depmap</tt> 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.<br/><br/>
  89
  90 <i>The custom depmap has highest preference, followed by the versioned depmap, followed by the versionless one </i><br/><br/>
  91
  92 <u><b>Packages adding their own depmaps:</b></u><br/>
  93 Packages from now on should add their own depmap fragments when they get installed. This is achieved by calling the <tt>add_to_maven_depmap</tt> macro for each jar/artifact being installed, followed by calling <tt>update_maven_depmap</tt> in the post and postun sections (note: this means that there will have to be a jpackage-utils >= 0:1.7.2 post and postun requirement for all packages that do this, since jpackage-utils 1.7.2 provides the macros). Finally, <tt>%{_mavendepmapfragdir}</tt> (=/etc/maven/fragments) should be added in the %files section of the main package. The idea is as follows:<br/><br/>
  94
  95 The %install section of each package uses the <tt>add_to_maven_depmap</tt> macro for each jar/pom that the main package and it's subpackages install. The macro puts the resulting data in <tt>$RPM_BUILD_ROOT%{_mavendepmapfragdir}/%{name}</tt>. <tt>update_maven_depmap</tt> in the post and postun then cat's /etc/maven/fragments/* into /etc/maven/maven2-depmap.xml which is read whenever mvn is run. See the plexus-cdc spec for a simple example, and maven-doxia for a more complex one.<br/><br/>
  96
  97 <p>
  98 <b><u>New properties:</b></u><br/>
  99
 100 <ul>
 101 <li><i>maven2.offline.mode</i> - Combined with maven2.ignore.versions, this switch is analogous to maven2.jpp.mode in 8jpp and lower. It tells maven to use the pre-configured jpackage repositories.</li>
 102
 103 <li><i>maven2.ignore.versions</i> - Combined with maven2.offline.mode, this switch is analogous to maven2.jpp.mode in 8jpp and lower. It tells maven to ignore versions when looking at the dependency map.</li>
 104
 105 <li><i>maven2.usejppjars</i> - This is a new option. When 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.</li>
 106
 107 <li><i>maven2.jpp.depmap.file</i> - This option tells maven where to find the dependency mappings.</li>
 108 </ul>
 109 </p>
 110 </body>
 111 </html>