Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improve add-on dependency documentation #2211

Merged
merged 1 commit into from
Jan 17, 2024
Merged

Improve add-on dependency documentation #2211

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 16 additions & 26 deletions developers/buildsystem.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`:

Expand All @@ -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
<bundle dependency="true">mvn:org.openhab.addons.bundles/org.openhab.binding.bluetooth/3.1.0-SNAPSHOT</bundle>
<properties>
<dep.noembedding>netty-common</dep.noembedding>
</properties>
```

### 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
<properties>
<dep.noembedding>netty-common</dep.noembedding>
</properties>
<bundle dependency="true">mvn:org.openhab.addons.bundles/org.openhab.binding.bluetooth/${project.version}</bundle>
<bundle dependency="true">mvn:com.github.foo/bar/2.0.0</bundle>
```

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
<properties>
Expand All @@ -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. `<bnd.importpackage>!foo.bar.*</bnd.importpackage>` would prevent all packages starting with foo.bar from being imported).
Using `resolution:="optional` is generally preferred over exclusion.

## Karaf Feature

Expand Down