From 9e302b2241b7a3cdb4c7171ff155ac22f5f92848 Mon Sep 17 00:00:00 2001 From: "Jan N. Klug" Date: Sun, 14 Jan 2024 18:10:46 +0100 Subject: [PATCH] Improve add-on dependency documentation Signed-off-by: Jan N. Klug --- developers/buildsystem.md | 42 +++++++++++++++------------------------ 1 file changed, 16 insertions(+), 26 deletions(-) diff --git a/developers/buildsystem.md b/developers/buildsystem.md index da168d3803..9b88e5b160 100644 --- a/developers/buildsystem.md +++ b/developers/buildsystem.md @@ -19,7 +19,7 @@ This section talks about some common buildsystem related topics and also some qu Generally all dependencies should be OSGi-bundles and available on Maven Central. -### External dependency +### Embedding dependency In most cases they should be referenced in the project POM with scope `compile`: @@ -35,47 +35,36 @@ In most cases they should be referenced in the project POM with scope `compile`: ``` These dependencies are embedded in the resulting bundle automatically. - -There are two exceptions: - -1. Dependencies to other openHAB bundles (e.g. `org.openhab.addons.bundles/org.openhab.binding.bluetooth/3.1.0-SNAPSHOT` or `org.openhab.addons.bundles/org.openhab.transform.map/3.1.0-SNAPSHOT`). -1. Bundles that are used by more than one binding (e.g. Netty-bundles like `io.netty/netty-common/4.1.34.Final`). - -Dependencies on other openHAB bundles should have the scope `provided`. -To ensure that they are available at runtime they also need to be added to the `feature.xml`: +If the embedded bundle's manifest is not properly exporting all needed packages, you can import them manually by adding ```xml - mvn:org.openhab.addons.bundles/org.openhab.binding.bluetooth/3.1.0-SNAPSHOT + + netty-common + ``` -### Internal dependency - -In two cases libraries can be added to the `/lib` directory: +### External dependency -1. The bundle is not available for download -1. The bundle is not an OSGi bundle but needs to be used for integration tests. - Unlike Karaf, BND is not able to wrap bundles on its own. - In this case the binding works as wrapper. - You need add the library and export all needed packages manually. +In two cases using an "external" (i.e. not embedded) dependency is required: -The build system automatically picks up all JAR files in `/lib` and embeds them in the new bundle. -In this case they must not be added to the feature. +1. Dependencies to other openHAB bundles (e.g. `org.openhab.addons.bundles/org.openhab.binding.bluetooth/3.1.0-SNAPSHOT` or `org.openhab.addons.bundles/org.openhab.transform.map/3.1.0-SNAPSHOT`). +2. Bundles that are used by more than one binding (e.g. Netty-bundles like `io.netty/netty-common/4.1.34.Final`). -If the bundles manifest is not properly exporting all needed packages, you can import them manually by adding +Dependencies on other openHAB bundles should always have the scope `provided`. +To ensure that external dependencies are available at runtime they also need to be added to the `feature.xml`: ```xml - - netty-common - + mvn:org.openhab.addons.bundles/org.openhab.binding.bluetooth/${project.version} + mvn:com.github.foo/bar/2.0.0 ``` -It is also necessary to add them to the `feature.xml`(see above). +Using release versions is mandatory. If the version that is used in other openHAB bundles is incompatible with your library, check if you can use a different version of your library. In case this is not possible, please ask if an exception can be made and a different version can be bundled within your binding. Technically you just need to omit the exclusion-statement above. If you only depend on shared bundles you can also omit the exclusion statement and add a `noEmbedDependencies.profile` file in the root directory of your binding. -If the imported packages need to be exposed to other bundles (e.g. case 2 above), this has to be done manually by adding +If the imported packages need to be exposed to other bundles, this has to be done manually by adding ```xml @@ -87,6 +76,7 @@ to the POM. If `version="1.0.0"` is not set, the packages are exported with the same version as the main bundle. Optional parameters available for importing/exporting packages (e.g. `foo.bar.*;resolution:="optional"`) are available, too. Packages can be excluded from import/export by prepending `!` in front of the name (e.g. `!foo.bar.*` would prevent all packages starting with foo.bar from being imported). +Using `resolution:="optional` is generally preferred over exclusion. ## Karaf Feature