1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
|
[repository specification](repository.html) | [reference](reference.html) | [tutorial](tutorial.html)
Packaging Java and Maven projects with Maven Repo Helper
========================================================
The maven-repo-helper package provides tools for installing and maintaining Maven POMs and jars installed in /usr/share/maven-repo.
Maven is a comprehensive build tool for Java and other languages based around the concept of plugins and a repository accessible normally from internet (a la CPAN), and providing access to the libraries used by a project.
To satisfy the requirement that all software must be built from the Debian repository and that no access to Internet is allowed during a build, we have re-created a Maven repository for Debian. This repository is located in /usr/share/maven-repo and Maven POM files installed there must follow some special requirements.
The Debian policy mandates that Java libraries are installed in /usr/share/java, so we have many Java libraries have already been packaged in Debian, but they don't have any Maven descriptors (POMs) associated with them. maven-repo-helper can help by installing those libraries also in /usr/share/maven-repo with their POM files.
The Maven repository maintained by Debian has some special characteristics which make it difficult to use directly upstream POM files without any changes. To allow a smooth upgrade of Java libraries, we create both native and Debian versions of the artifacts, and replace all versions in the dependencies with Debian versions - see the [repository specification](repository.html) document for more informations about this process. In addition, entries in the POM file which are not needed anymore, such as build information, are removed. mh\_make provides the scripts mh\_patchpom and mh\_cleanpom which patch dependencies versions and clean up the POM file respectively. Other scripts often make use of those two scripts to provide more advanced functionality.
maven-repo-helper has no dependency on Maven, so it can be used for any library, including libraries used by Maven itself. It provides the foundations for maven-debian-helper. Its goal is to manage the /usr/share/maven-repo folder properly, and cannot be used alone to build a Java library from source. You will normally use it either with Ant (started by a cdbs rule or dh 7 rule or anything you like), or with javahelper which will take care of building the binaries for your project.
**Important:** If you want your build to use Maven itself, then run mh\_make from the maven-debian-helper package on the upstream sources. mh\_make will guide you for that process and generate all necessary debian files for you.
You can also use mh\_make --ant to speed up the packaging of a project which uses Ant as the build tool and needs to install its artifacts into the Maven repository.
Quick start
===========
This section presents some of the recommanded packaging styles:
DH 7 + Ant + maven-repo-helper
------------------------------
The build uses dh 7 style, it runs Ant for the build and uses maven-repo-helper to install all jars both in /usr/share/java and in /usr/share/maven-repo with the POM files.
debian/control:
Source: bnd
Section: java
Priority: optional
Maintainer: Debian Java Maintainers <pkg-java-maintainers@lists.alioth.debian.org>
Uploaders: Ludovic Claude <ludovicc@debian.org>
Build-Depends: debhelper (>= 8), maven-repo-helper (>= 1.7), default-jdk
Build-Depends-Indep: junit, libosgi-ee-minimum-api-java (>= 1.2.1)
Standards-Version: 3.9.2
Homepage: http://www.aqute.biz/Code/Bnd
Package: bnd
Architecture: all
Depends: ${misc:Depends}
Description: A tool to create and diagnose OSGi R4 bundles
[...]
Note the Build-Depends on debhelper and maven-repo-helper
debian/rules:
#!/usr/bin/make -f
export JAVA_HOME=/usr/lib/jvm/default-java
%:
dh $@ --buildsystem=ant --with maven_repo_helper
We use here dh 7 for the build, with ant as the build system, and the maven_repo_helper plugin which will install all generated artifacts in the Maven repository.
Ant is run with the upstream build.xml file and the default target.
bnd.poms:
biz.aQute.bndlib/tmp/pom.xml --has-package-version --artifact=biz.aQute.bndlib/tmp/biz.aQute.bndlib.jar --java-lib --usj-name=bndlib
Deploy the jar built in biz.aQute.bndlib/tmp folder (--artifact option) as bndlib.jar (--usj-name option) in /usr/share/java (--java-lib option) and deploy it as well in the Maven repository. We use the POM file created by the build (biz.aQute.bndlib/tmp/pom.xml) as it contains the metadata for the bndlib jar.
The option --has-package-version tells maven-repo-helper that the version of the POM matches the version of the Debian package, which is a useful hint for
mh\_make when packaging another project which uses this library.
maven.rules:
biz.aQute s/bnd/bndlib/
Change the name of the artifact from bnd to bndlib in the Maven POM. The current version of bndlib will be replaced by a generic 'debian' version.
You can use mh\_lspoms from the maven-debian-helper package to help you locate POM files in your sources and generate both the .poms and maven.rules files.
DH 7 + Ant + maven-ant-helper + maven-repo-helper
-------------------------------------------------
A variant of the previous solution, where we don't use the upstream build script, but an Ant script which works on something which looks like a Maven project and tries to emulate Maven as best as it can. This is quite handy when you are working on a package used by Maven itself and cannot use Maven during the build.
debian/control:
Source: plexus-utils2
Section: java
Priority: optional
Maintainer: Debian Java Maintainers <pkg-java-maintainers@lists.alioth.debian.org>
Uploaders: Ludovic Claude <ludovic.claude@laposte.net>
Build-Depends: debhelper (>= 7), default-jdk, maven-repo-helper (>= 1.7), ant-optional, maven-ant-helper (>= 7)
Build-Depends-Indep: libplexus-parent-java (>= 2.0.6), junit (>= 3.8.2), default-jdk-doc
Standards-Version: 3.9.2
Vcs-Svn: svn://svn.debian.org/svn/pkg-java/trunk/plexus-utils2
Vcs-Browser: http://svn.debian.org/wsvn/pkg-java/trunk/plexus-utils2
Homepage: http://plexus.codehaus.org/plexus-utils
Package: libplexus-utils2-java
Architecture: all
Depends: ${misc:Depends}, libplexus-parent-java (>= 2.0.6)
Suggests: libplexus-utils2-java-doc
Description: Plexus Common Utilities
[...]
Package: libplexus-utils2-java-doc
Architecture: all
Section: doc
Depends: ${misc:Depends}, default-jdk-doc
Suggests: libplexus-utils2-java
Description: Documentation for Plexus Common Utilities
[...]
We define a binary package which will contain the jars and the fragment of the Maven repository for this package (libplexus-utils2-java),
and a documentation package containing the Javadoc folder (installed in /usr/share/doc) and the Javadoc jar installed in the Maven repository (libplexus-utils2-java-doc).
Note the Build-Depends on debhelper, maven-repo-helper and maven-ant-helper.
debian/rules:
#!/usr/bin/make -f
DEB_SOURCE_PACKAGE := $(shell dpkg-parsechangelog | grep '^Source:' | cut -f 2 -d ' ')
DEB_UPSTREAM_VERSION := $(shell dpkg-parsechangelog | egrep '^Version:' | cut -f 2 -d ' ' | cut -d: -f2- | sed 's/-[^-]*$$//')
export JAVA_HOME=/usr/lib/jvm/default-java
export CLASSPATH=$(shell for jar in `cat debian/build-classpath`; do if [ -f "$$jar" ]; then echo -n "$${jar}:"; fi; done)
export ANT_ARGS=-Dbasedir=$(realpath .) -Dpackage=$(DEB_SOURCE_PACKAGE) -f /usr/share/maven-ant-helper/maven-build.xml
%:
dh $@ --buildsystem=ant --with maven_repo_helper
We use here dh 7 for the build, with ant as the build system, and the maven\_repo\_helper plugin which will install all generated artifacts in the Maven repository
We configure ant to use the maven-ant-helper build script (/usr/share/maven-ant-helper/maven-build.xml) and the classpath defined in debian/build-classpath
libplexus-utils2-java.poms:
pom.xml --has-package-version --artifact=target/plexus-utils-*.jar --java-lib --usj-name=plexus-utils2
Install the jar as plexus-utils2.jar (--usj-name option) in /usr/share/java (--java-lib option) and install it as well in /usr/share/maven-repo with its POM file.
The jar is coming from the target/ folder used by Maven (and the maven-repo-helper script) for its builds, and we use a glob pattern (*) to match any version of the jar (--artifact option).
The option --has-package-version tells maven-repo-helper that the version of the POM matches the version of the Debian package, which is a useful hint for
mh\_make when packaging another project which uses this library.
libplexus-utils2-java-doc.poms:
target/plexus-utils.javadoc.pom --has-package-version --artifact=target/plexus-utils.javadoc.jar --classifier=javadoc --ignore-pom
Install the javadoc jar into /usr/share/maven-repo, without a POM file (--ignore-pom option) because that's the way Maven works - javadoc jars have no dedicated POM files for them. Instead, there is a classifier which tells Maven that this jar contains Javadoc (--classifier option).
The javadoc jar is packaged in libplexus-utils2-java-doc package.
libplexus-utils2-java-doc.install:
target/apidocs/* usr/share/doc/libplexus-utils2-java/api
Install the javadoc folder into /usr/share/doc/libplexus-utils2-java/api.
This folder is packaged in libplexus-utils2-java-doc package.
maven.rules:
junit junit jar s/3\..*/3.x/ * *
org.codehaus.plexus plexus-utils jar s/2\..*/2.x/ * *
org.codehaus.plexus plexus pom s/2\..*/2.x/ * *
Adapt versions for Debian in the Maven POMs, as it ease small upgrades.
- junit:junit jar dependencies with a version starting with 3. will use version 3.x instead (and libjunit-java contains a similar rule which install version 3.x in the Maven repository)
- org.codehaus.plexus:plexus-utils jar dependencies with a version starting with 2. will use version 2.x instead
- org.codehaus.plexus:plexus pom dependencies with a version starting with 2. will use version 2.x instead
DH 7 + javahelper + maven-repo-helper
-------------------------------------
debian/control:
Source: httpunit
Maintainer: Debian Java Maintainers <pkg-java-maintainers@lists.alioth.debian.org>
Uploaders: Miguel Landaeta <miguel@miguel.cc>, Michael Koch <konqueror@gmx.de>
Section: java
Priority: optional
Build-Depends: default-jdk, ant (>= 1.7.0-6), javahelper (>= 0.28),
debhelper (>= 7.0.50~), rhino (>= 1.7R1-2), libjtidy-java (>= 7+svn20070309-2),
libgnujaf-java (>= 1.1.1-4), junit (>= 3.8.2), libgnumail-java (>= 1.1.2-2),
libservlet2.4-java (>= 5.0.30-8), libxerces2-java (>= 2.9.1-2),
libnekohtml-java (>= 0.9.5+dfsg-1.1), maven-repo-helper (>= 1.7)
Standards-Version: 3.9.2
Homepage: http://httpunit.org/
Vcs-Browser: http://svn.debian.org/wsvn/pkg-java/trunk/httpunit/
Vcs-Svn: svn://svn.debian.org/svn/pkg-java/trunk/httpunit
Package: libhttpunit-java
Architecture: all
Section: java
Priority: optional
Depends: ${java:Depends}, libxerces2-java (>= 2.9.1-2), libnekohtml-java (>= 0.9.5+dfsg-1.1),
rhino (>= 1.7R1-2), libjtidy-java (>= 7+svn20070309-2), libservlet2.4-java
(>= 5.0.30-8), ${misc:Depends}
Recommends: junit (>= 3.8.2)
Suggests: libhttpunit-java-doc (= ${binary:Version})
Description: automated web site testing toolkit
[...]
Note the Build-Depends on debhelper, javahelper, ant and maven-repo-helper
debian/rules:
#!/usr/bin/make -f
%:
dh --with javahelper --with jh_maven_repo_helper $@
We use here dh 7 for the build, with javahelper as the build system (which in turn will launch Ant because build.xml exists),
and the jh\_maven\_repo\_helper plugin which is adapted to work with javahelper and will install all generated artifacts in the Maven repository.
libhttpunit-java.jlibs:
lib/httpunit.jar
We tell javahelper to install the httpunit.jar file located in lib into /usr/share/java
libhttpunit-java.poms:
debian/pom.xml --usj-name=httpunit
Create a link for the jar /usr/share/java/httpunit.jar into the Maven repository
and use debian/pom.xml as its companion metadata file
CDBS + maven-repo-helper using mh\_install
-----------------------------------------
debian/control:
Source: maven-debian-helper
Section: java
Priority: optional
Maintainer: Debian Java Maintainers <pkg-java-maintainers@lists.alioth.debian.org>
Uploaders: Torsten Werner <twerner@debian.org>, Ludovic Claude <ludovic.claude@laposte.net>,
Michael Koch <konqueror@gmx.de>, Damien Raude-Morvan <drazzib@debian.org>
Build-Depends: cdbs, debhelper (>= 7), default-jdk, maven-ant-helper (>= 7), maven-repo-helper (>= 1.7), ant-optional, help2man
Build-Depends-Indep: junit, libmaven-plugin-tools-java, libplexus-velocity-java
Standards-Version: 3.9.2
Vcs-Svn: svn://svn.debian.org/svn/pkg-java/trunk/maven-debian-helper
Vcs-Browser: http://svn.debian.org/wsvn/pkg-java/trunk/maven-debian-helper/
Homepage: http://wiki.debian.org/Java/MavenBuilder
Package: maven-debian-helper
Architecture: all
Depends: ${misc:Depends}, default-jdk, maven-repo-helper (>= 1.5), maven2 (>= 2.2.1-5),
libmaven-clean-plugin-java, libmaven-resources-plugin-java,
libmaven-compiler-plugin-java, libmaven-jar-plugin-java, libmaven-site-plugin-java,
libsurefire-java, velocity, libplexus-velocity-java
Suggests: libmaven-javadoc-plugin-java, apt-file, devscripts, subversion
Description: Helper tools for building Debian packages with Maven
[...]
Note the Build-Depends on cdbs and maven-repo-helper. maven-ant-helper and ant-optional are also needed for this package, as it's quite complex
but this is not important for this tutorial.
debian/rules:
#!/usr/bin/make -f
include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/ant.mk
PACKAGE := $(DEB_SOURCE_PACKAGE)
VERSION := $(shell echo ${DEB_UPSTREAM_VERSION} | sed -r 's/([0-9\.]+).*/\1/')
JAVA_HOME := /usr/lib/jvm/default-java
DEB_JARS := ant-nodeps classworlds maven-core maven-artifact maven-artifact-manager maven-model \
maven-compat maven-plugin-api maven-project maven-scm-api velocity file-management plexus-utils \
plexus-container-default-alpha maven-repo-helper
DEB_ANT_BUILD_TARGET := package
DEB_ANT_BUILDFILE := debian/build.xml
DEB_ANT_ARGS := -Dpackage=$(PACKAGE) -Dbin.package=$(PACKAGE)
API_DOCS := target/api
install/$(PACKAGE)::
mh_install -p$(PACKAGE)
clean::
mh_clean
This is a simplified version of debian/rules, which shows how to use the mh\_install and mh\_clean scripts from maven-repo-helper
with CDBS and Ant.
mh\_install performs the installation of the built jars into /usr/share/maven-repo and /usr/share/java. It uses the configuration defined
in maven-debian-helper.poms.
mh\_clean does the clean up of files left behind during the execution of mh\_install.
maven-debian-helper.poms:
pom.xml --no-parent --has-package-version
maven-debian-helper/pom.xml --has-package-version --artifact=maven-debian-helper/target/maven-debian-helper-*.jar --java-lib
maven-debian-plugin/pom.xml --has-package-version --artifact=maven-debian-plugin/target/maven-debian-plugin-*.jar --java-lib
maven-build-nodocs/pom.xml --has-package-version --artifact=maven-build-nodocs/target/maven-build-nodocs-*.jar --java-lib
maven-packager-utils/pom.xml --has-package-version --artifact=maven-packager-utils/target/maven-packager-utils-*.jar --java-lib
Here we tell mh\_install to deploy the maven-debian-helper project and its sub projects into /usr/share/maven-repo,
and to deploy all jars also into /usr/share/java (--java-lib option)
CDBS + maven-repo-helper using mh\_installpoms and mh\_installjar
-----------------------------------------------------------------
debian/control:
Source: plexus-io
Section: java
Priority: optional
Maintainer: Debian Java Maintainers <pkg-java-maintainers@lists.alioth.debian.org>
Uploaders: Torsten Werner <twerner@debian.org>, Ludovic Claude <ludovic.claude@laposte.net>
Build-Depends: debhelper (>= 5), cdbs (>= 0.4.5.3), default-jdk
Build-Depends-Indep: maven-repo-helper (>= 1.7), maven-ant-helper (>= 7), ant, ant-optional,
libplexus-utils-java, libplexus-containers-java
Standards-Version: 3.8.1
Vcs-Svn: svn://svn.debian.org/svn/pkg-java/trunk/plexus-io
Vcs-Browser: http://svn.debian.org/wsvn/pkg-java/trunk/plexus-io/
Homepage: http://plexus.codehaus.org/plexus-components/plexus-io/
Package: libplexus-io-java
Architecture: all
Depends: ${misc:Depends}, libplexus-utils-java, libplexus-containers-java
Description: Plexus IO Components
[...]
Note the Build-Depends on cdbs and maven-repo-helper.
debian/rules:
#!/usr/bin/make -f
include /usr/share/cdbs/1/rules/debhelper.mk
include /usr/share/cdbs/1/class/ant.mk
PACKAGE := $(DEB_SOURCE_PACKAGE)
VERSION := $(DEB_UPSTREAM_VERSION)
JAVA_HOME := /usr/lib/jvm/default-java
DEB_JARS := ant-nodeps plexus-utils plexus-container-default
DEB_ANT_BUILD_TARGET := package #javadoc
DEB_ANT_BUILDFILE := /usr/share/maven-ant-helper/maven-build.xml
DEB_ANT_ARGS := -Dbasedir=$(realpath .) -Dpackage=$(PACKAGE) -Dversion=$(VERSION)
API_DOCS := build/api
binary-post-install/lib$(PACKAGE)-java::
mh_installpoms -plib$(PACKAGE)-java
mh_installjar -plib$(PACKAGE)-java -l pom.xml build/$(PACKAGE)-$(VERSION).jar
clean::
mh_clean
No patches for the POM files are needed, all is taken care of by the mh\_installpom script (which uses mh\_cleanpom)
mh\_installpoms will install all POM files registered in debian/lib$package-java.pom into /usr/share/maven-repo,
mh\_installjar will install the jar file associated with the POM into /usr/share/maven-repo and also add a link to the jar in /usr/share/java, with and without the version
debian/libplexus-io-java.pom
pom.xml --no-parent
It simply lists the pom files in the source tree which need to be installed in the repository, and indicates with the --no-parent option that if the POM inherits
from a parent POM, then this inheritance relationship will be removed in the cleaned POM. Removing the parent inheritence can often simplify the packaging, as
the parent POM mostly does not contain any useful information - we need only the list of dependencies in our repository, the other details for the build are irrelevant.
There is less configuration here because we are using the low-level mh_installpoms and mh_installjar scripts which place the configuration on their command line options.
Typical workflow for packaging a project from source
----------------------------------------------------
1. Get the original sources and unpack them, copy the debian/ folder if you are working on an existing package.
1. mh\_make --ant
1. edit debian/rules (to fix the last remaining packaging details)
1. edit debian/control (to add maven-repo-helper to Build-Depends: )
|
