// 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

[CAUTION]
====
This plugin is deprecated and will be removed in the next major Gradle release. New builds should not use this plugin.

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.
====

The OSGi plugin provides a factory method to create an link:{javadocPath}/org/gradle/api/plugins/osgi/OsgiManifest.html[OsgiManifest] object. `OsgiManifest` extends link:{javadocPath}/org/gradle/api/java/archives/Manifest.html[Manifest]. To learn more about generic manifest handling, see <<building_java_projects.adoc#sec:jar_manifest,more about Java manifests>>. 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.

[[sec:osgi_usage]]
== Usage

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

.Using the OSGi plugin
====
include::sample[dir="osgi/groovy",files="build.gradle[tags=use-plugin]"]
include::sample[dir="osgi/kotlin",files="build.gradle.kts[tags=use-plugin]"]
====

[[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:

`osgiClasses` — link:{groovyDslPath}/org.gradle.api.tasks.Sync.html[Sync]::
_Depends on_: `classes`
+
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: link:{javadocPath}/org/gradle/api/plugins/osgi/OsgiPluginConvention.html[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
[%header%autowidth,compact]
|===
| Method | Return Type | Description

| osgiManifest()
| link:{javadocPath}/org/gradle/api/plugins/osgi/OsgiManifest.html[OsgiManifest]
| Returns an OsgiManifest object.

| osgiManifest(Closure cl)
| link:{javadocPath}/org/gradle/api/plugins/osgi/OsgiManifest.html[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.

.Configuration of OSGi MANIFEST.MF file
====
include::sample[dir="userguide/tutorial/osgi/groovy",files="build.gradle[tags=configure-jar]"]
include::sample[dir="userguide/tutorial/osgi/kotlin",files="build.gradle.kts[tags=configure-jar]"]
====

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://bnd.bndtools.org/[BND tool].
