/usr/share/doc/maven-repo-helper/repository.html

<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
<title>Maven Repo Helper repository specification</title>
<style type="text/css">

pre { /* the pre makes the border */
    margin: 0.5em 0;
    padding: 10pt;
    border: 1pt solid #AEBDCC;
    background-color: #F3F5F7;
    color: black;
}

pre code { /* the code has no border and is inside the pre */
    margin: 0;
    padding: 0;
    border: none;
}


</style>
<style type="text/css">

/*
*   math2html: convert LaTeX equations to HTML output.
*
*   Copyright (C) 2009,2010 Alex Fernández
*
*   Released under the terms of the `2-Clause BSD license'_, in short:
*   Copying and distribution of this file, with or without modification,
*   are permitted in any medium without royalty provided the copyright
*   notice and this notice are preserved.
*   This file is offered as-is, without any warranty.
*
* .. _2-Clause BSD license: http://www.spdx.org/licenses/BSD-2-Clause
*
*   Based on eLyXer: convert LyX source files to HTML output.
*   http://elyxer.nongnu.org/
*/
/* --end--
* CSS file for LaTeX formulas.
*/

/* Formulas */
.formula {
	text-align: center;
	font-family: "Droid Serif", "DejaVu Serif", "STIX", serif;
	margin: 1.2em 0;
}
span.formula {
	white-space: nowrap;
}
div.formula {
	padding: 0.5ex;
	margin-left: auto;
	margin-right: auto;
}

/* Basic features */
a.eqnumber {
	display: inline-block;
	float: right;
	clear: right;
	font-weight: bold;
}
span.unknown {
	color: #800000;
}
span.ignored, span.arraydef {
	display: none;
}
.formula i {
	letter-spacing: 0.1ex;
}

/* Alignment */
.align-left, .align-l {
	text-align: left;
}
.align-right, .align-r {
	text-align: right;
}
.align-center, .align-c {
	text-align: center;
}

/* Structures */
span.overline, span.bar {
	text-decoration: overline;
}
.fraction, .fullfraction {
	display: inline-block;
	vertical-align: middle;
	text-align: center;
}
.fraction .fraction {
	font-size: 80%;
	line-height: 100%;
}
span.numerator {
	display: block;
}
span.denominator {
	display: block;
	padding: 0ex;
	border-top: thin solid;
}
sup.numerator, sup.unit {
	font-size: 70%;
	vertical-align: 80%;
}
sub.denominator, sub.unit {
	font-size: 70%;
	vertical-align: -20%;
}
span.sqrt {
	display: inline-block;
	vertical-align: middle;
	padding: 0.1ex;
}
sup.root {
	font-size: 70%;
	position: relative;
	left: 1.4ex;
}
span.radical {
	display: inline-block;
	padding: 0ex;
	font-size: 150%;
	vertical-align: top;
}
span.root {
	display: inline-block;
	border-top: thin solid;
	padding: 0ex;
	vertical-align: middle;
}
span.symbol {
	line-height: 125%;
	font-size: 125%;
}
span.bigsymbol {
	line-height: 150%;
	font-size: 150%;
}
span.largesymbol {
	font-size: 175%;
}
span.hugesymbol {
	font-size: 200%;
}
span.scripts {
	display: inline-table;
	vertical-align: middle;
}
.script {
	display: table-row;
	text-align: left;
	line-height: 150%;
}
span.limits {
	display: inline-table;
	vertical-align: middle;
}
.limit {
	display: table-row;
	line-height: 99%;
}
sup.limit, sub.limit {
	line-height: 100%;
}
span.symbolover {
	display: inline-block;
	text-align: center;
	position: relative;
	float: right;
	right: 100%;
	bottom: 0.5em;
	width: 0px;
}
span.withsymbol {
	display: inline-block;
}
span.symbolunder {
	display: inline-block;
	text-align: center;
	position: relative;
	float: right;
	right: 80%;
	top: 0.3em;
	width: 0px;
}

/* Environments */
span.array, span.bracketcases, span.binomial, span.environment {
	display: inline-table;
	text-align: center;
	border-collapse: collapse;
	margin: 0em;
	vertical-align: middle;
}
span.arrayrow, span.binomrow {
	display: table-row;
	padding: 0ex;
	border: 0ex;
}
span.arraycell, span.bracket, span.case, span.binomcell, span.environmentcell {
	display: table-cell;
	padding: 0ex 0.2ex;
	line-height: 99%;
	border: 0ex;
}
/*
* CSS file for LaTeX formulas, extra stuff:
* binomials, vertical braces, stackrel, fonts and colors.
*/

/* Inline binomials */
span.binom {
	display: inline-block;
	vertical-align: middle;
	text-align: center;
	font-size: 80%;
}
span.binomstack {
	display: block;
	padding: 0em;
}

/* Over- and underbraces */
span.overbrace {
	border-top: 2pt solid;
}
span.underbrace {
	border-bottom: 2pt solid;
}

/* Stackrel */
span.stackrel {
	display: inline-block;
	text-align: center;
}
span.upstackrel {
	display: block;
	padding: 0em;
	font-size: 80%;
	line-height: 64%;
	position: relative;
	top: 0.15em;

}
span.downstackrel {
	display: block;
	vertical-align: bottom;
	padding: 0em;
}

/* Fonts */
span.mathsf, span.textsf {
	font-style: normal;
	font-family: sans-serif;
}
span.mathrm, span.textrm {
	font-style: normal;
	font-family: serif;
}
span.text, span.textnormal {
	font-style: normal;
}
span.textipa {
	color: #008080;
}
span.fraktur {
	font-family: "Lucida Blackletter", eufm10, blackletter;
}
span.blackboard {
	font-family: Blackboard, msbm10, serif;
}
span.scriptfont {
	font-family: "Monotype Corsiva", "Apple Chancery", "URW Chancery L", cursive;
	font-style: italic;
}

/* Colors */
span.colorbox {
	display: inline-block;
	padding: 5px;
}
span.fbox {
	display: inline-block;
	border: thin solid black;
	padding: 2px;
}
span.boxed, span.framebox {
	display: inline-block;
	border: thin solid black;
	padding: 5px;
}


</style>
</head>
<body>
<div class="document">


<p><a class="reference external" href="repository.html">repository specification</a> |
<a class="reference external" href="reference.html">reference</a> | <a class="reference external" href="tutorial.html">tutorial</a></p>
<div class="section" id="maven-repository-specification">
<h1>Maven Repository Specification</h1>
<p>This page specifies how to install Java libraries in Maven compatible
way which makes it possible to use Maven for Debian packaging. This
specification is intended to be</p>
<ul class="simple">
<li>as short as possible,</li>
<li>easy to understand,</li>
<li>easy to use, and</li>
<li>compatible with the Debian Java policy.</li>
</ul>
<div class="section" id="status">
<h2>Status</h2>
<p>The specification is in use and implemented by maven-repo-helper and
maven-debian-helper packages.</p>
</div>
<div class="section" id="motivation-advantages-of-using-maven">
<h2>Motivation: advantages of using Maven</h2>
<p>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 <a class="reference external" href="http://maven.apache.org">Maven's homepage</a> and in the
book <a class="reference external" href="http://books.sonatype.com/maven-book/">Maven: The Definitive
Guide</a>.</p>
<p>Maven maintains a model of a project in a file <strong>pom.xml</strong>: the
developer can assign attributes to a project such as:</p>
<ul class="simple">
<li>name</li>
<li>description</li>
<li>URL</li>
<li>information about developers and contributors</li>
<li>license</li>
<li>mailing lists</li>
<li>issue tracker</li>
<li>source code management (like subversion)</li>
<li>dependencies</li>
</ul>
<p>Most of those attributes can directly be used for Debian packaging but
the most interesting ones are the dependencies.</p>
<p>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'.</p>
<pre class="literal-block">
a ---&gt; b ---&gt; d
   |      |
   |      |-&gt; e
   |      |
   |       -&gt; f
   |
    -&gt; c ---&gt; f
          |
          |-&gt; g
          |
           -&gt; h
</pre>
<p>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 <strong>i.jar</strong> to <strong>DEB_JARS</strong> in <strong>debian/rules</strong>). But Maven will
do this automatically for us and we do not have to touch reverse depends
of any package when the dependencies change.</p>
</div>
<div class="section" id="problems-with-upstream-s-repository-central">
<h2>Problems with upstream's repository (central)</h2>
<p>There is one central repository for Maven artifacts at
<a class="reference external" href="http://repo2.maven.org/maven2/">http://repo2.maven.org/maven2/</a> 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.</p>
<p>The package maven-repo-helper tries to solve this problem by providing a
local repository below the following directory:</p>
<pre class="literal-block">
REPO=/usr/share/maven-repo
</pre>
<p>We will reference this location as <strong>$REPO</strong> in the specification.</p>
<p>In Maven Central repository, there is one policy which mandates that
projects upload a cleaned version of their POM files (see
<a class="reference external" href="Guide%20to%20uploading%20artifacts%20to%20the%20Central%20Repository">http://maven.apache.org/guides/mini/guide-central-repository-upload.html</a>).
In particular, the tag in a POM files should be removed, as well as or
tags as all dependencies should be already in Central. We will use
similar rules for the Debian repository.</p>
</div>
<div class="section" id="versions-in-maven-pom-files-and-smooth-updates-of-debian-packages">
<h2>Versions in Maven POM files and smooth updates of Debian packages</h2>
<p>The Maven repository should support smooth upgrades of Java libraries.
When a new version of a library is installed in a Debian system, this is
what should happend:</p>
<ol class="arabic simple">
<li>Files in <strong>:math:`REPO/`GROUPID/:math:`ARTIFACTID/`OLD_VERSION/</strong>
are deleted</li>
<li>The new POM file and link to the jar are installed under
<strong>:math:`REPO/`GROUPID/:math:`ARTIFACTID/`NEW_VERSION/</strong></li>
<li>Other POMs which have a dependency on <strong>:math:`GROUPID:`ARTIFACTID::math:`OLD_VERSION__ should see their dependencies updated to __`GROUPID::math:`ARTIFACTID:`NEW_VERSION</strong></li>
</ol>
<p>Steps 1. and 2. are simple file operations, but 3. implies that dpkg
should somehow parse all POM files installed under $REPO, and update the
dependency version where necessary. This would imply changing files
outside of the package affected by the update, and those files may
belong to other packages. This is difficult and against the Debian
guidelines.</p>
<p>We are using a solution which keeps the amount of effort to a minimum,
keeps $REPO consistent and useable at all times and works well with
Maven.</p>
<p>The idea is to maintain 2 versions of each artifact under the Maven
repository. The first version uses the native version from Maven, to
keep compatibility.</p>
<p>The second version is more interesting: its version is converted to a
Debian managed version, usually 'debian', but it could be '1.x' to
represent any version compatible with the version 1 of the API.</p>
<p>The Maven repository will look like this:</p>
<pre class="literal-block">
/usr/share/java/
  commons-beanutils-1.8.0.jar
  commons-beanutils.jar -&gt; commons-beanutils-1.8.0.jar
  junit-3.8.2.jar
  junit.jar -&gt; junit-3.8.2.jar
/usr/share/maven-repo/
   commons-beanutils/commons-beanutils/1.8.0/
     commons-beanutils-1.8.0.jar -&gt; ../../../../java/commons-beanutils-1.8.0.jar
     commons-beanutils-1.8.0.pom
   commons-beanutils/commons-beanutils/debian/
     commons-beanutils-debian.jar -&gt; ../../../../java/commons-beanutils-1.8.0.jar
     commons-beanutils-debian.pom
   junit/junit/3.8.2/
     junit-3.8.2.jar -&gt; ../../../../java/junit-3.8.2.jar
     junit-3.8.2.pom
   junit/junit/3.x/
     junit-3.x.jar -&gt; ../../../../java/junit-3.8.2.jar
     junit-3.x.pom
</pre>
<p>The jar for each package (here libcommons-beanutils-java and junit) are
installed in /usr/share/java to comply with the Debian Java policy, then
we create symlinks to those jars in the places where we need them. So we
have a link for the jar under the current version folder in
/usr/share/maven-repo, and there is a link to the jar under the Debian
version in the Maven repository.</p>
<p>Upgrading the jar is now a simple matter of deleting the jars, symlinks
and folders used by the old version, creating the jars, symlinks and
folders for the new version, and updating the symlinks for the
versionless links in /usr/share/java (commons-beanutils.jar, junit.jar)
and updating the symlinks for the Debian versioned symlinks
(/usr/share/maven-repo/commons-beanutils/commons-beanutils/debian/commons-beanutils-debian.jar
and /usr/share/maven-repo/junit/junit/3.x/junit-3.x.jar). Don't worry,
the scripts provided by maven-repo-helper will do this for you.</p>
<p>This layout makes it easy to upgrade libraries independenly of each
others, it keeps some compatibility with the Maven central repository so
that you can mix and match Debian-controlled parts of the repository
with downloads from the Internet if you wish.</p>
<p>Now the real trick is in how dependencies are versioned in each POM: we
replace all native versions with Debian versions.</p>
<p>This is the (simplified) content of commons-beanutils-1.8.0.pom:</p>
<pre class="literal-block">
&lt;project&gt;
&lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
&lt;groupId&gt;commons-beanutils&lt;/groupId&gt;
&lt;artifactId&gt;commons-beanutils&lt;/artifactId&gt;
&lt;version&gt;1.8.0&lt;/version&gt;
&lt;packaging&gt;jar&lt;/packaging&gt;
&lt;dependencies&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;commons-logging&lt;/groupId&gt;
        &lt;artifactId&gt;commons-logging&lt;/artifactId&gt;
        &lt;version&gt;debian&lt;/version&gt;
    &lt;/dependency&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;commons-collections&lt;/groupId&gt;
        &lt;artifactId&gt;commons-collections&lt;/artifactId&gt;
        &lt;version&gt;3.x&lt;/version&gt;
        &lt;optional&gt;true&lt;/optional&gt;
    &lt;/dependency&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;commons-collections&lt;/groupId&gt;
        &lt;artifactId&gt;commons-collections-testframework&lt;/artifactId&gt;
        &lt;version&gt;debian&lt;/version&gt;
        &lt;scope&gt;test&lt;/scope&gt;
    &lt;/dependency&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;junit&lt;/groupId&gt;
        &lt;artifactId&gt;junit&lt;/artifactId&gt;
        &lt;version&gt;3.x&lt;/version&gt;
        &lt;scope&gt;test&lt;/scope&gt;
    &lt;/dependency&gt;
&lt;/dependencies&gt;
&lt;/project&gt;
</pre>
<p>commons-beanutils-debian.pom has the same content, except that is now
'debian':</p>
<pre class="literal-block">
&lt;project&gt;
&lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
&lt;groupId&gt;commons-beanutils&lt;/groupId&gt;
&lt;artifactId&gt;commons-beanutils&lt;/artifactId&gt;
&lt;version&gt;debian&lt;/version&gt; &lt;!-- 'debian' version here ! --&gt;
&lt;packaging&gt;jar&lt;/packaging&gt;
&lt;dependencies&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;commons-logging&lt;/groupId&gt;
        &lt;artifactId&gt;commons-logging&lt;/artifactId&gt;
        &lt;version&gt;debian&lt;/version&gt;
    &lt;/dependency&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;commons-collections&lt;/groupId&gt;
        &lt;artifactId&gt;commons-collections&lt;/artifactId&gt;
        &lt;version&gt;3.x&lt;/version&gt;
        &lt;optional&gt;true&lt;/optional&gt;
    &lt;/dependency&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;commons-collections&lt;/groupId&gt;
        &lt;artifactId&gt;commons-collections-testframework&lt;/artifactId&gt;
        &lt;version&gt;debian&lt;/version&gt;
        &lt;scope&gt;test&lt;/scope&gt;
    &lt;/dependency&gt;
    &lt;dependency&gt;
        &lt;groupId&gt;junit&lt;/groupId&gt;
        &lt;artifactId&gt;junit&lt;/artifactId&gt;
        &lt;version&gt;3.x&lt;/version&gt;
        &lt;scope&gt;test&lt;/scope&gt;
    &lt;/dependency&gt;
&lt;/dependencies&gt;
&lt;/project&gt;
</pre>
<p>Note that all dependencies have also their versions replaced with the
symbolic versions from Debian. For example, there is a dependency on
version 3.x of junit. 3.x is a symbolic version for junit that we have
defined earlier.</p>
<p>If we need to update junit to a new version, let's suppose that the
version 3.8.3 comes out, then junit 3.8.2 will be removed from the Maven
repository and replaced by junit 3.8.3. But junit 3.x will not be
affected by the change, except that the target for the symlink of
junit-3.x.jar will now point to junit-3.8.3.jar. More importantly, the
POM file for junit 3.x will not change, which means that we can keep
pointing to it from other packages, like in this case
libcommons-beanutils-java.</p>
</div>
<div class="section" id="alternatives">
<h2>Alternatives</h2>
<ul class="simple">
<li>JPackage</li>
</ul>
<p>The documentation of JPackage can be found at
<a class="reference external" href="http://www.jpackage.org/cgi-bin/viewvc.cgi/src/jpackage-utils/doc/jpackage-1.5-policy.xhtml?root=jpackage&amp;view=co">http://www.jpackage.org/cgi-bin/viewvc.cgi/src/jpackage-utils/doc/jpackage-1.5-policy.xhtml?root=jpackage&amp;view=co</a>.
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.</p>
<p>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.</p>
<ul class="simple">
<li>Version ranges</li>
</ul>
<p>Maven supports version ranges - see the <a class="reference external" href="http://docs.codehaus.org/display/MAVEN/Dependency+Mediation+and+Conflict+Resolution">version ranges
specification</a>.
We could use replace strict versions in dependencies by version ranges,
to allow smooth upgrades when a library is updated. For example, in the
commons-beanutils POM we could replace the version for the junit
dependency by a version range:</p>
<pre class="literal-block">
&lt;dependency&gt;
    &lt;groupId&gt;junit&lt;/groupId&gt;
    &lt;artifactId&gt;junit&lt;/artifactId&gt;
    &lt;version&gt;[3.8.2,4.0)&lt;/version&gt;
    &lt;scope&gt;test&lt;/scope&gt;
&lt;/dependency&gt;
</pre>
<p>With this new POM definition, we could easily update junit from version
3.8.2 to version 3.8.3 without breaking commons-beanutils.</p>
<p>That's a neet solution, unfortunately Maven 2 had quite a few issues
with version ranges. To enable a reliable resolution of versions with
version ranges, we need first to enforce a reliable numbering scheme for
Java libraries. Some Java libraries in Debian have some really strange
version schemes, some use for example dates, others -ALPHA, -BETA, -RC
suffixes, others not. It looks like Maven 3.1 will adopt OSGi numering
scheme, but nothing is written in stone at the moment. When things will
have settled, we will probably update the Maven repository for Debian to
use version ranges instead of symbolic versions.</p>
</div>
</div>
<div class="section" id="targets">
<h1>Targets</h1>
<p>The key words &quot;MUST&quot;, &quot;MUST NOT&quot;, &quot;REQUIRED&quot;, &quot;SHALL&quot;, &quot;SHALL NOT&quot;,
&quot;SHOULD&quot;, &quot;SHOULD NOT&quot;, &quot;RECOMMENDED&quot;, &quot;MAY&quot;, and &quot;OPTIONAL&quot; in this
document are to be interpreted as described in
[[<a class="reference external" href="http://www.ietf.org/rfc/rfc2119.txt">http://www.ietf.org/rfc/rfc2119.txt</a>|RFC 2119]].</p>
<p>This specification is targeted at the following types of packages:</p>
<ol class="arabic simple">
<li>Packages that use Maven for building SHALL install their artifacts
into <strong>$REPO</strong>. Those packages SHOULD use maven-repo-helper or
maven-debian-helper which will do most of the work automatically.</li>
<li>Packages that don't use Maven (yet) but their upstream developers are
using Maven: they SHALL install their artifacts into <strong>$REPO</strong> after
making sure they follow the specification. Patching of the pom.xml
files might be necessary. Maven-repo-helper or maven-debian-helper
MAY be used to check the conformance to the spec.</li>
<li>Package where the upstream developers don't use Maven but pom.xml are
provided for Maven users: the artifacts SHOULD be installed into
<strong>$REPO</strong> after making sure they follow the specification. Patching
of the pom.xml files might be necessary. Maven-repo-helper MAY be
used to check the conformance to the spec.</li>
<li>All other packages: pom.xml files from other sources (central,
mvnrepository.com or hand written) MAY be installed into <strong>$REPO</strong>
after making sure the artifacts follow the specification. Patching of
the pom.xml files might be necessary. Maven-repo-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 be upgraded to a SHALL.</li>
</ol>
</div>
<div class="section" id="specification">
<h1>Specification</h1>
<p>Artifacts MUST be installed into <strong>:math:`REPO/`GROUPID/:math:`ARTIFACTID/`VERSION/</strong>
where $GROUPID is the result of <strong>groupId.replace( '.', '/' )</strong> and
<span class="formula"><i>VERSION</i><i>is</i><i>the</i><i>current</i><i>version</i><i>of</i><i>the</i><i>artifact</i>.<i>The</i><i>pom</i>.<i>xml</i><i>files</i><i>MUST</i><i>be</i><i>installed</i><i>as</i><sub><sub></sub></sub></span>ARTIFACTID-<span class="formula"><i>VERSION</i>.<i>pom</i><sub><sub><i>and</i></sub></sub><i>the</i><i>symlink</i><i>to</i><i>the</i><i>jar</i><i>file</i><i>as</i><sub><sub></sub></sub></span>ARTIFACTID-<span class="formula"><i>VERSION</i>.<i>jar</i><sub><sub>.</sub></sub><i>Following</i><i>the</i><i>Debian</i><i>Java</i><i>policy</i>, <i>the</i><i>jar</i><i>file</i><i>itself</i><i>SHOULD</i><i>be</i><i>installed</i><i>as</i><sub><sub></sub></sub></span>ARTIFACTID.jar__
into <strong>/usr/share/java/</strong>, but the name of the jar MAY be different.</p>
<p>Artifacts SHOULD also be installed into <strong>:math:`REPO/`GROUPID/:math:`ARTIFACTID/`DEBIAN_VERSION/</strong>,
where $DEBIAN_VERSION is the symbolic version used to facilitate
updates of the artifact in Debian. As we need to guaranty that the new
version of the package will keep running and won't break dependant
packages, it is advised to use a symbolic version which will exclude API
breaking changes in the library. A well behaved library will use the
symbolic versions 1.x, 2.x, 3.x and so on to indicate that all versions
starting with 1. will be mapped to the symbolic version 1.x and that
minor updates in this version range will not break other packages, but
version 2.0 onwards will contain breaking changes and require a bigger
upgrade including updating the symbolic version 2.x for this library and
for all dependant packages. It is expected that such a major change MAY
require a new packaging for the library, for example
libcommons-collections-java contains the version 2. of
commons-collection and uses the symbolic version 2.x in the Maven
repository, but libcommons-collections3-java contains the version 3. of
commons-collections and uses the symbolic version 3.x in the Maven
repository.</p>
<p>Maven plugins cannot use symbolic versions, so when the artifact is a
Maven plugin, then the symbolic version SHOULD NOT be used for that
artifact.</p>
<p>All compile and run time dependencies including parents and plugins 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.</p>
<p>For all dependencies already packaged in Debian with the accompanying
Maven metadata, hard coded version numbers for those dependencies SHOULD
be replaced by their symbolic version. Example:</p>
<pre class="literal-block">
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.maven&lt;/groupId&gt;
  &lt;artifactId&gt;maven-core&lt;/artifactId&gt;
  &lt;version&gt;2.0.9&lt;/version&gt;
&lt;/dependency&gt;
</pre>
<p>should be changed to</p>
<pre class="literal-block">
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.maven&lt;/groupId&gt;
  &lt;artifactId&gt;maven-core&lt;/artifactId&gt;
  &lt;version&gt;2.x&lt;/version&gt;
&lt;/dependency&gt;
</pre>
<p>When the POM contains also a reference to a parent, then the version for
this parent SHOULD also be replaced by a symbolic version. Example:</p>
<pre class="literal-block">
&lt;parent&gt;
    &lt;groupId&gt;asm&lt;/groupId&gt;
    &lt;artifactId&gt;asm-parent&lt;/artifactId&gt;
    &lt;version&gt;2.2.3&lt;/version&gt;
&lt;/parent&gt;

&lt;parent&gt;
    &lt;groupId&gt;asm&lt;/groupId&gt;
    &lt;artifactId&gt;asm-parent&lt;/artifactId&gt;
    &lt;version&gt;2.x&lt;/version&gt;
&lt;/parent&gt;
</pre>
<p>Dependencies that are not yet following this specification can be
referred with <strong>system</strong> and <strong>/usr/share/java/$ARTIFACTID.jar</strong> but
this SHOULD be avoided if possible. Example:</p>
<pre class="literal-block">
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.maven&lt;/groupId&gt;
  &lt;artifactId&gt;maven-core&lt;/artifactId&gt;
  &lt;version&gt;2.0.9&lt;/version&gt;
&lt;/dependency&gt;
</pre>
<p>could be changed to</p>
<pre class="literal-block">
&lt;dependency&gt;
  &lt;groupId&gt;org.apache.maven&lt;/groupId&gt;
  &lt;artifactId&gt;maven-core&lt;/artifactId&gt;
  &lt;version&gt;2.0.9&lt;/version&gt;
  &lt;scope&gt;system&lt;/scope&gt;
  &lt;systemPath&gt;/usr/share/java/maven2.jar&lt;/systemPath&gt;
&lt;/dependency&gt;
</pre>
<p>as long as the Debian package maven2 does not ship its pom files. The
hardcoded version number is ignored by Maven if the <a href="#id1"><span class="problematic" id="id2">**</span></a>** element is
specified.</p>
<div class="system-message" id="id1">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">doc/repository.rst</tt>, line 451); <em><a href="#id2">backlink</a></em></p>
Inline strong start-string without end-string.</div>
<p>The helper scripts provided by maven-repo-helper (in particular
mh_cleanpom and mh_installpom) and maven-debian-helper (integrated in
Maven as Maven plugins) will assist you to install the jar files and the
POM descriptors in the repository, and replace the versions in the POM
files by symbolic versions where needed. They perform further operations
such as removing unecessary tags in the XML (, and in particular are
removed), and they insert some useful additional information in the POM
file as properties. Those additional properties provide guidance for
those automatic tools when working on the package or on packages
dependent upon this package.</p>
<p>For example:</p>
<pre class="literal-block">
&lt;properties&gt;
    &lt;debian.originalVersion&gt;2.2.3&lt;/debian.originalVersion&gt;
    &lt;debian.package&gt;libasm2-java&lt;/debian.package&gt;
    &lt;debian.mavenRules&gt;&lt;![CDATA[asm * * s/2\..*/2.x/ * *]]&gt;&lt;/debian.mavenRules&gt;
&lt;/properties&gt;
</pre>
<ul>
<li><p class="first">debian.originalVersion: Indicates the current version for the
library. Used in particular to manage updates.</p>
</li>
<li><p class="first">debian.package: Name of the binary Debian package containing this POM
file. It speeds up packaging, as launching dpkg--search is not really
efficient from Java.</p>
</li>
<li><p class="first">debian.mavenRules: Lists the rules used for this package. It
simplifies handling dependencies. For example, if the dependency
asm:asm:2.4.5 is found in a POM file, then we try to apply the rule
'asm * * s/2..*/2.x/ * *'. It will match and return 'asm asm jar
2.x compile' after dependency resolution, and the tool will replace
version 2.4.5 by 2.x in the POM file.</p>
</li>
<li><p class="first">debian.hasPackageVersion: Indicates that there is a match between the
version in Maven and the Debian version of the package. For example
if the Maven version is 2.2.3 for asm, and the debian version of
libasm2-java is 2.2.3-1, then we can add this property flag to the
POM. For consumers of the package, it means that if they have a
dependency on asm with the version 2.2 for example, then they can use
a version constraint on their Depends and Build-Depends for the
libasm2-java package, like so:</p>
<p>Depends: ${misc:Depends}, libasm2-java ( &gt;= 2.2 )</p>
</li>
</ul>
</div>
<div class="section" id="glossary">
<h1>Glossary</h1>
<p>Some of Maven's concept are explained here but do not expect an exact
reference, please.</p>
<ul>
<li><p class="first"><strong>Artifact</strong>: An artifact is a module in a Maven project. Every
artifact has one pom.xml file (called the POM) and has zero or one
binary jar files. An artifact can be uniquely addressed by the <a href="#id3"><span class="problematic" id="id4">**</span></a><strong>,
**</strong>, and <a href="#id5"><span class="problematic" id="id6">**</span></a>** elements.</p>
<div class="system-message" id="id3">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">doc/repository.rst</tt>, line 504); <em><a href="#id4">backlink</a></em></p>
<p>Inline strong start-string without end-string.</p>
</div>
<div class="system-message" id="id5">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">doc/repository.rst</tt>, line 504); <em><a href="#id6">backlink</a></em></p>
<p>Inline strong start-string without end-string.</p>
</div>
</li>
<li><p class="first"><strong>Dependency</strong>: A reference to another artifact that is needed for
building, testing, or during runtime. It is specified by the <a href="#id7"><span class="problematic" id="id8">**</span></a>**
element.</p>
<div class="system-message" id="id7">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">doc/repository.rst</tt>, line 508); <em><a href="#id8">backlink</a></em></p>
<p>Inline strong start-string without end-string.</p>
</div>
</li>
<li><p class="first"><strong>Parent</strong>: Every artifact can have zero or one dependency specified
by the <a href="#id9"><span class="problematic" id="id10">**</span></a>** element. Parent are somewhat similar to dependencies but
not identical.</p>
<div class="system-message" id="id9">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">doc/repository.rst</tt>, line 511); <em><a href="#id10">backlink</a></em></p>
<p>Inline strong start-string without end-string.</p>
</div>
</li>
<li><p class="first"><strong>Plugin</strong>: Maven uses plugins to carry out most of the work of build
process like the ''maven-clean-plugin'', ''maven-compile-plugin'',
and ''maven-jar-plugin'' - just to name a few. Specialized plugins
can be used to customize the build process and they are specified by
the <a href="#id11"><span class="problematic" id="id12">**</span></a>** element.</p>
<div class="system-message" id="id11">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">doc/repository.rst</tt>, line 514); <em><a href="#id12">backlink</a></em></p>
<p>Inline strong start-string without end-string.</p>
</div>
</li>
<li><p class="first"><strong>POM</strong>: The ''project object model'' that describes the artifact and
its build process. It is represented as a file pom.xml in the source
code which gets renamed to <span class="formula"><i>ARTIFACTID</i> − </span>VERSION.pom during
installation. It is also designed as Maven metadata as it contains
data about an artifact.</p>
</li>
<li><p class="first"><strong>Project</strong>: One or more modules can be built in one build process
and they usually share the same version number. In a multimodule
project the modules are specified by the <a href="#id13"><span class="problematic" id="id14">**</span></a>** element. That is why
every maven project is best packaged as one Debian source package.</p>
<div class="system-message" id="id13">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">doc/repository.rst</tt>, line 524); <em><a href="#id14">backlink</a></em></p>
<p>Inline strong start-string without end-string.</p>
</div>
</li>
</ul>
</div>
</div>
</body>
</html>
maven-repo-helper 1.8.9 / usr / share / doc / maven-repo-helper / repository.html
