// Copyright 2017 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.

[[osgi_plugin]]
== The OSGi Plugin

The OSGi plugin provides a factory method to create an api:org.gradle.api.plugins.osgi.OsgiManifest[] object. `OsgiManifest` extends api:org.gradle.api.java.archives.Manifest[]. To learn more about generic manifest handling, see <<sub:manifest>>. If the Java plugins is applied, the OSGi plugin replaces the manifest object of the default jar with an `OsgiManifest` object. The replaced manifest is merged into the new one.

[NOTE]
====
The OSGi plugin makes heavy use of the http://bnd.bndtools.org/[BND tool]. A separate https://github.com/bndtools/bnd/blob/master/biz.aQute.bnd.gradle/README.md[plugin implementation] is maintained by the BND authors that has more advanced features.
====


[[sec:osgi_usage]]
=== Usage

To use the OSGi plugin, include the following in your build script:

++++
<sample id="useOsgiPlugin" dir="osgi" title="Using the OSGi plugin">
            <sourcefile file="build.gradle" snippet="use-plugin"/>
        </sample>
++++


[[sec:osgi_implicitly_applied_plugins]]
=== Implicitly applied plugins

Applies the Java base plugin.

[[sec:osgi_tasks]]
=== Tasks

The OSGi plugin adds the following tasks to the project:

.OSGi plugin - tasks
[cols="a,a,a,a", options="header"]
|===
| Task name
| Depends on
| Type
| Description

| `osgiClasses`
| `classes`
| api:org.gradle.api.tasks.Sync[]
| Copies all classes from the main source set to a single directory that is processed by BND.
|===


[[sec:osgi_convention_object]]
=== Convention object

The OSGi plugin adds the following convention object: api:org.gradle.api.plugins.osgi.OsgiPluginConvention[] 


[[sec:osgi_convention_properties]]
==== Convention properties

The OSGi plugin does not add any convention properties to the project.

[[sec:osgi_convention_methods]]
==== Convention methods

The OSGi plugin adds the following methods. For more details, see the API documentation of the convention object.

.OSGi methods
[cols="a,a,a", options="header"]
|===
| Method
| Return Type
| Description

| osgiManifest()
| api:org.gradle.api.plugins.osgi.OsgiManifest[]
| Returns an OsgiManifest object.

| osgiManifest(Closure cl)
| api:org.gradle.api.plugins.osgi.OsgiManifest[]
| Returns an OsgiManifest object configured by the closure.
|===

The classes in the classes dir are analyzed regarding their package dependencies and the packages they expose. Based on this the _Import-Package_ and the _Export-Package_ 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 _Import-Package_ value. Beside the explicit properties of the `OsgiManifest` object you can add instructions.

++++
<sample id="osgi" dir="userguide/tutorial/osgi" title="Configuration of OSGi MANIFEST.MF file">
                <sourcefile file="build.gradle" snippet="configure-jar"/>
            </sample>
++++

The first argument of the instruction call is the key of the property. The other arguments form the value. To learn more about the available instructions have a look at the http://www.aqute.biz/Bnd/Bnd[BND tool].