felix-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From conflue...@apache.org
Subject [CONF] Apache Felix > Apache Felix Bundle Plugin FAQ
Date Sat, 03 Dec 2011 00:23:00 GMT
<html>
<head>
    <base href="https://cwiki.apache.org/confluence">
            <link rel="stylesheet" href="/confluence/s/2042/9/1/_/styles/combined.css?spaceKey=FELIX&amp;forWysiwyg=true"
type="text/css">
    </head>
<body style="background: white;" bgcolor="white" class="email-body">
<div id="pageContent">
<div id="notificationFormat">
<div class="wiki-content">
<div class="email">
    <h2><a href="https://cwiki.apache.org/confluence/display/FELIX/Apache+Felix+Bundle+Plugin+FAQ">Apache
Felix Bundle Plugin FAQ</a></h2>
    <h4>Page <b>edited</b> by             <a href="https://cwiki.apache.org/confluence/display/~mcculls">Stuart
McCulloch</a>
    </h4>
        <br/>
                         <h4>Changes (1)</h4>
                                 
    
<div id="page-diffs">
                    <table class="diff" cellpadding="0" cellspacing="0">
    
            <tr><td class="diff-snipped" >...<br></td></tr>
            <tr><td class="diff-unchanged" > <br>Put this in either the
JAR or bundle plugin configuration. <br></td></tr>
            <tr><td class="diff-added-lines" style="background-color: #dfd;">
<br>h2. Why do some generated resources (such as Declarative Services XML files) appear
in the final jar, but others don&#39;t? <br> <br>When you use the Service-Component
instruction to specify Declarative Services the BND tool scans the project classpath for components
and automatically adds its generated XML to the final bundle, therefore Include-Resource is
not necessary. But if you generate files under OSGI-INF using another mechanism then they
won&#39;t end up in the bundle unless you add that directory using Include-Resource (this
goes back to the core design decision that BND pulls classes and resources into the bundle,
rather than just taking everything under target/classes). We try to provide reasonable defaults
on the Maven side in the bundleplugin so local classes and resources will end up in the bundle
without additional configuration, but we do this by looking at the effective pom and src/
folder rather than the generated target/classes content. <br></td></tr>
    
            </table>
    </div>                            <h4>Full Content</h4>
                    <div class="notificationGreySide">
        <h1><a name="ApacheFelixBundlePluginFAQ-ApacheFelixBundlePluginFrequentlyAskedQuestions"></a>Apache
Felix Bundle Plugin Frequently Asked Questions</h1>

<style type='text/css'>/*<![CDATA[*/
div.rbtoc1322871748328 {margin-left: 1.5em;padding: 0px;}
div.rbtoc1322871748328 ul {list-style: disc;margin-left: 0px;}
div.rbtoc1322871748328 li {margin-left: 0px;padding-left: 0px;}

/*]]>*/</style><div class='rbtoc1322871748328'>
<ul>
    <li><a href='#ApacheFelixBundlePluginFAQ-ApacheFelixBundlePluginFrequentlyAskedQuestions'>Apache
Felix Bundle Plugin Frequently Asked Questions</a></li>
<ul>
    <li><a href='#ApacheFelixBundlePluginFAQ-WhenIembedadependencywhydoIseeduplicatedcontent%3F'>When
I embed a dependency why do I see duplicated content?</a></li>
    <li><a href='#ApacheFelixBundlePluginFAQ-WhydoIseemoreclassesinmybundleafterupgradingtomavenbundleplugin2.0.0%3F'>Why
do I see more classes in my bundle after upgrading to maven-bundle-plugin 2.0.0?</a></li>
    <li><a href='#ApacheFelixBundlePluginFAQ-WhydoIgetanexception%28Unsupportedmajor.minorversion49.0%29whenIbuildwitha1.4orearlierJDK%3F'>Why
do I get an exception (Unsupported major.minor version 49.0) when I build with a 1.4 or earlier
JDK?</a></li>
    <li><a href='#ApacheFelixBundlePluginFAQ-WhenIbuildabundle%2Csomeclassesarebuiltin%22target%2Fclasses%22butthey%27renotincludedinthefinaljar.'>When
I build a bundle, some classes are built in "target/classes" but they're not included in the
final jar.</a></li>
    <li><a href='#ApacheFelixBundlePluginFAQ-HowdoIremovethegeneratedMaveninformationfromtheresultingbundleJARfile%3F'>How
do I remove the generated Maven information from the resulting bundle JAR file?</a></li>
    <li><a href='#ApacheFelixBundlePluginFAQ-Whydosomegeneratedresources%28suchasDeclarativeServicesXMLfiles%29appearinthefinaljar%2Cbutothersdon%27t%3F'>Why
do some generated resources (such as Declarative Services XML files) appear in the final jar,
but others don't?</a></li>
</ul>
</ul></div>

<h2><a name="ApacheFelixBundlePluginFAQ-WhenIembedadependencywhydoIseeduplicatedcontent%3F"></a>When
I embed a dependency why do I see duplicated content?</h2>

<p>Having two copies of classes, both unpacked and embedded as jars, is a sign that
your Embed-Dependency and Export-Package instructions are overlapping. Export-Package tells
BND to pull in classes found in the named packages from the build classpath and add them to
the bundle, Embed-Dependency tells BND to embed (or inline if enabled) whole artifacts in
the bundle.</p>

<p>so say I have:</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>Export-Package: org.objectweb.asm.*
</pre>
</div></div>

<p>and I have the asm artifact as a compile scope dependency, then I would see the org.objectweb.asm
classes unpacked in the bundle, ie. pulled in by BND.</p>

<p>say I now decide to embed asm as a jar, for example with:</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>Embed-Dependency: *;scope=compile|runtime
</pre>
</div></div>

<p>I would now see the asm artifact embedded inside bundle - but I would also see the
unpacked classes from before, because I'm still asking BND to pull them in (you will probably
also see split package warnings during the build).</p>

<p>ok - so how do I embed asm as a jar, but mark its packages as exported without pulling
in the unpacked classes... well, there is another export instruction added for exactly this
reason:</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>-exportcontents: org.objectweb.asm.*
</pre>
</div></div>

<p>(this is &lt;_exportcontents&gt; in the POM because a tag can't start with
'-')</p>

<p>this instruction is merged with Export-Package, after BND has decided on the content
of the bundle - that is, it works just like Export-Package except that it won't alter the
content of the bundle.</p>

<p>So by removing org.objectweb.asm.* from Export-Package and using the -exportcontents
instruction instead along with Embed-Dependency, I can now embed the asm artifact in my bundle
and export its packages:</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>Embed-Dependency: *;scope=compile|runtime
-exportcontents: org.objectweb.asm.*
</pre>
</div></div>

<h2><a name="ApacheFelixBundlePluginFAQ-WhydoIseemoreclassesinmybundleafterupgradingtomavenbundleplugin2.0.0%3F"></a>Why
do I see more classes in my bundle after upgrading to maven-bundle-plugin 2.0.0?</h2>

<p>Before 2.0.0 the maven-bundle-plugin only passed local classes and compile scope
dependencies to bnd. This was because the main BundlePlugin mojo used "@requiresDependencyResolution
runtime" which asks Maven to only resolve dependencies of compile or runtime scope (the maven-bundle-plugin
also explicitly filtered runtime scope dependencies from the classpath passed to bnd). Because
bnd only had a fraction of the original classpath used to compile the bundle classes it meant
that imported packages weren't augmented with additional information (such as versions and
attributes) available from the complete classpath.</p>

<p>In 2.0.0 a conscious decision was made to pass the complete classpath to bnd so it
would have the complete set of information used during compilation. To do this the @requiresDependencyResolution
setting was changed to "test" so all dependencies will now be resolved. Furthermore only test
scope artifacts are now filtered from the final classpath passed to bnd.</p>

<p>For most users passing more of the original compilation classpath to bnd simply means
you get more accurate and consistent results. However, if you happened to rely on the old
behaviour (perhaps by setting Private-Package: * to pull in all local and compile scope classes)
then you will see more classes added to your bundle as the wildcard matches against additional
content in the classpath.</p>

<p>There are two solutions when this happens:</p>

<ul>
	<li>Change your Private-Package / Export-Package instructions to more accurately describe
what you want in your bundle</li>
	<li>Add the following setting to remove provided and runtime scope dependencies from
the classpath passed to bnd:
<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>&lt;plugin&gt;
  &lt;groupId&gt;org.apache.felix&lt;/groupId&gt;
  &lt;artifactId&gt;maven-bundle-plugin&lt;/artifactId&gt;
  &lt;configuration&gt;
    &lt;excludeDependencies&gt;*;scope=provided|runtime&lt;/excludeDependencies&gt;
  &lt;/configuration&gt;
&lt;/plugin&gt;
</pre>
</div></div></li>
</ul>


<p>This second option effectively switches the maven-bundle-plugin back to the old 1.X
behaviour.</p>

<p>Please also note that since 2.0.0 the maven-bundle-plugin also sets default Export-Package
and Private-Package instructions based on your local source files, so you might well find
that simply removing any Private-Package and/or Export-Package instructions from your pom.xml
will actually produce the correct result.</p>

<h2><a name="ApacheFelixBundlePluginFAQ-WhydoIgetanexception%28Unsupportedmajor.minorversion49.0%29whenIbuildwitha1.4orearlierJDK%3F"></a>Why
do I get an exception (Unsupported major.minor version 49.0) when I build with a 1.4 or earlier
JDK?</h2>

<p>The latest maven-bundle-plugin (2.0.0) uses a new release of bnd which requires Java5.
This means you now have to build your bundle projects using a Java5 (or later) JDK. Note that
you can still compile classes for earlier releases of the JVM by setting the appropriate source
and target levels in your pom.xml:</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>&lt;plugin&gt;
  &lt;artifactId&gt;maven-compiler-plugin&lt;/artifactId&gt;
  &lt;configuration&gt;
    &lt;source&gt;1.4&lt;/source&gt;
    &lt;target&gt;1.4&lt;/target&gt;
  &lt;/configuration&gt;
&lt;/plugin&gt;
</pre>
</div></div>

<h2><a name="ApacheFelixBundlePluginFAQ-WhenIbuildabundle%2Csomeclassesarebuiltin%22target%2Fclasses%22butthey%27renotincludedinthefinaljar."></a>When
I build a bundle, some classes are built in "target/classes" but they're not included in the
final jar.</h2>

<p>The only classes that will appear in the bundle are the ones you ask it to include
using Export-Package, Private-Package, Include-Resource, and Embed-Dependency - so just because
a file exists under target/classes does NOT mean it will end up in the bundle. This is because
this is the way the underlying <a href="http://aqute.biz/Code/Bnd" class="external-link"
rel="nofollow">BND</a> tool works (it is primarily pull-based).</p>

<p>Now the bundleplugin will look at your Maven project and add appropriate BND instructions
to pull in resource files - and version 2.0.0 will also look at your source directory to set
reasonable defaults for Export-Package and Private-Package (unless you set these yourself).
So when using bundleplugin 2.0.0 I'd use the default Private-Package and Export-Package to
begin with - I would then move towards using an explicit list of packages in Export-Package
to add versioning, directives, etc.</p>

<p>The only time I would set Private-Package would be to have more control over what
ends up in the bundle - either to remove certain packages or perhaps pull in additional packages
not found by the source scanner. Also note that both Export-Package and Private-Package accept
wildcards such as "org.example.&#42;" which can reduce the number of entries in the list,
but you should be careful not to set either the export or private instruction to "&#42;"
as this would pull in the entire classpath... dependencies and all!</p>

<h2><a name="ApacheFelixBundlePluginFAQ-HowdoIremovethegeneratedMaveninformationfromtheresultingbundleJARfile%3F"></a>How
do I remove the generated Maven information from the resulting bundle JAR file?</h2>

<p>Use the following archive setting:</p>

<div class="preformatted panel" style="border-width: 1px;"><div class="preformattedContent
panelContent">
<pre>&lt;configuration&gt;
  &lt;archive&gt;
    &lt;addMavenDescriptor&gt;false&lt;/addMavenDescriptor&gt;
  &lt;/archive&gt;
&lt;/configuration&gt;
</pre>
</div></div>

<p>Put this in either the JAR or bundle plugin configuration.</p>

<h2><a name="ApacheFelixBundlePluginFAQ-Whydosomegeneratedresources%28suchasDeclarativeServicesXMLfiles%29appearinthefinaljar%2Cbutothersdon%27t%3F"></a>Why
do some generated resources (such as Declarative Services XML files) appear in the final jar,
but others don't?</h2>

<p>When you use the Service-Component instruction to specify Declarative Services the
BND tool scans the project classpath for components and automatically adds its generated XML
to the final bundle, therefore Include-Resource is not necessary. But if you generate files
under OSGI-INF using another mechanism then they won't end up in the bundle unless you add
that directory using Include-Resource (this goes back to the core design decision that BND
pulls classes and resources into the bundle, rather than just taking everything under target/classes).
We try to provide reasonable defaults on the Maven side in the bundleplugin so local classes
and resources will end up in the bundle without additional configuration, but we do this by
looking at the effective pom and src/ folder rather than the generated target/classes content.</p>
    </div>
        <div id="commentsSection" class="wiki-content pageSection">
        <div style="float: right;">
            <a href="https://cwiki.apache.org/confluence/users/viewnotifications.action"
class="grey">Change Notification Preferences</a>
        </div>
        <a href="https://cwiki.apache.org/confluence/display/FELIX/Apache+Felix+Bundle+Plugin+FAQ">View
Online</a>
        |
        <a href="https://cwiki.apache.org/confluence/pages/diffpagesbyversion.action?pageId=97491&revisedVersion=7&originalVersion=6">View
Changes</a>
                |
        <a href="https://cwiki.apache.org/confluence/display/FELIX/Apache+Felix+Bundle+Plugin+FAQ?showComments=true&amp;showCommentArea=true#addcomment">Add
Comment</a>
            </div>
</div>
</div>
</div>
</div>
</body>
</html>

Mime
View raw message