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

Also see openhab/openhab-distro#1707

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

developers/ide/generic.md

@@ -0,0 +1,69 @@
+---
+layout: developersguide
+title: Generic IDEs hints
+---
+
+# Demo project
+
+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)
+
+
+## Use of Maven for the demo project
+
+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
+
+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.
+
+- `/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.
+
+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 what to run in the OSGi runtime.
+This task will update the `runbundles` section of the `app.bndrun` file.
+Each time you add a dependency or change 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`
+
+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.
+
+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

@@ -9,28 +9,40 @@ title: IntelliJ
 
 - git, Maven, IntelliJ and Java 17 are installed
 
-## 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:
+  - [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)
 
-This article refers to the directory where you installed the distribution as `<DISTRO_DIR>`.
+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>`
+2. Open The Module settings (inside `Project Settings`, or use F4). Click on the + button and select `Import module`.
+3. Choose one of the repository directory you just cloned. 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.
+4. Repeat step 2 and 3 for all repositories you cloned.
+5. Use Maven to clean & install projects
 
-## Build the addons repository
+  - `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
 
-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)
+You then have two main options to run your development. Use the official distribution, or use Maven.
 
-1. Open IntelliJ and create a new project from existing sources (File | New | Project from existing sources) and pick `<ADDON_DIR>`/pom.xml
+## Option 1: Use and debug from the official distribution
 
-    IntelliJ will start importing, indexing and building, it will take while, wait until finished (see status bar)
+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)
 
-1. Use Maven to clean & install the addons project
+This article refers to the directory where you installed the distribution as `<DISTRO_DIR>`.
 
-    - 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 +64,21 @@ 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 fork an additional repository in your `<PARENT_DIR>`. It contains the demo project.
+- [openhab distro repository](https://www.github.com/openhab/openhab-distro)
+
+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

@@ -82,7 +82,7 @@ We have prepared some step-by-step guides for the following IDEs:
 </td>
 <td style="width:50%">
 
-[Generic IDE](ide/generic.html)
+[![Generic IDE](./ide/images/generic_ide.png)](ide/generic.html)
 
 </table>