[packages/maven.git] / maven-jpp-readme.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<title>JPackage Maven2</title>
</head>
<body>
<h1>Notes on the JPackage version of Maven2 (2.0.4)</h1>
<p>
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.
<p>

<p>
<u><b>How to use it:</b></u><br/>

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. 
</p>

<p>
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.
</p>

<p>
<b><u>Dependency maps/'depmaps':</b></u><br/>

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/>

The depmap has entries in the format:<br/>
<pre>
&lt;dependencies&gt;
..
    &lt;dependency&gt;
        &lt;maven&gt;
            &lt;groupId&gt;OGROUPID&lt;/groupId&gt;
            &lt;artifactId&gt;OARTIFACTID&lt;/artifactId&gt;
            &lt;version&gt;OVERSION&lt;/version&gt;
        &lt;/maven&gt;
        &lt;jpp&gt;
            &lt;groupId&gt;NGROUPID&lt;/groupId&gt;
            &lt;artifactId&gt;NARTIFACTID&lt;/artifactId&gt;
            &lt;version&gt;NVERSION&lt;/version&gt;
        &lt;/jpp&gt;
    &lt;/dependency&gt;
..
&lt;dependencies&gt;
</pre>

<br/><br/>
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/>
<pre>
    &lt;dependency&gt;
        &lt;maven&gt;
            &lt;groupId&gt;junit&lt;/groupId&gt;
            &lt;artifactId&gt;junit&lt;/artifactId&gt;
            &lt;version&gt;3.8.1&lt;/version&gt;
        &lt;/maven&gt;
        &lt;jpp&gt;
            &lt;groupId&gt;JPP&lt;/groupId&gt;
            &lt;artifactId&gt;junit&lt;/artifactId&gt;
            &lt;version&gt;3.8.1&lt;/version&gt;
        &lt;/jpp&gt;
    &lt;/dependency&gt;
</pre>
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
</p>

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/>

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/>

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/>

<pre>
    &lt;dependency&gt;
        &lt;maven&gt;
            &lt;groupId&gt;velocity&lt;/groupId&gt;
            &lt;artifactId&gt;velocity-dep&lt;/artifactId&gt;
            &lt;version&gt;1.4&lt;/version&gt;
        &lt;/maven&gt;
    &lt;/dependency&gt;
</pre>

to the depmap.<br/><br/>

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.  

Finally, a custom one can be specified via -Dmaven2.jpp.depmap.file="..."<br/><br/>

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/>

<i>The custom depmap has highest preference, followed by the versioned depmap, followed by the versionless one </i><br/><br/>

<u><b>Packages adding their own depmaps:</b></u><br/>
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/>

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/>

<p>
<b><u>New properties:</b></u><br/>

<ul>
<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>

<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>

<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>

<li><i>maven2.jpp.depmap.file</i> - This option tells maven where to find the dependency mappings.</li>
</ul>
</p>
</body>
</html>
Commit	Line	Data
bd00ca76	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	<dependencies>
	30	..
	31	<dependency>
	32	<maven>
	33	<groupId>OGROUPID</groupId>
	34	<artifactId>OARTIFACTID</artifactId>
	35	<version>OVERSION</version>
	36	</maven>
	37	<jpp>
	38	<groupId>NGROUPID</groupId>
	39	<artifactId>NARTIFACTID</artifactId>
	40	<version>NVERSION</version>
	41	</jpp>
	42	</dependency>
	43	..
	44	<dependencies>
	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	<dependency>
	51	<maven>
	52	<groupId>junit</groupId>
	53	<artifactId>junit</artifactId>
	54	<version>3.8.1</version>
	55	</maven>
	56	<jpp>
	57	<groupId>JPP</groupId>
	58	<artifactId>junit</artifactId>
	59	<version>3.8.1</version>
	60	</jpp>
	61	</dependency>
	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 <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:<br/>
71
72	<pre>
73	<dependency>
74	<maven>
75	<groupId>velocity</groupId>
76	<artifactId>velocity-dep</artifactId>
77	<version>1.4</version>
78	</maven>
79	</dependency>
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>