The build system has been migrated to a Maven + Bnd based build system. Bindings not yet merged into the openHAB2-addons repository or external bindings need to be migrated to the new build system in order to be accepted and to make them work with the current build system.
This tutorial will make use of git and maven command line tools.
Background
openHAB is a java project that is build around the OSGi framework. openHAB add-ons are OSGi bundles.
Over the years the bnd software (“bnd is the engine behind a number of popular software development tools that support OSGi”) has established itself as the defacto standard for creating OSGi bundles.
The openHAB maintainers have decided to move from the very Eclipse centric buildsystem to maven/bnd. A combination that not only allows to develop bindings seamlessly in other IDEs than Eclipse, but Java beginners and intermediates find a commonly known maven build system.
This tutorial describes in a step-by-step approach how to migrate a binding. The steps described here use git and maven on the command line.
Step 1: Backup your current work
If you don’t have a backup already of your binding, copy your binding from the your source tree to some other place. This will be your backup for the migration. We need these later in the migration step.
You can also make an additional backup by creating another branch in git with the following command:
git checkout -b <name your backup branch>
Step 2: Installing the IDE
Before you start, it’s best to freshly set up your development environment. For development ONLY USE JAVA 8. Either install Eclipse or if you prefer VisualCode or IntelliJ. See the documentation on how to install: Developer Guide | openHAB. This tutorial describes the steps using Eclipse.
When installing Eclipse ONLY select openHAB Development in the Eclipse installer.
Step 3: Getting your old code into the new installation
Copy your original clone of the openhab2-addons repo to the newly installed git directory.
Step 4: Getting your current branch up-to-date with the latest sources
Note: This step destroys the content of your current branch. So any changes on this branch will be lost. That’s why you should back it up
This step is only really relevant if you have a pr pending. If you don’t have a pr pending it’s easier to start with a new clean git branch and update that to the latest sources.
So if you have a pr pending first make sure your on the branch of your pr with your binding:
git checkout <my pr branch>
Now get the latest code from the openhab2-addons repo (this assumes the remote openhab2-addons is on origin. If you have a different name replace origin with your name. If you don’t know what I’m talking about here, you probably have origin):
git fetch origin
The following command will update your branch to the latest code that you just have fetched in the previous command. NOTE this will destroy any changes on your branch, do you have backups! (note this being git, it isn’t directly gone, but that is outside the scope here, hint: reflog)
git reset --hard origin/master
Cleanup the brute force way. You have likely untracked changes after this command.
You can now delete the
addonsfolder.
Check if you still have any (untracked) changes with git status:
git status
If everything is clean it shows: nothing to commit, working tree clean. But if there are untracked files you can get ride of them with the following commands (I admit a bit brute force):
git stash -u
git stash drop
What it does. It pushes any (untracked) changes to the git stack. The second command simple deletes them from the stack.
Step 5: Create the new basis of your binding
With the create_openhab_binding_skeleton script in the bundles folder we’re going to create the basis for your migrated binding. The bindings have been moved from the addons folder to the `bundles folder. Run the following command to create the basis for your binding. The skeleton script also updates all files outside your binding folder that are needed to be adapted for new bindings.
On Linux:
create_openhab_binding_skeleton.sh <binding name> "<your full name>" <your github name>
On Windows:
create_openhab_binding_skeleton.cmd <binding name> "<your full name>" <your github name>
This will generate a new binding in the bundles/org.openhab.binding.<binding name> folder. The following steps are all relative to this folder. More on the skeleton script can be found here: Developer Guide | openHAB
Step 6: Clean up the generated binding
The skeleton script generates an example binding. Because we are going to migrate an existing binding we don’t need those files. So you can clean the following files/directories:
- Remove README.md
- Clean
src/main/java - Clean
scr/main/resources
Step 7: Copy your code back into the newly generated binding
To get your binding code into the newly generated binding copy the following files:
- Copy your README.md and any related files (i.e. images) into your binding folder
- Copy your java source files to
src/main/java - Copy the
ESH-INFfolder intosrc/main/resources
If you have any other additional files they either go in the root of your binding or if the relevant for runtime. They go in the src/main/resources/
Additional Modifications:
- If you have an
OSGI-INFfolder you need to replace the xml files with annotations in JAVA. TheOSGI-INFfolder is related to how OSGI services are enabled. In the past we did this by xml files inOSGI-INFfolder. But some time ago we switched to using annotations. And any pull request containing them is kindly asked to change it to annotations. If you already have annotations.gitignorefiles in theOSGI-INFfolder can be removed. Because the xml configuration isn’t accepted anymore the documentation on the xml files has been removed. To migrate the xml configuration here is an old documentation page that shows both xml and annotations. openhab-docs/developers/prerequisites/osgids.md at c58e7b9b87bd69826cf90ce450cdfddba7b2d79f · openhab/openhab-docs · GitHub There is also more documentation on the annotations: OSGi Declarative Services | openHAB But probably the easiest way is to look at other bindings! - The schema location in the
ESH-INFxml files must be updated:
OLD:http://eclipse.org/smarthome/schemas/..
NEW:https://openhab.org/schemas/... - The schema location
xsi:schemaLocationin the pom.xml must be updated:
OLD:http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd
NEW:http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd
Step 8 (Optional): Handling additional libraries
If you have additional libraries in a lib folder. You need to migrate those. In the documentation this is described in detail: Build System | openHAB
Also this is might be a good time to check if you use libraries that contain functionality also supported by core libraries, and you actually don’t need those extra libraries.
Step 9: Importing the binding in Eclipse
In eclipse Import the binding via File import. Select as an existing project.
If you have a dependency on guava you need to replace those method calls, because we don’t support guava anymore in bindings. In most cases only a single class was used from this library. You will have compile errors in this case.
Step 10: Add your binding to the debug/demo app
With openHAB2 Development and demo app is available. To debug your binding, add the dependency of your binding to the pom.xml of the demo app. (The one next to app.bndrun). See also out Eclipse documentation for up-to-date details: Eclipse IDE | openHAB
Step 11: Check and Compile
To check if everything is ok. We can build the binding with maven. Use the following command from the openHAB2-addons root folder:
mvn clean install -pl :org.openhab.binding.<your binding>
This will also produce a html report file. It’s a good practice to fix those issues.
Step 12: Push your changes back to Github.
Now we’re completed the migration and can compile the new binding we need to push the changes back to the branch on Github. Use the following command:
git push --force-with-lease
Don’t forget to use the force, otherwise you will get a lot of merge commits.
Finished!!
You made it 
If you have a pr pending ping us on the pr that you want to have your pr merged 
And if add any more commits. Don’t forget to sign-off on them!
Bonus: Writing Unit Tests
One of the advantages of the new build system is that it allows you to add tests much easier. While with the old build system you needed to setup a whole project. You can now add your unit tests to src/test/java. This allows you to write unit and mocked tests. If you would have a test that needs a working OSGI container you still need to setup a separate project. These are located in the itests folder. But most cases can be handled by mocking and setting up your code architecture such it’s not all in a big class.
If you have any questions or improvements to this tutorial let me know in the comments.
This text was originally posted in the now closed issue 5005 https://github.com/openhab/openhab2-addons/issues/5005#issuecomment-467973902 To give it more visibility the text has been updated and placed here on the forum.
