[development] Adding generic, maven based run and debug. (#2435)

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

Also see https://github.com/openhab/openhab-distro/pull/1707

Signed-off-by: Gwendal Roulleau <gwendal.roulleau@gmail.com>

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

Apply MR comments

Signed-off-by: Gwendal Roulleau <gwendal.roulleau@gmail.com>

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

Apply MR comments

Signed-off-by: Gwendal Roulleau <gwendal.roulleau@gmail.com>

---------

Signed-off-by: Gwendal Roulleau <gwendal.roulleau@gmail.com>

.vuepress/docs-sidebar.js

@@ -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/',

developers/ide/generic.md

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

developers/ide/intellij.md

@@ -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. 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:
+
+    - [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)
+
+Use the command `git clone https://github.com/<yourgitusername>/openhab-<addons|core|webui>` (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).
+
+    - `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
+
+You then have two main options to run your development: use the official distribution, or use Maven.
+
+## Option 1: Use and debug from the official distribution
+
+This is the simpler option, but you can only use it for add-on development.
+
+### 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>`.
 
-## Build the addons repository
-
-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 and create a new project from existing sources (File | New | Project from existing sources) and pick `<ADDON_DIR>`/pom.xml
-
-    IntelliJ will start importing, indexing and building, it will take while, wait until finished (see status bar)
-
-1. Use Maven to clean & install the addons project
-
-    - 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
-
-## Debug your addon
+### Debug your addon
 
 1. Copy the addon JAR to Openhab distribution created before
 
@@ -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)

developers/index.md

@@ -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).