Skip to content

Commit

Permalink
[development] Adding generic, maven based run and debug. (#2435)
Browse files Browse the repository at this point in the history
* [development] Adding generic, maven based run and debug.

Also see openhab/openhab-distro#1707

Signed-off-by: Gwendal Roulleau <[email protected]>

* [development] Adding generic, maven based run and debug.

Apply MR comments

Signed-off-by: Gwendal Roulleau <[email protected]>

* [development] Adding generic, maven based run and debug.

Apply MR comments

Signed-off-by: Gwendal Roulleau <[email protected]>

---------

Signed-off-by: Gwendal Roulleau <[email protected]>
  • Loading branch information
dalgwen authored Dec 30, 2024
1 parent c64ed13 commit 3298dc8
Show file tree
Hide file tree
Showing 9 changed files with 138 additions and 18 deletions.
9 changes: 9 additions & 0 deletions .vuepress/docs-sidebar.js
Original file line number Diff line number Diff line change
Expand Up @@ -213,6 +213,15 @@ module.exports = [
collapsable: true,
children: [
['developer/', 'Overview & Introduction'],
{ title: 'IDEs',
collapsable: true,
children: [
'developer/ide/eclipse',
'developer/ide/intellij',
'developer/ide/vscode',
'developer/ide/generic',
]
},
'developer/guidelines',
'developer/addons/',
'developer/bindings/',
Expand Down
76 changes: 76 additions & 0 deletions developers/ide/generic.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,76 @@
---
layout: developersguide
title: Generic IDEs hints
---

# Generic setup for your IDE

## The demo project with Maven

It can be particularly useful, regardless of the IDE, to be able to launch a development instance of openHAB.
This is the purpose of the `org.openhab.demo.app` project, which can be found in the `openhab-distro` repository.

To do this, you need to clone the [openhab distro repository](https://www.github.com/openhab/openhab-distro)

To launch the demo project, Eclipse [has its bnd plugin](./eclipse.html#working-with-add-ons).
However, it can sometimes be particularly slow. Maven is therefore a completely viable alternative (and the only option
available for other IDEs).
Using the demo project through Maven will allow you to run an openHAB instance that uses the artifacts present in your
local Maven repository (and downloads them beforehand if they are not already present).

This means that if you develop an add-on (or even a `openhab-core` module), once you have built and installed it, it
will be available in your local repository and the demo project will be able to use your development.

### Build project

::: warning
Make sure you meet the prerequisites like the Java and Maven version. As of openHAB 5.x Java 21.x is required and at least mvn 3.8.6.
:::

Use Maven to build the projects you want to develop for. It is important to use the `mvn install` option to copy the artifact in your local repository.

### Preparation

There are two files to take care of:

- `/openhab-distro/launch/app/pom.xml` must contain the artifact you are developing in the dependencies section (search for "uncomment this and add the name of your binding that you want to work on")

- `/openhab-distro/launch/app/app.bndrun` will list the modules needed by the OSGi runtime. You also have to add your add-on in the `runrequires` section (e.g. `bnd.identity;id='org.openhab.binding.YOURBINDINGNAME'` and don't forget to add the `\` to the previous line if you adding it to the end of the list)

After editing this two files, use this maven command from the `/openhab-distro/launch/app/` directory:

`mvn bnd-resolver:resolve`

This will ask the bnd plugin to 'resolve' the dependencies (i.e. to calculate which bundles to run in the OSGi runtime) and update
the `runbundles` section of the `app.bndrun` file accordingly.
Each time you add a dependency or change the version, you HAVE to run a resolve task.

::: warning
The `pom.xml` file is versioned. The version fields present in the file must match the modules
you are developing. For example, if you are developing a module for `openhab-core` and it is deployed as version
5.0.0-SNAPSHOT in your local repository, you must use this same 5.0.0-SNAPSHOT version in the version field of the
`org.openhab.demo.app` artifact. Similarly, for add-on development, ensure that the version field of your add-on in the
pom.xml file matches the version you are currently developing. If you use incorrect versions, you will not understand
why your changes are not being taken into account
:::

### Launching and debugging

Go to the directory `/openhab-distro/launch/app`

To launch the demo app, using the content of the `app.bndrun` file:

`mvn bnd-run:run`

You can now open the app in your browser via [http://localhost:8080/](http://localhost:8080/).

To launch in debug mode:

`mvn -D-runjdb=10001 package bnd-run:run`

Wait for the process to pause and show the log `Listening for transport...` then attach your IDE to the remote debugging
session (here, on port 10001). The openHAB demo project startup process will then resume and you will be able to
open it in your browser.

Each modification of your code requires rebuilding your add-on with `mvn clean install` so that it is
deployed in your local repository and accessible for the next execution.
Binary file added developers/ide/images/generic_ide.pdn
Binary file not shown.
Binary file added developers/ide/images/generic_ide.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
58 changes: 44 additions & 14 deletions developers/ide/intellij.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,30 +7,44 @@ title: IntelliJ

## Prerequisites

- git, Maven, IntelliJ and Java 17 are installed
- git, Maven (at least 3.8.6), IntelliJ and Java (21) are installed and available in the path.

## Install openHAB distribution
## Build the repositories

1. Install the official [openHAB distribution](https://www.openhab.org/download/)
1. Start the distribution **in debug mode** (use `./start_debug.sh` instead of `./start.sh` in step 4)
1. Fork and clone the repositories into a parent directory (Reference `<PARENT_DIR>` from now on for this article). Take only the one(s) you will work on:

This article refers to the directory where you installed the distribution as `<DISTRO_DIR>`.
- [openhab addons repository](https://www.github.com/openhab/openhab-addons)
- [openhab core repository](https://www.github.com/openhab/openhab-core)
- [openhab webui repository](https://www.github.com/openhab/openhab-webui)

## Build the addons repository
Use the command `git clone https://github.com/<yourgitusername>/openhab-<addons|core|webui>` (replace git user name accordingly).

1. Fork and clone the [openhab addons repository](https://www.github.com/openhab/openhab-addons) into a new directory (Reference `<ADDON_DIR>` from now on for this article) with `git clone https://github.com/<yourgitusername>/openhab-addons` (replace git user name accordingly)
1. Open IntelliJ, select the file/open, and choose the `<PARENT_DIR>`
1. Open The Module settings (inside `Project Settings`, or use F4). Click on the + button and select `Import module`.
1. Choose one of the repository directory you just cloned. select the Maven external model as import format.
IntelliJ will start importing and indexing. It will take while, wait until finished. The Module window should now be filled with a bunch of projects.
![Import modules](images/ide_setup_intellij_import_module.png)
1. Repeat step 2 and 3 for all repositories you cloned.
1. Use Maven to clean & install projects. Make sure you use the required Maven version (3.8.6 is recommended).

1. Open IntelliJ and create a new project from existing sources (File | New | Project from existing sources) and pick `<ADDON_DIR>`/pom.xml
- `mvn clean install` in the root of the repositories using commandline Maven (or IntelliJ Maven view)
- some of the add-ons might fail to build - if it's not the one you're interested in, that should not bother you
- when the Maven project finished, you should find the freshly built addon JAR in the target directory

IntelliJ will start importing, indexing and building, it will take while, wait until finished (see status bar)
You then have two main options to run your development: use the official distribution, or use Maven.

1. Use Maven to clean & install the addons project
## Option 1: Use and debug from the official distribution

- mvn clean install in the root of `<ADDON_DIR>` using commandline Maven (or IntelliJ Maven view)
- some of the add-ons might fail to build - if it's not the one, you're interested in that should not bother you
- when the Maven project finished, you should find the freshly built addon JAR in the target directory
This is the simpler option, but you can only use it for add-on development.

## Debug your addon
### Install openHAB distribution

1. Install the official [openHAB distribution](https://www.openhab.org/download/)
1. Start the distribution **in debug mode** (use `./start_debug.sh` instead of `./start.sh` in step 4)

This article refers to the directory where you installed the distribution as `<DISTRO_DIR>`.

### Debug your addon

1. Copy the addon JAR to Openhab distribution created before

Expand All @@ -52,3 +66,19 @@ This article refers to the directory where you installed the distribution as `<D
![Remote Debug Run Configuration](images/ide_setup_intellij_debug_configuration.png)

You can now add breakpoints to your project now and your test distro should stop there.

## Option 2: Use maven-bdn plugin and the demo project

This option is more complex, but will allow you to run/debug anything.
You will have to clone the additional repository openhab-distro repository in your `<PARENT_DIR>`. It contains the demo project.
Look at the [generic IDEs information](./generic.md) to know more about how to prepare and launch the demo project.

After this, instead of using the command line, you can setup IntelliJ to launch the maven tasks.

![Launch Maven Task](./images/ide_setup_intellij_debug.png)

When launching the demo project from IntelliJ with the bnd debug option (in VM options in the screenshot above),
look in the Run window for the mention "Listening for transport".
You can then click on the `Attach debugger` to automatically start a debugging session.

![Attach debugger](./images/ide_setup_intellij_debug_attach.png)
13 changes: 9 additions & 4 deletions developers/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -63,22 +63,27 @@ We have prepared some step-by-step guides for the following IDEs:

<table style="width:100%">
<tr>
<td style="width:30%">
<td style="width:50%">

[![Visual Studio Code](./ide/images/vscode.jpg)](ide/vscode.html)

</td>
<td style="width:30%">
<td style="width:50%">

[![Eclipse IDE](./ide/images/eclipse.jpg)](ide/eclipse.html)

</td>
<td style="width:30%">
</tr>
<tr>
<td style="width:50%">

[![IntelliJ IDE](./ide/images/intellij.jpg)](ide/intellij.html)

</td>
</tr>
<td style="width:50%">

[![Generic IDE](./ide/images/generic_ide.png)](ide/generic.html)

</table>

Not sure what to choose?: openHAB maintainers use [Eclipse IDE](https://wiki.eclipse.org/Eclipse_Installer).
Expand Down

0 comments on commit 3298dc8

Please sign in to comment.