Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 1 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 2 | <html><head><title>Apache Felix - Maven Bundle Plugin (BND)</title> |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 3 | |
| 4 | |
| 5 | |
| 6 | |
| 7 | <link rel="stylesheet" href="maven-bundle-plugin-bnd_files/site.css" type="text/css" media="all"> |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 8 | <meta http-equiv="Content-Type" content="text/html;charset=UTF-8"></head><body> |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 9 | <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 Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 10 | <div class="menu"> |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 11 | <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 Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 31 | <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> |
| 35 | tool from Peter Kriens. The way BND works is by treating your project |
| 36 | as a big collection of classes (e.g., project code, dependencies, and |
| 37 | the class path). The way you create a bundle with BND is to tell it the |
| 38 | content of the bundle's JAR file as a subset of the available classes. |
| 39 | This plugin wraps BND to make it work specifically with the Maven 2 |
| 40 | project structure and to provide it with reasonable default behavior |
| 41 | for 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 |
| 48 | will first look at a simple example of how to use the plugin to give an |
| 49 | immediate 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 McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 52 | |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 53 | <div class="preformatted"><div class="preformattedContent"> |
| 54 | <pre>org.foo.myproject.api |
| 55 | org.foo.myproject.impl1 |
| 56 | org.foo.myproject.impl2 |
| 57 | ... |
| 58 | </pre> |
| 59 | </div></div> |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 60 | |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 61 | <p>If we also assume that we have a bundle activator in one of the implementation packages, then the <tt><plugins></tt> section of the POM file for this bundle project would look like this:</p> |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 62 | |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 63 | <div class="preformatted"><div class="preformattedContent"> |
| 64 | <pre>... |
| 65 | <plugins> |
| 66 | <plugin> |
| 67 | <groupId>org.apache.felix</groupId> |
| 68 | <artifactId>maven-bundle-plugin</artifactId> |
| 69 | <extensions>true</extensions> |
| 70 | <configuration> |
| 71 | <instructions> |
| 72 | <Export-Package>org.foo.myproject.api</Export-Package> |
| 73 | <Private-Package>org.foo.myproject.*</Private-Package> |
| 74 | <Bundle-Activator>org.foo.myproject.impl1.Activator</Bundle-Activator> |
| 75 | </instructions> |
| 76 | </configuration> |
| 77 | </plugin> |
| 78 | </plugins> |
| 79 | ... |
| 80 | </pre> |
| 81 | </div></div> |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 82 | |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 83 | <p>The <tt><Export-Package></tt> and <tt><Private-Package></tt> instructions tell the plugin about the contents of the resulting bundle JAR file. The <tt><Export-Package></tt> instruction tells the plugin which of the available packages to copy into the bundle <b>and</b> export, while the <tt><Private-Package></tt> instruction indicates which of the available packages to copy into the bundle <b>but not</b> |
| 84 | export. If the two sets overlap, as they do in the case, then the |
| 85 | export takes precedence. Since we did not specify any values for any |
| 86 | other bundle manifest headers, they will assume default values which |
| 87 | are 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> |
| 88 | bundle manifest header based on the contents of the bundle, which means |
| 89 | that you generally do not ever need to explicitly specify it yourself. |
| 90 | That'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 |
| 95 | its behavior. For this Maven plugin, these instructions are issued in |
| 96 | the 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 McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 97 | |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 98 | <ol> |
| 99 | <li><em>Manifest headers</em> - Any instruction that starts with |
| 100 | a capital letter will appear in the resulting bundle's manifest file; |
| 101 | the value for the header will either be copied, augmented, or generated |
| 102 | by 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 |
| 106 | directive that informs BND to perform some special processing and is |
| 107 | not 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 Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 117 | <h3><a name="MavenBundlePlugin(BND)-{{<ExportPackage>}}"></a><tt><Export-Package></tt></h3> |
| 118 | |
| 119 | <p>The <tt><Export-Package></tt> instruction is a list of |
| 120 | packages for the bundle to export. These packages are copied into the |
| 121 | resulting bundle JAR file from the available classes (i.e., project |
| 122 | classes, dependencies, and class path); thus, it is possible to include |
| 123 | classes into your bundle that are not associated with source files in |
| 124 | your project. <tt><Export-Package></tt> can be specified with |
| 125 | package patterns using the '*' wildcard. Also, it is possible to |
| 126 | exclude packages using negation by starting the package pattern with |
| 127 | '!'. Thus, non-negated patterns indicate which of the available |
| 128 | packages to include in the bundle, whereas negated patterns indicate |
| 129 | which 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 |
| 134 | directives and attributes, which will be copied appropriately into the |
| 135 | generated Export-Package manifest header. Besides explicitly listing |
| 136 | package version attributes, BND will also determine package versions by |
| 137 | examining the source JAR file or from <tt>packageinfo</tt> files in the package directory.</p> |
| 138 | |
| 139 | <h3><a name="MavenBundlePlugin(BND)-{{<PrivatePackage>}}"></a><tt><Private-Package></tt></h3> |
| 140 | |
| 141 | <p>The <tt><Private-Package></tt> instruction is similar in every way to the <tt><Export-Package></tt> instruction, except for the fact that these packages will <b>not</b> |
| 142 | be exported by the bundle. If a package is selected by both the export |
| 143 | and private package headers, then the export takes precedence.</p> |
| 144 | |
| 145 | <h3><a name="MavenBundlePlugin(BND)-{{<IncludeResource>}}"></a><tt><Include-Resource></tt></h3> |
| 146 | |
| 147 | <p>The <tt><Include-Resource></tt> instruction is a list of |
| 148 | arbitrary resources that should be copied into the bundle JAR file. The |
| 149 | specified resources are declared as clauses that can have the following |
| 150 | forms:</p> |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 151 | |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 152 | <div class="preformatted"><div class="preformattedContent"> |
| 153 | <pre>clause ::= assignment | inline | simple |
| 154 | assignment ::= PATH '=' PATH |
| 155 | simple ::= PATH |
| 156 | inline ::= '@' PATH |
| 157 | </pre> |
| 158 | </div></div> |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 159 | |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 160 | <p>For the <tt><Include-Resource></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> |
| 161 | form will place the resource in the bundle JAR with only the file name, |
| 162 | i.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> |
| 163 | points to a directory, the entire directory hierarchy is copied into |
| 164 | the resulting bundle JAR file relative to the specified directory. If a |
| 165 | specific resource must be placed into a subdirectory of the bundle jar, |
| 166 | then use the <tt>assignment</tt> form, where the first path is the the |
| 167 | destination path (including file name if the resource is a file) and |
| 168 | the 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 |
| 171 | variable substitution will be performed on the resource, where |
| 172 | variables in the resources are denoted with "${ ... }" syntax.</p> |
| 173 | |
| 174 | <h3><a name="MavenBundlePlugin(BND)-{{<ImportPackage>}}"></a><tt><Import-Package></tt></h3> |
| 175 | |
| 176 | <p>The <tt><Import-Package></tt> instruction is a list of |
| 177 | packages that are required by the bundle's contained packages. The |
| 178 | default for this header is "*", resulting in importing all referred |
| 179 | packages. This header rarely has to be explicitly specified. However, |
| 180 | in certain cases when there is an unwanted import, such an import can |
| 181 | be removed by using a negation package pattern. The package patterns |
| 182 | work in the same way as for <tt><Export-Package></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 |
| 189 | part of the Maven integration, the plugin tries to set reasonable |
| 190 | defaults for various instructions. For example:</p> |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 191 | |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 192 | <ul> |
| 193 | <li><tt><Bundle-SymbolicName></tt> is assumed to be "<tt>${groupId}.${artifactId</tt>}".</li> |
| 194 | <li><tt><Export-Package></tt> is assumed to be "<tt>${groupId}.${artifactId}.*</tt>", unless <tt><Private-Package></tt> is specified, then <tt><Export-Package></tt> is assumed to be empty.</li> |
| 195 | <li><tt><Private-Package></tt> is assumed to be empty by default.</li> |
| 196 | <li><tt><Import-Package></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><Include-Resource></tt> is assumed to be "<tt>src/main/resources/</tt>", |
| 198 | which will copy the specified project directory hierarchy into the |
| 199 | resulting bundle JAR file, mirroring standard Maven behavior.</li> |
| 200 | <li><tt><Bundle-Version></tt> is assumed to be "<tt>${pom.version</tt>}" with '-' character separator of the qualifier replaced with a '.' character.</li> |
| 201 | <li><tt><Bundle-Name></tt> is assumed to be "<tt>${pom.name</tt>}".</li> |
| 202 | <li><tt><Bundle-Description></tt> is assumed to be "<tt>${pom.description</tt>}".</li> |
| 203 | <li><tt><Bundle-License></tt> is assumed to be "<tt>${pom.licenses</tt>}".</li> |
| 204 | <li><tt><Bundle-Vendor></tt> is assumed to be "<tt>${pom.organization.name</tt>}".</li> |
| 205 | <li><tt><Bundle-DocURL></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> |
| 210 | to be '2'. Additionally, it generates imports for every export to |
| 211 | ensure package substitutability, which is very important when working |
| 212 | with collaborating services. It is possible to override any of these |
| 213 | values (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"HowTo""></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 |
| 222 | installing the latest version of the Maven2 runtime. The latest Maven2 |
| 223 | release and instuctions for getting started with Maven2 can be found at |
| 224 | the <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 |
| 229 | some appropriate plugin configuration to your bundle project's POM. |
| 230 | Below is an example of a simple OSGi bundle POM for Maven2:</p> |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 231 | |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 232 | <div class="preformatted"><div class="preformattedContent"> |
| 233 | <pre><project> |
| 234 | <modelVersion>4.0.0</modelVersion> |
| 235 | <groupId>my-osgi-bundles</groupId> |
| 236 | <artifactId>examplebundle</artifactId> |
| 237 | <packaging>bundle</packaging> <!-- (1) --> |
| 238 | <version>1.0</version> |
| 239 | <name>Example Bundle</name> |
| 240 | <dependencies> |
| 241 | <dependency> |
| 242 | <groupId>org.apache.felix</groupId> |
| 243 | <artifactId>org.osgi.core</artifactId> |
| 244 | <version>0.8.0-incubator</version> |
| 245 | </dependency> |
| 246 | </dependencies> |
| 247 | <build> |
| 248 | <plugins> |
| 249 | <plugin> <!-- (2) START --> |
| 250 | <groupId>org.apache.felix</groupId> |
| 251 | <artifactId>maven-bundle-plugin</artifactId> |
| 252 | <extensions>true</extensions> |
| 253 | <configuration> |
| 254 | <instructions> |
| 255 | <Export-Package>com.my.company.api</Export-Package> |
| 256 | <Private-Package>com.my.company.*</Private-Package> |
| 257 | <Bundle-Activator>com.my.company.Activator</Bundle-Activator> |
| 258 | </instructions> |
| 259 | </configuration> |
| 260 | </plugin> <!-- (2) END --> |
| 261 | </plugins> |
| 262 | </build> |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 263 | </project> |
| 264 | </pre> |
| 265 | </div></div> |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 266 | |
| 267 | <p>There are two main things to note: (1) the <tt><packaging></tt> |
| 268 | specifier must be "bundle" and (2) the plugin and configuration must be |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 269 | specified (the configuration section is where you will issue |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 270 | instructions to the plugin).</p> |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 271 | |
| 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 |
| 275 | implementation. The Log Service project is comprised of a single |
| 276 | package: <tt>org.apache.felix.log.impl</tt>. It has a dependency on |
| 277 | the core OSGi interfaces as well as a dependency on the compendium OSGi |
| 278 | interfaces for the specific log service interfaces. The following is |
| 279 | its POM file:</p> |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 280 | |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 281 | <div class="preformatted"><div class="preformattedContent"> |
| 282 | <pre><project> |
| 283 | <modelVersion>4.0.0</modelVersion> |
| 284 | <groupId>org.apache.felix</groupId> |
| 285 | <artifactId>org.apache.felix.log</artifactId> |
| 286 | <packaging>bundle</packaging> |
| 287 | <name>Apache Felix Log Service</name> |
| 288 | <version>0.8.0-SNAPSHOT</version> |
| 289 | <description> |
| 290 | This bundle provides an implementation of the OSGi R4 Log service. |
| 291 | </description> |
| 292 | <dependencies> |
| 293 | <dependency> |
| 294 | <groupId>${pom.groupId}</groupId> |
| 295 | <artifactId>org.osgi.core</artifactId> |
| 296 | <version>0.8.0-incubator</version> |
| 297 | </dependency> |
| 298 | <dependency> |
| 299 | <groupId>${pom.groupId}</groupId> |
| 300 | <artifactId>org.osgi.compendium</artifactId> |
| 301 | <version>0.9.0-incubator-SNAPSHOT</version> |
| 302 | </dependency> |
| 303 | </dependencies> |
| 304 | <build> |
| 305 | <plugins> |
| 306 | <plugin> |
| 307 | <groupId>org.apache.felix</groupId> |
| 308 | <artifactId>maven-bundle-plugin</artifactId> |
| 309 | <extensions>true</extensions> |
| 310 | <configuration> |
| 311 | <instructions> |
| 312 | <Export-Package>org.osgi.service.log</Export-Package> |
| 313 | <Private-Package>org.apache.felix.log.impl</Private-Package> |
| 314 | <Bundle-SymbolicName>${pom.artifactId}</Bundle-SymbolicName> |
| 315 | <Bundle-Activator>${pom.artifactId}.impl.Activator</Bundle-Activator> |
| 316 | <Export-Service>org.osgi.service.log.LogService,org.osgi.service.log.LogReaderService</Export-Service> |
| 317 | </instructions> |
| 318 | </configuration> |
| 319 | </plugin> |
| 320 | </plugins> |
| 321 | </build> |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 322 | </project> |
| 323 | </pre> |
| 324 | </div></div> |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 325 | |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 326 | <p>Notice that the <tt><Export-Package></tt> instruction |
| 327 | specifies that the bundle exports the Log Service package, even though |
| 328 | this package is not contained in the bundle project. By declaring this, |
| 329 | the plugin will copy the Log Service package into the resulting bundle |
| 330 | JAR file. This is useful in this case because now the bundle can |
| 331 | resolve without having to download the entire compendium bundle. The |
| 332 | resulting manifest for the Log Service bundle looks like this (notice |
| 333 | how the imports/exports automatically have version information |
| 334 | associated with them, which was obtained from packageinfo files in the |
| 335 | source packages):</p> |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 336 | |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 337 | <div class="preformatted"><div class="preformattedContent"> |
| 338 | <pre>Manifest-Version: 1 |
| 339 | Bundle-License: http://www.apache.org/licenses/LICENSE-2.0.txt |
| 340 | Bundle-Activator: org.apache.felix.log.impl.Activator |
| 341 | Import-Package: org.osgi.framework;version=1.3, org.osgi.service.log;v |
| 342 | ersion=1.3 |
| 343 | Include-Resource: src/main/resources |
| 344 | Export-Package: org.osgi.service.log;uses:=org.osgi.framework;version= |
| 345 | 1.3 |
| 346 | Bundle-Version: 0.8.0.SNAPSHOT |
| 347 | Bundle-Name: Apache Felix Log Service |
| 348 | Bundle-Description: This bundle provides an implementation of the OSGi |
| 349 | R4 Log service. |
| 350 | Private-Package: org.apache.felix.log.impl |
| 351 | Bundle-ManifestVersion: 2 |
| 352 | Export-Service: org.osgi.service.log.LogService,org.osgi.service.log.L |
| 353 | ogReaderService |
| 354 | Bundle-SymbolicName: org.apache.felix.log |
| 355 | </pre> |
| 356 | </div></div> |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 357 | |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 358 | <p>The resulting bundle JAR file has the following content (notice how |
| 359 | the LICENSE and NOTICE files were automatically copied from the <tt>src/main/resources/</tt> directory of the project):</p> |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 360 | |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 361 | <div class="preformatted"><div class="preformattedContent"> |
| 362 | <pre>META-INF/MANIFEST.MF |
| 363 | LICENSE |
| 364 | META-INF/ |
| 365 | META-INF/maven/ |
| 366 | META-INF/maven/org.apache.felix/ |
| 367 | META-INF/maven/org.apache.felix/org.apache.felix.log/ |
| 368 | META-INF/maven/org.apache.felix/org.apache.felix.log/pom.properties |
| 369 | META-INF/maven/org.apache.felix/org.apache.felix.log/pom.xml |
| 370 | NOTICE |
| 371 | org/ |
| 372 | org/apache/ |
| 373 | org/apache/felix/ |
| 374 | org/apache/felix/log/ |
| 375 | org/apache/felix/log/impl/ |
| 376 | org/apache/felix/log/impl/Activator.class |
| 377 | org/apache/felix/log/impl/Log.class |
| 378 | org/apache/felix/log/impl/LogEntryImpl.class |
| 379 | org/apache/felix/log/impl/LogException.class |
| 380 | org/apache/felix/log/impl/LogListenerThread.class |
| 381 | org/apache/felix/log/impl/LogNode.class |
| 382 | org/apache/felix/log/impl/LogNodeEnumeration.class |
| 383 | org/apache/felix/log/impl/LogReaderServiceFactory.class |
| 384 | org/apache/felix/log/impl/LogReaderServiceImpl.class |
| 385 | org/apache/felix/log/impl/LogServiceFactory.class |
| 386 | org/apache/felix/log/impl/LogServiceImpl.class |
| 387 | org/osgi/ |
| 388 | org/osgi/service/ |
| 389 | org/osgi/service/log/ |
| 390 | org/osgi/service/log/LogEntry.class |
| 391 | org/osgi/service/log/LogListener.class |
| 392 | org/osgi/service/log/LogReaderService.class |
| 393 | org/osgi/service/log/LogService.class |
| 394 | org/osgi/service/log/package.html |
| 395 | org/osgi/service/log/packageinfo |
| 396 | </pre> |
| 397 | </div></div> |
| 398 | |
| 399 | <h2><a name="MavenBundlePlugin(BND)-BuildingthePlugin"></a>Building the Plugin</h2> |
| 400 | |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 401 | <p>The plugin is hosted at the Apache Felix project. The following |
| 402 | steps describe how to build and install the plugin into your local |
| 403 | Maven2 repository.</p> |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 404 | |
| 405 | <p>Using the SVN client of your choice, checkout the maven-bundle-plugin project.</p> |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 406 | |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 407 | <div class="preformatted"><div class="preformattedContent"> |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 408 | <pre>$ svn co http://svn.apache.org/repos/asf/felix/trunk/bundleplugin |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 409 | </pre> |
| 410 | </div></div> |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 411 | |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 412 | <p>Using Maven2, build and install the maven-bundle-plugin by issuing |
| 413 | the following Maven2 command in the project directory that was created |
| 414 | as a result of the previous step.</p> |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 415 | |
Karl Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 416 | <div class="preformatted"><div class="preformattedContent"> |
| 417 | <pre>$ mvn install |
| 418 | </pre> |
| 419 | </div></div> |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 420 | |
| 421 | <h1><a name="MavenBundlePlugin(BND)-Goals"></a>Goals</h1> |
| 422 | |
| 423 | <p>The maven-bundle-plugin also provides additional functionality via |
| 424 | some Maven goals. Command-line execution of a goal is performed as |
| 425 | follows:</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> |
| 436 | configuration 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> |
| 444 | configuration 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> |
| 450 | configuration 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> |
| 456 | configuration 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 |
| 466 | tool, 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 <packaging> 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><Embed-Dependency></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"><Embed-Dependency></span>dependencies<span class="code-tag"></Embed-Dependency></span></pre> |
| 476 | </div></div> |
| 477 | |
| 478 | <p>where:</p> |
| 479 | |
| 480 | <div class="preformatted"><div class="preformattedContent"> |
| 481 | <pre>dependencies ::= clause ( ',' clause ) * |
| 482 | clause ::= MATCH ( ';' attr '=' MATCH | ';inline=true' ) |
| 483 | attr ::= 'groupId' | 'artifactId' | 'version' | 'scope' | 'type' | 'classifier' |
| 484 | MATCH ::= <globbed regular expressions> |
| 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"><Embed-Dependency></span>*;scope=compile|runtime<span class="code-tag"></Embed-Dependency></span> |
| 492 | |
| 493 | <span class="code-tag"><Embed-Dependency></span>junit;scope=test<span class="code-tag"></Embed-Dependency></span> |
| 494 | |
| 495 | <span class="code-tag"><Embed-Dependency></span>aopalliance;scope=!test;inline=true<span class="code-tag"></Embed-Dependency></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><Embed-StripVersion>true</Embed-StripVersion></tt> - removes the version from the file (ie. <em>artifactId.jar</em>)</li> |
| 502 | <li><tt><Embed-StripGroup>false</Embed-StripGroup></tt> - adds the groupId as a subdirectory (ie. <em>groupId/artifactId-version.jar</em>)</li> |
| 503 | <li><tt><Embed-Directory>directory</Embed-Directory></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 |
| 508 | changed to include the complete set of transitive dependencies with the |
| 509 | following option:</p> |
| 510 | |
| 511 | <div class="code"><div class="codeContent"> |
| 512 | <pre class="code-xml"><span class="code-tag"><Embed-Transitive></span>true<span class="code-tag"></Embed-Transitive></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"><Embed-Dependency></span>*;scope=compile|runtime;inline=true<span class="code-tag"></Embed-Dependency></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 |
| 525 | repository.xml file during the install phase, using a default location |
| 526 | of:</p> |
| 527 | |
| 528 | <div class="code"><div class="codeContent"> |
| 529 | <pre class="code-java"><LOCAL-MAVEN-REPOSITORY>/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=<PATH_TO_OBR></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"><groupId></span>org.apache.felix<span class="code-tag"></groupId></span> |
| 542 | <span class="code-tag"><artifactId></span>maven-bundle-plugin<span class="code-tag"></artifactId></span> |
| 543 | <span class="code-tag"><extensions></span>true<span class="code-tag"></extensions></span> |
| 544 | <span class="code-tag"><configuration></span> |
| 545 | <span class="code-tag"><obrRepository></span>PATH_TO_OBR<span class="code-tag"></obrRepository></span> |
| 546 | <span class="code-tag"><instructions></span> |
| 547 | <span class="code-tag"><span class="code-comment"><!-- bnd instructions --></span></span> |
| 548 | <span class="code-tag"></instructions></span> |
| 549 | <span class="code-tag"></configuration></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"><groupId></span>org.apache.felix<span class="code-tag"></groupId></span> |
| 556 | <span class="code-tag"><artifactId></span>maven-bundle-plugin<span class="code-tag"></artifactId></span> |
| 557 | <span class="code-tag"><extensions></span>true<span class="code-tag"></extensions></span> |
| 558 | <span class="code-tag"><configuration></span> |
| 559 | <span class="code-tag"><obrRepository></span>NONE<span class="code-tag"></obrRepository></span> |
| 560 | <span class="code-tag"><instructions></span> |
| 561 | <span class="code-tag"><span class="code-comment"><!-- bnd instructions --></span></span> |
| 562 | <span class="code-tag"></instructions></span> |
| 563 | <span class="code-tag"></configuration></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 |
| 570 | bundle manifest where Eclipse/PDE expects it, and use the Maven |
| 571 | Dependency Plugin to arrange for any embedded dependencies to appear in |
| 572 | a local directory that matches the Bundle-ClassPath entries. Here is an |
| 573 | example POM that does this:</p> |
| 574 | |
| 575 | <div class="preformatted"><div class="preformattedContent"> |
| 576 | <pre><project> |
| 577 | |
| 578 | <properties> |
| 579 | <bundle.symbolicName>org.example</bundle.symbolicName> |
| 580 | <bundle.namespace>org.example</bundle.namespace> |
| 581 | </properties> |
| 582 | |
| 583 | <modelVersion>4.0.0</modelVersion> |
| 584 | <groupId>examples</groupId> |
| 585 | <artifactId>org.example</artifactId> |
| 586 | <version>1.0-SNAPSHOT</version> |
| 587 | |
| 588 | <name>${bundle.symbolicName} [${bundle.namespace}]</name> |
| 589 | |
| 590 | <packaging>bundle</packaging> |
| 591 | |
| 592 | <build> |
| 593 | <plugins> |
| 594 | <plugin> |
| 595 | <groupId>org.apache.felix</groupId> |
| 596 | <artifactId>maven-bundle-plugin</artifactId> |
| 597 | <version>1.1.0-SNAPSHOT</version> |
| 598 | <extensions>true</extensions> |
| 599 | <!-- |
| 600 | the following instructions build a simple set of public/private classes into an OSGi bundle |
| 601 | --> |
| 602 | <configuration> |
| 603 | <manifestLocation>META-INF</manifestLocation> |
| 604 | <instructions> |
| 605 | <Bundle-SymbolicName>${bundle.symbolicName}</Bundle-SymbolicName> |
| 606 | <Bundle-Version>${pom.version}</Bundle-Version> |
| 607 | <!-- |
| 608 | assume public classes are in the top package, and private classes are under ".internal" |
| 609 | --> |
| 610 | <Export-Package>${bundle.namespace};version="${pom.version}"</Export-Package> |
| 611 | <Private-Package>${bundle.namespace}.internal</Private-Package> |
| 612 | <Bundle-Activator>${bundle.namespace}.internal.Activator</Bundle-Activator> |
| 613 | <!-- |
| 614 | embed compile/runtime dependencies using path that matches the copied dependency folder |
| 615 | --> |
| 616 | <Embed-Dependency>*;scope=compile|runtime;inline=false</Embed-Dependency> |
| 617 | <Embed-Directory>target/dependency</Embed-Directory> |
| 618 | <Embed-StripGroup>true</Embed-StripGroup> |
| 619 | </instructions> |
| 620 | </configuration> |
| 621 | </plugin> |
| 622 | <plugin> |
| 623 | <artifactId>maven-dependency-plugin</artifactId> |
| 624 | <executions> |
| 625 | <execution> |
| 626 | <id>copy-dependencies</id> |
| 627 | <phase>package</phase> |
| 628 | <goals> |
| 629 | <goal>copy-dependencies</goal> |
| 630 | </goals> |
| 631 | </execution> |
| 632 | </executions> |
| 633 | </plugin> |
| 634 | </plugins> |
| 635 | </build> |
| 636 | |
| 637 | <dependencies> |
| 638 | <dependency> |
| 639 | <groupId>org.osgi</groupId> |
| 640 | <artifactId>osgi_R4_core</artifactId> |
| 641 | <version>1.0</version> |
| 642 | <scope>provided</scope> |
| 643 | <optional>true</optional> |
| 644 | </dependency> |
| 645 | <dependency> |
| 646 | <groupId>org.osgi</groupId> |
| 647 | <artifactId>osgi_R4_compendium</artifactId> |
| 648 | <version>1.0</version> |
| 649 | <scope>provided</scope> |
| 650 | <optional>true</optional> |
| 651 | </dependency> |
| 652 | <dependency> |
| 653 | <groupId>junit</groupId> |
| 654 | <artifactId>junit</artifactId> |
| 655 | <version>3.8.1</version> |
| 656 | <scope>compile</scope> |
| 657 | <optional>true</optional> |
| 658 | </dependency> |
| 659 | </dependencies> |
| 660 | |
| 661 | </project> |
| 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 |
| 682 | handle any embedded entries. The pax:eclipse goal extends |
| 683 | eclipse: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>, |
| 688 | for example when you embed the classes from another jar. This can |
| 689 | sometimes cause unforeseen problems in Maven, as it will use the output |
| 690 | directory (<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 |
| 693 | contents of the bundle to the output directory after the packaging |
| 694 | step, so the additional classes will be found where Maven expects them. |
| 695 | Thankfully 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"><groupId>org.apache.felix</groupId> |
| 699 | <artifactId>maven-bundle-plugin</artifactId> |
| 700 | <extensions><span class="code-keyword">true</span></extensions> |
| 701 | <configuration> |
| 702 | <unpackBundle><span class="code-keyword">true</span></unpackBundle> |
| 703 | <instructions> |
| 704 | <!-- bnd instructions --> |
| 705 | </instructions> |
| 706 | </configuration></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"><_include>src/main/resources/META-INF/MANIFEST.MF</_include> |
| 715 | <Export-Package>org.example.*</Export-Package></pre> |
| 716 | </div></div> |
| 717 | |
| 718 | <p>Bnd will use it when calculating the bundle contents, and will also |
| 719 | copy across all manifest attributes starting with a capital letter.<br> |
| 720 | As shown in the above example, you could use this to include a non-OSGi |
| 721 | manifest 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 Pauls | f87ac14 | 2007-07-06 22:36:17 +0000 | [diff] [blame] | 726 | </div> |
| 727 | |
Stuart McCulloch | 93de649 | 2007-12-16 15:59:05 +0000 | [diff] [blame^] | 728 | </body></html> |