blob: f9209471fa6b5a2c6367e8358f4d7161b4ad6966 [file] [log] [blame]
Karl Paulsf87ac142007-07-06 22:36:17 +00001<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
Stuart McCulloch93de6492007-12-16 15:59:05 +00002<html><head><title>Apache Felix - Maven Bundle Plugin (BND)</title>
Karl Paulsf87ac142007-07-06 22:36:17 +00003
4
5
6
7 <link rel="stylesheet" href="maven-bundle-plugin-bnd_files/site.css" type="text/css" media="all">
Karl Paulsf87ac142007-07-06 22:36:17 +00008 <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"></head><body>
Stuart McCulloch93de6492007-12-16 15:59:05 +00009 <div class="title"><div class="logo"><a href="http://felix.apache.org/site/index.html"><img alt="Apache Felix" src="maven-bundle-plugin-bnd_files/logo.png" border="0"></a></div><div class="header"><a href="http://www.apache.org/"><img alt="Apache" src="maven-bundle-plugin-bnd_files/apache.png" border="0"></a></div></div>
Karl Paulsf87ac142007-07-06 22:36:17 +000010 <div class="menu">
Stuart McCulloch93de6492007-12-16 15:59:05 +000011<ul>
12 <li><a href="http://felix.apache.org/site/index.html" title="Index">home</a></li>
13 <li><a href="http://felix.apache.org/site/news.html" title="news">news</a></li>
14 <li><a href="http://felix.apache.org/site/status.html" title="status">status</a></li>
15 <li><a href="http://felix.apache.org/site/license.html" title="license">license</a></li>
16 <li><span class="nobr"><a href="http://felix.apache.org/site/downloads.cgi" title="Visit page outside Confluence" rel="nofollow">downloads<sup><img class="rendericon" src="maven-bundle-plugin-bnd_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span></li>
17 <li><a href="http://felix.apache.org/site/documentation.html" title="documentation">documentation</a></li>
18 <li><a href="http://felix.apache.org/site/mailinglists.html" title="mailinglists">mailing lists</a></li>
19 <li><span class="nobr"><a href="http://cwiki.apache.org/confluence/x/O-" title="Visit page outside Confluence" rel="nofollow">wiki<sup><img class="rendericon" src="maven-bundle-plugin-bnd_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span></li>
20 <li><a href="http://felix.apache.org/site/committers.html" title="committers">committers</a></li>
21 <li><a href="http://felix.apache.org/site/faq.html" title="faq">faq</a></li>
22 <li><a href="http://felix.apache.org/site/roadmap.html" title="roadmap">roadmap</a></li>
23 <li><a href="http://felix.apache.org/site/sourcecode.html" title="sourcecode">source code</a></li>
24 <li><a href="http://felix.apache.org/site/codingstandards.html" title="codingstandards">coding standards</a></li>
25 <li><a href="http://felix.apache.org/site/issuetracking.html" title="issuetracking">issue tracking</a></li>
26 <li><a href="http://felix.apache.org/site/dependencies.html" title="dependencies">dependencies</a></li>
27 <li><span class="nobr"><a href="http://www.apache.org/" title="Visit page outside Confluence" rel="nofollow">apache software foundation<sup><img class="rendericon" src="maven-bundle-plugin-bnd_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span></li>
28 <li><span class="nobr"><a href="http://www.apache.org/foundation/sponsorship.html" title="Visit page outside Confluence" rel="nofollow">sponsorship<sup><img class="rendericon" src="maven-bundle-plugin-bnd_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span></li>
29 <li><span class="nobr"><a href="http://www.apache.org/foundation/thanks.html" title="Visit page outside Confluence" rel="nofollow">sponsors<sup><img class="rendericon" src="maven-bundle-plugin-bnd_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span></li>
30</ul> </div>
Karl Paulsf87ac142007-07-06 22:36:17 +000031 <div class="main">
32<h1><a name="MavenBundlePlugin(BND)-BundlePluginforMaven"></a>Bundle Plugin for Maven</h1>
33
34<p>This plugin for Maven 2 is based on the <span class="nobr"><a href="http://www.aqute.biz/Code/Bnd" title="Visit page outside Confluence" rel="nofollow">BND<sup><img class="rendericon" src="maven-bundle-plugin-bnd_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span>
35tool from Peter Kriens. The way BND works is by treating your project
36as a big collection of classes (e.g., project code, dependencies, and
37the class path). The way you create a bundle with BND is to tell it the
38content of the bundle's JAR file as a subset of the available classes.
39This plugin wraps BND to make it work specifically with the Maven 2
40project structure and to provide it with reasonable default behavior
41for Maven 2 projects.</p>
42
43<p><a name="MavenBundlePlugin(BND)-simpleexample"></a></p>
44
45<h1><a name="MavenBundlePlugin(BND)-SimpleExample"></a>Simple Example</h1>
46
47<p>Rather than going straight to a detailed list of plugin features, we
48will first look at a simple example of how to use the plugin to give an
49immediate flavor. A detailed "<a href="#MavenBundlePlugin%2528BND%2529-howto" title="how-to on Maven Bundle Plugin (BND)">how to</a>" will follow.</p>
50
51<p>Assume that we have a simple bundle project that has a pubic API package an several implementation packages, such as:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +000052
Karl Paulsf87ac142007-07-06 22:36:17 +000053<div class="preformatted"><div class="preformattedContent">
54<pre>org.foo.myproject.api
55org.foo.myproject.impl1
56org.foo.myproject.impl2
57...
58</pre>
59</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +000060
Karl Paulsf87ac142007-07-06 22:36:17 +000061<p>If we also assume that we have a bundle activator in one of the implementation packages, then the <tt>&lt;plugins&gt;</tt> section of the POM file for this bundle project would look like this:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +000062
Karl Paulsf87ac142007-07-06 22:36:17 +000063<div class="preformatted"><div class="preformattedContent">
64<pre>...
65&lt;plugins&gt;
66 &lt;plugin&gt;
67 &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
68 &lt;artifactId&gt;maven-bundle-plugin&lt;/artifactId&gt;
69 &lt;extensions&gt;true&lt;/extensions&gt;
70 &lt;configuration&gt;
71 &lt;instructions&gt;
72 &lt;Export-Package&gt;org.foo.myproject.api&lt;/Export-Package&gt;
73 &lt;Private-Package&gt;org.foo.myproject.*&lt;/Private-Package&gt;
74 &lt;Bundle-Activator&gt;org.foo.myproject.impl1.Activator&lt;/Bundle-Activator&gt;
75 &lt;/instructions&gt;
76 &lt;/configuration&gt;
77 &lt;/plugin&gt;
78&lt;/plugins&gt;
79...
80</pre>
81</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +000082
Karl Paulsf87ac142007-07-06 22:36:17 +000083<p>The <tt>&lt;Export-Package&gt;</tt> and <tt>&lt;Private-Package&gt;</tt> instructions tell the plugin about the contents of the resulting bundle JAR file. The <tt>&lt;Export-Package&gt;</tt> instruction tells the plugin which of the available packages to copy into the bundle <b>and</b> export, while the <tt>&lt;Private-Package&gt;</tt> instruction indicates which of the available packages to copy into the bundle <b>but not</b>
84export. If the two sets overlap, as they do in the case, then the
85export takes precedence. Since we did not specify any values for any
86other bundle manifest headers, they will assume default values which
87are described <a href="#MavenBundlePlugin%2528BND%2529-defaultbehavior" title="default-behavior on Maven Bundle Plugin (BND)">below</a>. One specific behavior to highlight is that the plugin generates the <tt>Import-Package</tt>
88bundle manifest header based on the contents of the bundle, which means
89that you generally do not ever need to explicitly specify it yourself.
90That's it.</p>
91
92<h1><a name="MavenBundlePlugin(BND)-Features"></a>Features</h1>
93
94<p>The BND library underlying the plugin defines instructions to direct
95its behavior. For this Maven plugin, these instructions are issued in
96the plugin configuration section of the POM file, as was illustrated <a href="#MavenBundlePlugin%2528BND%2529-simpleexample" title="simple-example on Maven Bundle Plugin (BND)">above</a>. BND recognizes three types of instructions:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +000097
Karl Paulsf87ac142007-07-06 22:36:17 +000098<ol>
99 <li><em>Manifest headers</em> - Any instruction that starts with
100a capital letter will appear in the resulting bundle's manifest file;
101the value for the header will either be copied, augmented, or generated
102by BND depending on the instruction.</li>
103 <li><em>Variables</em> - Any instruction starting with a lowercase letter is assumed to be a variable in the form of a name-value pair, such as <tt>version=3.0</tt>, that can be used for property substitution, but is not copied to the manifest.</li>
104 <li><em>Directives</em>
105- Any instruction starting with a '-' character is considered to be a
106directive that informs BND to perform some special processing and is
107not copied to the manifest.</li>
108</ol>
109
110
111<p>The remainder of this section covers the most important aspects of BND's instructions; for complete details refer to the <span class="nobr"><a href="http://www.aqute.biz/Code/Bnd" title="Visit page outside Confluence" rel="nofollow">BND documentation<sup><img class="rendericon" src="maven-bundle-plugin-bnd_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span>.</p>
112
113<p><a name="MavenBundlePlugin(BND)-instructions"></a></p>
114
115<h2><a name="MavenBundlePlugin(BND)-Instructions"></a>Instructions</h2>
116
Karl Paulsf87ac142007-07-06 22:36:17 +0000117<h3><a name="MavenBundlePlugin(BND)-{{&lt;ExportPackage&gt;}}"></a><tt>&lt;Export-Package&gt;</tt></h3>
118
119<p>The <tt>&lt;Export-Package&gt;</tt> instruction is a list of
120packages for the bundle to export. These packages are copied into the
121resulting bundle JAR file from the available classes (i.e., project
122classes, dependencies, and class path); thus, it is possible to include
123classes into your bundle that are not associated with source files in
124your project. <tt>&lt;Export-Package&gt;</tt> can be specified with
125package patterns using the '*' wildcard. Also, it is possible to
126exclude packages using negation by starting the package pattern with
127'!'. Thus, non-negated patterns indicate which of the available
128packages to include in the bundle, whereas negated patterns indicate
129which should not be included in the bundle.</p>
130
131<p>The list of package patterns is ordered and earlier patterns are applied before later patterns. For example, if you specify "<tt>org.foo.*,!org.foo.impl</tt>" the second pattern has no effect since all <tt>org.foo</tt> packages have already been selected by the first pattern. Instead, you should specify "<tt>!org.foo.impl,org.foo.*</tt>", which will export all <tt>org.foo</tt> packages except <tt>org.foo.impl</tt>.</p>
132
133<p>Following standard OSGi R4 syntax, package patterns can include both
134directives and attributes, which will be copied appropriately into the
135generated Export-Package manifest header. Besides explicitly listing
136package version attributes, BND will also determine package versions by
137examining the source JAR file or from <tt>packageinfo</tt> files in the package directory.</p>
138
139<h3><a name="MavenBundlePlugin(BND)-{{&lt;PrivatePackage&gt;}}"></a><tt>&lt;Private-Package&gt;</tt></h3>
140
141<p>The <tt>&lt;Private-Package&gt;</tt> instruction is similar in every way to the <tt>&lt;Export-Package&gt;</tt> instruction, except for the fact that these packages will <b>not</b>
142be exported by the bundle. If a package is selected by both the export
143and private package headers, then the export takes precedence.</p>
144
145<h3><a name="MavenBundlePlugin(BND)-{{&lt;IncludeResource&gt;}}"></a><tt>&lt;Include-Resource&gt;</tt></h3>
146
147<p>The <tt>&lt;Include-Resource&gt;</tt> instruction is a list of
148arbitrary resources that should be copied into the bundle JAR file. The
149specified resources are declared as clauses that can have the following
150forms:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000151
Karl Paulsf87ac142007-07-06 22:36:17 +0000152<div class="preformatted"><div class="preformattedContent">
153<pre>clause ::= assignment | inline | simple
154assignment ::= PATH '=' PATH
155simple ::= PATH
156inline ::= '@' PATH
157</pre>
158</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000159
Karl Paulsf87ac142007-07-06 22:36:17 +0000160<p>For the <tt>&lt;Include-Resource&gt;</tt> instruction, actual file paths are relative to the <tt>pom.xml</tt>, while file copy destinations are relative to the root of the resulting bundle JAR file. In the case of <tt>assignment</tt> or <tt>simple</tt> forms, the <tt>PATH</tt> parameter can point to a file or directory. The <tt>simple</tt>
161form will place the resource in the bundle JAR with only the file name,
162i.e., without any path component. For example, including <tt>src/main/resources/a/b.c</tt> will result in a resource <tt>b.c</tt> in the root of the bundle JAR. If the <tt>PATH</tt>
163points to a directory, the entire directory hierarchy is copied into
164the resulting bundle JAR file relative to the specified directory. If a
165specific resource must be placed into a subdirectory of the bundle jar,
166then use the <tt>assignment</tt> form, where the first path is the the
167destination path (including file name if the resource is a file) and
168the second path is the resource to copy. The <tt>inline</tt> form requires a ZIP or JAR file, which will be completely expanded in the bundle JAR.</p>
169
170<p>If a resource clause is specified inside of "{ ... }" brackets, then
171variable substitution will be performed on the resource, where
172variables in the resources are denoted with "${ ... }" syntax.</p>
173
174<h3><a name="MavenBundlePlugin(BND)-{{&lt;ImportPackage&gt;}}"></a><tt>&lt;Import-Package&gt;</tt></h3>
175
176<p>The <tt>&lt;Import-Package&gt;</tt> instruction is a list of
177packages that are required by the bundle's contained packages. The
178default for this header is "*", resulting in importing all referred
179packages. This header rarely has to be explicitly specified. However,
180in certain cases when there is an unwanted import, such an import can
181be removed by using a negation package pattern. The package patterns
182work in the same way as for <tt>&lt;Export-Package&gt;</tt>, which means they are ordered. For example, if you wanted to import all packages except <tt>org.foo.impl</tt> you would specify "<tt>!org.foo.impl,*</tt>"</p>
183
184<p><a name="MavenBundlePlugin(BND)-defaultbehavior"></a></p>
185
186<h2><a name="MavenBundlePlugin(BND)-DefaultBehavior"></a>Default Behavior</h2>
187
188<p>To use this plugin, very little information is required by BND. As
189part of the Maven integration, the plugin tries to set reasonable
190defaults for various instructions. For example:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000191
Karl Paulsf87ac142007-07-06 22:36:17 +0000192<ul>
193 <li><tt>&lt;Bundle-SymbolicName&gt;</tt> is assumed to be "<tt>${groupId}.${artifactId</tt>}".</li>
194 <li><tt>&lt;Export-Package&gt;</tt> is assumed to be "<tt>${groupId}.${artifactId}.*</tt>", unless <tt>&lt;Private-Package&gt;</tt> is specified, then <tt>&lt;Export-Package&gt;</tt> is assumed to be empty.</li>
195 <li><tt>&lt;Private-Package&gt;</tt> is assumed to be empty by default.</li>
196 <li><tt>&lt;Import-Package&gt;</tt> is assumed to be "<tt>*</tt>", which imports everything referred to by the bundle content, but not contained in the bundle.</li>
197 <li><tt>&lt;Include-Resource&gt;</tt> is assumed to be "<tt>src/main/resources/</tt>",
198which will copy the specified project directory hierarchy into the
199resulting bundle JAR file, mirroring standard Maven behavior.</li>
200 <li><tt>&lt;Bundle-Version&gt;</tt> is assumed to be "<tt>${pom.version</tt>}" with '-' character separator of the qualifier replaced with a '.' character.</li>
201 <li><tt>&lt;Bundle-Name&gt;</tt> is assumed to be "<tt>${pom.name</tt>}".</li>
202 <li><tt>&lt;Bundle-Description&gt;</tt> is assumed to be "<tt>${pom.description</tt>}".</li>
203 <li><tt>&lt;Bundle-License&gt;</tt> is assumed to be "<tt>${pom.licenses</tt>}".</li>
204 <li><tt>&lt;Bundle-Vendor&gt;</tt> is assumed to be "<tt>${pom.organization.name</tt>}".</li>
205 <li><tt>&lt;Bundle-DocURL&gt;</tt> is assumed to be "<tt>${pom.organization.url</tt>}".</li>
206</ul>
207
208
209<p>Since the plugin creates bundles for OSGi R4, it hard codes <tt>Bundle-ManifestVersion</tt>
210to be '2'. Additionally, it generates imports for every export to
211ensure package substitutability, which is very important when working
212with collaborating services. It is possible to override any of these
213values (except <tt>Bundle-ManifestVersion</tt>) just by specifying the desired value in the plugin configuration section of the POM file.</p>
214
215<p><a name="MavenBundlePlugin(BND)-howto"></a></p>
216
217<h1><a name="MavenBundlePlugin(BND)-Detailed&quot;HowTo&quot;"></a>Detailed "How To"</h1>
218
219<h2><a name="MavenBundlePlugin(BND)-GetMaven2"></a>Get Maven2</h2>
220
221<p>The first step in the process of using the plugin is downloading and
222installing the latest version of the Maven2 runtime. The latest Maven2
223release and instuctions for getting started with Maven2 can be found at
224the <span class="nobr"><a href="http://maven.apache.org/index.html" title="Visit page outside Confluence" rel="nofollow">Maven website<sup><img class="rendericon" src="maven-bundle-plugin-bnd_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span>.</p>
225
226<h2><a name="MavenBundlePlugin(BND)-UsingthePlugin"></a>Using the Plugin</h2>
227
228<p>To use the maven-bundle-plugin, you first need to add the plugin and
229some appropriate plugin configuration to your bundle project's POM.
230Below is an example of a simple OSGi bundle POM for Maven2:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000231
Karl Paulsf87ac142007-07-06 22:36:17 +0000232<div class="preformatted"><div class="preformattedContent">
233<pre>&lt;project&gt;
234 &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
235 &lt;groupId&gt;my-osgi-bundles&lt;/groupId&gt;
236 &lt;artifactId&gt;examplebundle&lt;/artifactId&gt;
237 &lt;packaging&gt;bundle&lt;/packaging&gt; &lt;!-- (1) --&gt;
238 &lt;version&gt;1.0&lt;/version&gt;
239 &lt;name&gt;Example Bundle&lt;/name&gt;
240 &lt;dependencies&gt;
241 &lt;dependency&gt;
242 &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
243 &lt;artifactId&gt;org.osgi.core&lt;/artifactId&gt;
244 &lt;version&gt;0.8.0-incubator&lt;/version&gt;
245 &lt;/dependency&gt;
246 &lt;/dependencies&gt;
247 &lt;build&gt;
248 &lt;plugins&gt;
249 &lt;plugin&gt; &lt;!-- (2) START --&gt;
250 &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
251 &lt;artifactId&gt;maven-bundle-plugin&lt;/artifactId&gt;
252 &lt;extensions&gt;true&lt;/extensions&gt;
253 &lt;configuration&gt;
254 &lt;instructions&gt;
255 &lt;Export-Package&gt;com.my.company.api&lt;/Export-Package&gt;
256 &lt;Private-Package&gt;com.my.company.*&lt;/Private-Package&gt;
257 &lt;Bundle-Activator&gt;com.my.company.Activator&lt;/Bundle-Activator&gt;
258 &lt;/instructions&gt;
259 &lt;/configuration&gt;
260 &lt;/plugin&gt; &lt;!-- (2) END --&gt;
261 &lt;/plugins&gt;
262 &lt;/build&gt;
Karl Paulsf87ac142007-07-06 22:36:17 +0000263&lt;/project&gt;
264</pre>
265</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000266
267<p>There are two main things to note: (1) the <tt>&lt;packaging&gt;</tt>
268specifier must be "bundle" and (2) the plugin and configuration must be
Karl Paulsf87ac142007-07-06 22:36:17 +0000269specified (the configuration section is where you will issue
Stuart McCulloch93de6492007-12-16 15:59:05 +0000270instructions to the plugin).</p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000271
272<h2><a name="MavenBundlePlugin(BND)-RealWorldExample"></a>Real-World Example</h2>
273
274<p>Consider this more real-world example using Felix' Log Service
275implementation. The Log Service project is comprised of a single
276package: <tt>org.apache.felix.log.impl</tt>. It has a dependency on
277the core OSGi interfaces as well as a dependency on the compendium OSGi
278interfaces for the specific log service interfaces. The following is
279its POM file:</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000280
Karl Paulsf87ac142007-07-06 22:36:17 +0000281<div class="preformatted"><div class="preformattedContent">
282<pre>&lt;project&gt;
283 &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
284 &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
285 &lt;artifactId&gt;org.apache.felix.log&lt;/artifactId&gt;
286 &lt;packaging&gt;bundle&lt;/packaging&gt;
287 &lt;name&gt;Apache Felix Log Service&lt;/name&gt;
288 &lt;version&gt;0.8.0-SNAPSHOT&lt;/version&gt;
289 &lt;description&gt;
290 This bundle provides an implementation of the OSGi R4 Log service.
291 &lt;/description&gt;
292 &lt;dependencies&gt;
293 &lt;dependency&gt;
294 &lt;groupId&gt;${pom.groupId}&lt;/groupId&gt;
295 &lt;artifactId&gt;org.osgi.core&lt;/artifactId&gt;
296 &lt;version&gt;0.8.0-incubator&lt;/version&gt;
297 &lt;/dependency&gt;
298 &lt;dependency&gt;
299 &lt;groupId&gt;${pom.groupId}&lt;/groupId&gt;
300 &lt;artifactId&gt;org.osgi.compendium&lt;/artifactId&gt;
301 &lt;version&gt;0.9.0-incubator-SNAPSHOT&lt;/version&gt;
302 &lt;/dependency&gt;
303 &lt;/dependencies&gt;
304 &lt;build&gt;
305 &lt;plugins&gt;
306 &lt;plugin&gt;
307 &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
308 &lt;artifactId&gt;maven-bundle-plugin&lt;/artifactId&gt;
309 &lt;extensions&gt;true&lt;/extensions&gt;
310 &lt;configuration&gt;
311 &lt;instructions&gt;
312 &lt;Export-Package&gt;org.osgi.service.log&lt;/Export-Package&gt;
313 &lt;Private-Package&gt;org.apache.felix.log.impl&lt;/Private-Package&gt;
314 &lt;Bundle-SymbolicName&gt;${pom.artifactId}&lt;/Bundle-SymbolicName&gt;
315 &lt;Bundle-Activator&gt;${pom.artifactId}.impl.Activator&lt;/Bundle-Activator&gt;
316 &lt;Export-Service&gt;org.osgi.service.log.LogService,org.osgi.service.log.LogReaderService&lt;/Export-Service&gt;
317 &lt;/instructions&gt;
318 &lt;/configuration&gt;
319 &lt;/plugin&gt;
320 &lt;/plugins&gt;
321 &lt;/build&gt;
Karl Paulsf87ac142007-07-06 22:36:17 +0000322&lt;/project&gt;
323</pre>
324</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000325
Karl Paulsf87ac142007-07-06 22:36:17 +0000326<p>Notice that the <tt>&lt;Export-Package&gt;</tt> instruction
327specifies that the bundle exports the Log Service package, even though
328this package is not contained in the bundle project. By declaring this,
329the plugin will copy the Log Service package into the resulting bundle
330JAR file. This is useful in this case because now the bundle can
331resolve without having to download the entire compendium bundle. The
332resulting manifest for the Log Service bundle looks like this (notice
333how the imports/exports automatically have version information
334associated with them, which was obtained from packageinfo files in the
335source packages):</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000336
Karl Paulsf87ac142007-07-06 22:36:17 +0000337<div class="preformatted"><div class="preformattedContent">
338<pre>Manifest-Version: 1
339Bundle-License: http://www.apache.org/licenses/LICENSE-2.0.txt
340Bundle-Activator: org.apache.felix.log.impl.Activator
341Import-Package: org.osgi.framework;version=1.3, org.osgi.service.log;v
342 ersion=1.3
343Include-Resource: src/main/resources
344Export-Package: org.osgi.service.log;uses:=org.osgi.framework;version=
345 1.3
346Bundle-Version: 0.8.0.SNAPSHOT
347Bundle-Name: Apache Felix Log Service
348Bundle-Description: This bundle provides an implementation of the OSGi
349 R4 Log service.
350Private-Package: org.apache.felix.log.impl
351Bundle-ManifestVersion: 2
352Export-Service: org.osgi.service.log.LogService,org.osgi.service.log.L
353 ogReaderService
354Bundle-SymbolicName: org.apache.felix.log
355</pre>
356</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000357
Karl Paulsf87ac142007-07-06 22:36:17 +0000358<p>The resulting bundle JAR file has the following content (notice how
359the LICENSE and NOTICE files were automatically copied from the <tt>src/main/resources/</tt> directory of the project):</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000360
Karl Paulsf87ac142007-07-06 22:36:17 +0000361<div class="preformatted"><div class="preformattedContent">
362<pre>META-INF/MANIFEST.MF
363LICENSE
364META-INF/
365META-INF/maven/
366META-INF/maven/org.apache.felix/
367META-INF/maven/org.apache.felix/org.apache.felix.log/
368META-INF/maven/org.apache.felix/org.apache.felix.log/pom.properties
369META-INF/maven/org.apache.felix/org.apache.felix.log/pom.xml
370NOTICE
371org/
372org/apache/
373org/apache/felix/
374org/apache/felix/log/
375org/apache/felix/log/impl/
376org/apache/felix/log/impl/Activator.class
377org/apache/felix/log/impl/Log.class
378org/apache/felix/log/impl/LogEntryImpl.class
379org/apache/felix/log/impl/LogException.class
380org/apache/felix/log/impl/LogListenerThread.class
381org/apache/felix/log/impl/LogNode.class
382org/apache/felix/log/impl/LogNodeEnumeration.class
383org/apache/felix/log/impl/LogReaderServiceFactory.class
384org/apache/felix/log/impl/LogReaderServiceImpl.class
385org/apache/felix/log/impl/LogServiceFactory.class
386org/apache/felix/log/impl/LogServiceImpl.class
387org/osgi/
388org/osgi/service/
389org/osgi/service/log/
390org/osgi/service/log/LogEntry.class
391org/osgi/service/log/LogListener.class
392org/osgi/service/log/LogReaderService.class
393org/osgi/service/log/LogService.class
394org/osgi/service/log/package.html
395org/osgi/service/log/packageinfo
396</pre>
397</div></div>
398
399<h2><a name="MavenBundlePlugin(BND)-BuildingthePlugin"></a>Building the Plugin</h2>
400
Stuart McCulloch93de6492007-12-16 15:59:05 +0000401<p>The plugin is hosted at the Apache Felix project. The following
402steps describe how to build and install the plugin into your local
403Maven2 repository.</p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000404
405<p>Using the SVN client of your choice, checkout the maven-bundle-plugin project.</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000406
Karl Paulsf87ac142007-07-06 22:36:17 +0000407<div class="preformatted"><div class="preformattedContent">
Stuart McCulloch93de6492007-12-16 15:59:05 +0000408<pre>$ svn co http://svn.apache.org/repos/asf/felix/trunk/bundleplugin
Karl Paulsf87ac142007-07-06 22:36:17 +0000409</pre>
410</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000411
Karl Paulsf87ac142007-07-06 22:36:17 +0000412<p>Using Maven2, build and install the maven-bundle-plugin by issuing
413the following Maven2 command in the project directory that was created
414as a result of the previous step.</p>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000415
Karl Paulsf87ac142007-07-06 22:36:17 +0000416<div class="preformatted"><div class="preformattedContent">
417<pre>$ mvn install
418</pre>
419</div></div>
Stuart McCulloch93de6492007-12-16 15:59:05 +0000420
421<h1><a name="MavenBundlePlugin(BND)-Goals"></a>Goals</h1>
422
423<p>The maven-bundle-plugin also provides additional functionality via
424some Maven goals. Command-line execution of a goal is performed as
425follows:</p>
426
427<div class="preformatted"><div class="preformattedContent">
428<pre>mvn org.apache.felix:maven-bundle-plugin:GOAL
429</pre>
430</div></div>
431
432<p>Where GOAL is one of the following:</p>
433
434<ul>
435 <li><tt>bundle</tt> - build an OSGi bundle jar<br>
436configuration options:
437 <ul>
438 <li><tt>manifestLocation</tt> defaults to ${project.build.outputDirectory}/META-INF</li>
439 <li><tt>unpackBundle</tt> unpack bundle contents to output directory, defaults to false</li>
440 <li><tt>supportedProjectTypes</tt> defaults to "jar","bundle"</li>
441 </ul>
442 </li>
443 <li><tt>bundleall</tt> - build an OSGi bundle jar for all transitive dependencies<br>
444configuration options:
445 <ul>
446 <li><tt>supportedProjectTypes</tt> defaults to "jar","bundle"</li>
447 </ul>
448 </li>
449 <li><tt>wrap</tt> - as above, but limited to the first level of dependencies<br>
450configuration options:
451 <ul>
452 <li><tt>supportedProjectTypes</tt> defaults to "jar","bundle"</li>
453 </ul>
454 </li>
455 <li><tt>manifest</tt> - create an OSGi manifest for the current project<br>
456configuration options:
457 <ul>
458 <li><tt>manifestLocation</tt> defaults to ${project.build.outputDirectory}/META-INF</li>
459 <li><tt>supportedProjectTypes</tt> defaults to "jar","bundle"</li>
460 </ul>
461 </li>
462</ul>
463
464
465<p>There are also new instructions available from the underlying BND
466tool, which continues to be improved independently; for the latest see <span class="nobr"><a href="http://aqute.biz/Code/Bnd" title="Visit page outside Confluence" rel="nofollow">BND documentation<sup><img class="rendericon" src="maven-bundle-plugin-bnd_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span>.</p>
467
468<p>The default goal <tt>bundle</tt> will be initialized by setting the &lt;packaging&gt; entry to "bundle".</p>
469
470<h1><a name="MavenBundlePlugin(BND)-Embeddingdependencies"></a>Embedding dependencies</h1>
471
472<p>The Maven Bundle Plugin supports embedding project dependencies into the built bundle using the <tt>&lt;Embed-Dependency&gt;</tt> instruction listing all dependencies in standard Bundle manifest header syntax:</p>
473
474<div class="code"><div class="codeContent">
475<pre class="code-xml"><span class="code-tag">&lt;Embed-Dependency&gt;</span>dependencies<span class="code-tag">&lt;/Embed-Dependency&gt;</span></pre>
476</div></div>
477
478<p>where:</p>
479
480<div class="preformatted"><div class="preformattedContent">
481<pre>dependencies ::= clause ( ',' clause ) *
482clause ::= MATCH ( ';' attr '=' MATCH | ';inline=true' )
483attr ::= 'groupId' | 'artifactId' | 'version' | 'scope' | 'type' | 'classifier'
484MATCH ::= &lt;globbed regular expressions&gt;
485</pre>
486</div></div>
487
488<p>some examples:</p>
489
490<div class="code"><div class="codeContent">
491<pre class="code-xml"><span class="code-tag">&lt;Embed-Dependency&gt;</span>*;scope=compile|runtime<span class="code-tag">&lt;/Embed-Dependency&gt;</span>
492
493<span class="code-tag">&lt;Embed-Dependency&gt;</span>junit;scope=test<span class="code-tag">&lt;/Embed-Dependency&gt;</span>
494
495<span class="code-tag">&lt;Embed-Dependency&gt;</span>aopalliance;scope=!test;inline=true<span class="code-tag">&lt;/Embed-Dependency&gt;</span></pre>
496</div></div>
497
498<p>By default matched dependencies are embedded in the bundle under as <tt>artifactId-version.jar</tt>. This behaviour can be modified using the following instructions:</p>
499
500<ul>
501 <li><tt>&lt;Embed-StripVersion&gt;true&lt;/Embed-StripVersion&gt;</tt> - removes the version from the file (ie. <em>artifactId.jar</em>)</li>
502 <li><tt>&lt;Embed-StripGroup&gt;false&lt;/Embed-StripGroup&gt;</tt> - adds the groupId as a subdirectory (ie. <em>groupId/artifactId-version.jar</em>)</li>
503 <li><tt>&lt;Embed-Directory&gt;directory&lt;/Embed-Directory&gt;</tt> - adds a subdirectory (ie. <em>directory/artifactId-version.jar</em>)</li>
504</ul>
505
506
507<p>Normally the plugin only checks direct dependencies, but this can be
508changed to include the complete set of transitive dependencies with the
509following option:</p>
510
511<div class="code"><div class="codeContent">
512<pre class="code-xml"><span class="code-tag">&lt;Embed-Transitive&gt;</span>true<span class="code-tag">&lt;/Embed-Transitive&gt;</span></pre>
513</div></div>
514
515<p>If you want a dependency inlined instead of embedded add the <tt>inline=true</tt>. For example to inline all <em>compile</em> and <em>runtime</em> scoped dependencies use:</p>
516
517<div class="code"><div class="codeContent">
518<pre class="code-xml"><span class="code-tag">&lt;Embed-Dependency&gt;</span>*;scope=compile|runtime;inline=true<span class="code-tag">&lt;/Embed-Dependency&gt;</span></pre>
519</div></div>
520
521
522<h1><a name="MavenBundlePlugin(BND)-OBRintegration"></a>OBR integration</h1>
523
524<p>The latest Maven Bundle Plugin automatically updates the local OBR
525repository.xml file during the install phase, using a default location
526of:</p>
527
528<div class="code"><div class="codeContent">
529<pre class="code-java">&lt;LOCAL-MAVEN-REPOSITORY&gt;/repository.xml</pre>
530</div></div>
531
532<p>You can configure the location of the OBR repository by using the command line:</p>
533
534<div class="code"><div class="codeContent">
535<pre class="code-java">mvn clean install -DobrRepository=&lt;PATH_TO_OBR&gt;</pre>
536</div></div>
537
538<p>or in the configuration section for the maven-bundle-plugin in your Maven POM:</p>
539
540<div class="code"><div class="codeContent">
541<pre class="code-xml"><span class="code-tag">&lt;groupId&gt;</span>org.apache.felix<span class="code-tag">&lt;/groupId&gt;</span>
542<span class="code-tag">&lt;artifactId&gt;</span>maven-bundle-plugin<span class="code-tag">&lt;/artifactId&gt;</span>
543<span class="code-tag">&lt;extensions&gt;</span>true<span class="code-tag">&lt;/extensions&gt;</span>
544<span class="code-tag">&lt;configuration&gt;</span>
545 <span class="code-tag">&lt;obrRepository&gt;</span>PATH_TO_OBR<span class="code-tag">&lt;/obrRepository&gt;</span>
546 <span class="code-tag">&lt;instructions&gt;</span>
547 <span class="code-tag"><span class="code-comment">&lt;!-- bnd instructions --&gt;</span></span>
548 <span class="code-tag">&lt;/instructions&gt;</span>
549<span class="code-tag">&lt;/configuration&gt;</span></pre>
550</div></div>
551
552<p>to disable OBR installation set the obrRepository to NONE, for example:</p>
553
554<div class="code"><div class="codeContent">
555<pre class="code-xml"><span class="code-tag">&lt;groupId&gt;</span>org.apache.felix<span class="code-tag">&lt;/groupId&gt;</span>
556<span class="code-tag">&lt;artifactId&gt;</span>maven-bundle-plugin<span class="code-tag">&lt;/artifactId&gt;</span>
557<span class="code-tag">&lt;extensions&gt;</span>true<span class="code-tag">&lt;/extensions&gt;</span>
558<span class="code-tag">&lt;configuration&gt;</span>
559 <span class="code-tag">&lt;obrRepository&gt;</span>NONE<span class="code-tag">&lt;/obrRepository&gt;</span>
560 <span class="code-tag">&lt;instructions&gt;</span>
561 <span class="code-tag"><span class="code-comment">&lt;!-- bnd instructions --&gt;</span></span>
562 <span class="code-tag">&lt;/instructions&gt;</span>
563<span class="code-tag">&lt;/configuration&gt;</span></pre>
564</div></div>
565
566
567<h1><a name="MavenBundlePlugin(BND)-Eclipse/PDEintegration"></a>Eclipse/PDE integration</h1>
568
569<p>It is possible to configure the Maven Bundle Plugin to put the
570bundle manifest where Eclipse/PDE expects it, and use the Maven
571Dependency Plugin to arrange for any embedded dependencies to appear in
572a local directory that matches the Bundle-ClassPath entries. Here is an
573example POM that does this:</p>
574
575<div class="preformatted"><div class="preformattedContent">
576<pre>&lt;project&gt;
577
578 &lt;properties&gt;
579 &lt;bundle.symbolicName&gt;org.example&lt;/bundle.symbolicName&gt;
580 &lt;bundle.namespace&gt;org.example&lt;/bundle.namespace&gt;
581 &lt;/properties&gt;
582
583 &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
584 &lt;groupId&gt;examples&lt;/groupId&gt;
585 &lt;artifactId&gt;org.example&lt;/artifactId&gt;
586 &lt;version&gt;1.0-SNAPSHOT&lt;/version&gt;
587
588 &lt;name&gt;${bundle.symbolicName} [${bundle.namespace}]&lt;/name&gt;
589
590 &lt;packaging&gt;bundle&lt;/packaging&gt;
591
592 &lt;build&gt;
593 &lt;plugins&gt;
594 &lt;plugin&gt;
595 &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
596 &lt;artifactId&gt;maven-bundle-plugin&lt;/artifactId&gt;
597 &lt;version&gt;1.1.0-SNAPSHOT&lt;/version&gt;
598 &lt;extensions&gt;true&lt;/extensions&gt;
599 &lt;!--
600 the following instructions build a simple set of public/private classes into an OSGi bundle
601 --&gt;
602 &lt;configuration&gt;
603 &lt;manifestLocation&gt;META-INF&lt;/manifestLocation&gt;
604 &lt;instructions&gt;
605 &lt;Bundle-SymbolicName&gt;${bundle.symbolicName}&lt;/Bundle-SymbolicName&gt;
606 &lt;Bundle-Version&gt;${pom.version}&lt;/Bundle-Version&gt;
607 &lt;!--
608 assume public classes are in the top package, and private classes are under ".internal"
609 --&gt;
610 &lt;Export-Package&gt;${bundle.namespace};version="${pom.version}"&lt;/Export-Package&gt;
611 &lt;Private-Package&gt;${bundle.namespace}.internal&lt;/Private-Package&gt;
612 &lt;Bundle-Activator&gt;${bundle.namespace}.internal.Activator&lt;/Bundle-Activator&gt;
613 &lt;!--
614 embed compile/runtime dependencies using path that matches the copied dependency folder
615 --&gt;
616 &lt;Embed-Dependency&gt;*;scope=compile|runtime;inline=false&lt;/Embed-Dependency&gt;
617 &lt;Embed-Directory&gt;target/dependency&lt;/Embed-Directory&gt;
618 &lt;Embed-StripGroup&gt;true&lt;/Embed-StripGroup&gt;
619 &lt;/instructions&gt;
620 &lt;/configuration&gt;
621 &lt;/plugin&gt;
622 &lt;plugin&gt;
623 &lt;artifactId&gt;maven-dependency-plugin&lt;/artifactId&gt;
624 &lt;executions&gt;
625 &lt;execution&gt;
626 &lt;id&gt;copy-dependencies&lt;/id&gt;
627 &lt;phase&gt;package&lt;/phase&gt;
628 &lt;goals&gt;
629 &lt;goal&gt;copy-dependencies&lt;/goal&gt;
630 &lt;/goals&gt;
631 &lt;/execution&gt;
632 &lt;/executions&gt;
633 &lt;/plugin&gt;
634 &lt;/plugins&gt;
635 &lt;/build&gt;
636
637 &lt;dependencies&gt;
638 &lt;dependency&gt;
639 &lt;groupId&gt;org.osgi&lt;/groupId&gt;
640 &lt;artifactId&gt;osgi_R4_core&lt;/artifactId&gt;
641 &lt;version&gt;1.0&lt;/version&gt;
642 &lt;scope&gt;provided&lt;/scope&gt;
643 &lt;optional&gt;true&lt;/optional&gt;
644 &lt;/dependency&gt;
645 &lt;dependency&gt;
646 &lt;groupId&gt;org.osgi&lt;/groupId&gt;
647 &lt;artifactId&gt;osgi_R4_compendium&lt;/artifactId&gt;
648 &lt;version&gt;1.0&lt;/version&gt;
649 &lt;scope&gt;provided&lt;/scope&gt;
650 &lt;optional&gt;true&lt;/optional&gt;
651 &lt;/dependency&gt;
652 &lt;dependency&gt;
653 &lt;groupId&gt;junit&lt;/groupId&gt;
654 &lt;artifactId&gt;junit&lt;/artifactId&gt;
655 &lt;version&gt;3.8.1&lt;/version&gt;
656 &lt;scope&gt;compile&lt;/scope&gt;
657 &lt;optional&gt;true&lt;/optional&gt;
658 &lt;/dependency&gt;
659 &lt;/dependencies&gt;
660
661&lt;/project&gt;
662</pre>
663</div></div>
664
665<p>To generate the Eclipse metadata use:</p>
666
667<div class="code"><div class="codeContent">
668<pre class="code-java">mvn clean <span class="code-keyword">package</span> eclipse:eclipse -Declipse.pde install</pre>
669</div></div>
670
671<p>and you should now be able to import this as an existing Eclipse project.</p>
672
673<p>FYI: the above POM was generated using the <tt>pax-create-bundle</tt> command from <span class="nobr"><a href="http://www.ops4j.org/projects/pax/construct/index.html" title="Visit page outside Confluence" rel="nofollow">Pax-Construct<sup><img class="rendericon" src="maven-bundle-plugin-bnd_files/linkext7.gif" alt="" align="absmiddle" border="0" height="7" width="7"></sup></a></span> and then tweaked to demonstrate using the Maven Dependency Plugin to handle embedded jars in Eclipse.</p>
674
675<p>With the original Pax-Construct generated POM you would simply use:</p>
676
677<div class="code"><div class="codeContent">
678<pre class="code-java">mvn clean <span class="code-keyword">package</span> pax:eclipse</pre>
679</div></div>
680
681<p>to create the appropriate Eclipse files and manifest, and also
682handle any embedded entries. The pax:eclipse goal extends
683eclipse:eclipse, and supports the same parameters.</p>
684
685<h1><a name="MavenBundlePlugin(BND)-Unpackingbundlecontentsto'target/classes'"></a>Unpacking bundle contents to 'target/classes'</h1>
686
687<p>Once in a while you may create a bundle which contains additional classes to the ones compiled from <tt>src/main/java</tt>,
688for example when you embed the classes from another jar. This can
689sometimes cause unforeseen problems in Maven, as it will use the output
690directory (<tt>target/classes</tt>) rather than the final bundle, when compiling against projects in the same reactor (ie. the same build).</p>
691
692<p>The easiest way to get around this Maven 'feature' is to unpack the
693contents of the bundle to the output directory after the packaging
694step, so the additional classes will be found where Maven expects them.
695Thankfully there is now an easy option to do this in the bundle-plugin:</p>
696
697<div class="code"><div class="codeContent">
698<pre class="code-java">&lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
699&lt;artifactId&gt;maven-bundle-plugin&lt;/artifactId&gt;
700&lt;extensions&gt;<span class="code-keyword">true</span>&lt;/extensions&gt;
701&lt;configuration&gt;
702 &lt;unpackBundle&gt;<span class="code-keyword">true</span>&lt;/unpackBundle&gt;
703 &lt;instructions&gt;
704 &lt;!-- bnd instructions --&gt;
705 &lt;/instructions&gt;
706&lt;/configuration&gt;</pre>
707</div></div>
708
709<h1><a name="MavenBundlePlugin(BND)-UsinganexistingMANIFEST.MFfile"></a>Using an existing MANIFEST.MF file</h1>
710
711<p>If you have an existing manifest, you can add this to the Bnd instructions, like so:</p>
712
713<div class="code"><div class="codeContent">
714<pre class="code-java">&lt;_include&gt;src/main/resources/META-INF/MANIFEST.MF&lt;/_include&gt;
715&lt;Export-Package&gt;org.example.*&lt;/Export-Package&gt;</pre>
716</div></div>
717
718<p>Bnd will use it when calculating the bundle contents, and will also
719copy across all manifest attributes starting with a capital letter.<br>
720As shown in the above example, you could use this to include a non-OSGi
721manifest which you then customize with extra OSGi attributes.</p>
722
723<h1><a name="MavenBundlePlugin(BND)-Feedback"></a>Feedback</h1>
724
725<p>Subscribe to the Felix users mailing list by sending a message to <span class="nobr"><a href="mailto:users-subscribe@felix.apache.org" title="Send mail to users-subscribe@felix.apache.org" rel="nofollow">users-subscribe@felix.apache.org<sup><img class="rendericon" src="maven-bundle-plugin-bnd_files/mail_small.gif" alt="" align="absmiddle" border="0" height="12" width="13"></sup></a></span>; after subscribing, email questions or feedback to <span class="nobr"><a href="mailto:users@felix.apache.org" title="Send mail to users@felix.apache.org" rel="nofollow">users@felix.apache.org<sup><img class="rendericon" src="maven-bundle-plugin-bnd_files/mail_small.gif" alt="" align="absmiddle" border="0" height="12" width="13"></sup></a></span>.</p>
Karl Paulsf87ac142007-07-06 22:36:17 +0000726 </div>
727
Stuart McCulloch93de6492007-12-16 15:59:05 +0000728</body></html>