<!--
  ~ Copyright 2009 the original author or authors.
  ~
  ~ Licensed under the Apache License, Version 2.0 (the "License");
  ~ you may not use this file except in compliance with the License.
  ~ You may obtain a copy of the License at
  ~
  ~      http://www.apache.org/licenses/LICENSE-2.0
  ~
  ~ Unless required by applicable law or agreed to in writing, software
  ~ distributed under the License is distributed on an "AS IS" BASIS,
  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  ~ See the License for the specific language governing permissions and
  ~ limitations under the License.
  -->
<chapter id='osgi_plugin' xmlns:xi="http://www.w3.org/2001/XInclude">
    <title>The OSGi Plugin</title>
    <para>The Gradle OSGi plugin enables the generation of an OSGi manifest. This OSGi manifest is automatically added
        to all the JAR files produced by the project.
        This plugin makes heavy use of Peter Kriens <ulink url='http://www.aqute.biz/Code/Bnd'>BND tool</ulink>.
    </para>

    <section>
        <title>Tasks</title>
        <para>TBD</para>
    </section>

    <section>
        <title>Project layout</title>
        <para>TBD</para>
    </section>

    <section>
        <title>Dependency management</title>
        <para>TBD</para>
    </section>

    <section>
        <title>Convention properties</title>

        <para>The OSGi plugin adds an <literal>osgi</literal> property to every <emphasis>jar</emphasis> task.
            This <literal>osgi</literal> property points to an instance of
            <apilink class="org.gradle.api.plugins.osgi.OsgiManifest"/>. Via the OsgiManifest object you can control the
            generation of the OSGi Manifest of the respective jar. The OSGi plugin assign default values to the
            OsgiManifest object.
        </para>
        <table>
            <title>OSGi properties</title>
            <thead>
                <tr>
                    <td>Task Property</td>
                    <td>Convention Property</td>
                </tr>
            </thead>
            <tr>
                <td>classesDir</td>
                <td>project.classesDir</td>
            </tr>
            <tr>
                <td>version</td>
                <td>project.version</td>
            </tr>
            <tr>
                <td>name</td>
                <td>project.archivesBaseName</td>
            </tr>
            <tr>
                <td>symbolicName</td>
                <td>transformation of the name and the group to produce a valid OSGi symbolic name</td>
            </tr>
            <tr>
                <td>classpath</td>
                <td>project.dependencies.resolve('runtime')</td>
            </tr>
        </table>

        <para>The classes in the classes dir are analyzed regarding there package dependencies and the packages they expose.
            Based on this the <emphasis>Import-Package</emphasis> and the <emphasis>Export-Package</emphasis> values of the
            OSGi Manifest are calculated. If the classpath contains jars with an OSGi bundle, the bundle
            information is used to specify version information for the <emphasis>Import-Package</emphasis>
            value. Beside the explicit properties of the <literal>OsgiManifest</literal> object you can add instructions.
        </para>
        <sample id="osgi" dir="userguide/tutorial/osgi" title="Configuration of OSGi MANIFEST.MF file">
            <sourcefile file="build.gradle" snippet="configure-jar"/>
        </sample>
        <para>The first argument of the instruction call is the key of the property. The other arguments form the value.
            They are joined by Gradle with the <literal>,</literal> separator. To learn more about the available
            instructions have a look at the <ulink url='http://www.aqute.biz/Code/Bnd'>BND tool</ulink>.</para>
    </section>
</chapter>
