diff --git a/.vuepress/docs-sidebar.js b/.vuepress/docs-sidebar.js index efa4b8d3bc..63b1d84d3b 100644 --- a/.vuepress/docs-sidebar.js +++ b/.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/', diff --git a/developers/ide/generic.md b/developers/ide/generic.md new file mode 100644 index 0000000000..940cb151d2 --- /dev/null +++ b/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. diff --git a/developers/ide/images/generic_ide.pdn b/developers/ide/images/generic_ide.pdn new file mode 100644 index 0000000000..931f2dfef9 Binary files /dev/null and b/developers/ide/images/generic_ide.pdn differ diff --git a/developers/ide/images/generic_ide.png b/developers/ide/images/generic_ide.png new file mode 100644 index 0000000000..39cf58d19e Binary files /dev/null and b/developers/ide/images/generic_ide.png differ diff --git a/developers/ide/images/ide_setup_intellij_debug.png b/developers/ide/images/ide_setup_intellij_debug.png new file mode 100644 index 0000000000..29a0cea3fe Binary files /dev/null and b/developers/ide/images/ide_setup_intellij_debug.png differ diff --git a/developers/ide/images/ide_setup_intellij_debug_attach.png b/developers/ide/images/ide_setup_intellij_debug_attach.png new file mode 100644 index 0000000000..30b216f9ce Binary files /dev/null and b/developers/ide/images/ide_setup_intellij_debug_attach.png differ diff --git a/developers/ide/images/ide_setup_intellij_import_module.png b/developers/ide/images/ide_setup_intellij_import_module.png new file mode 100644 index 0000000000..81ff542db8 Binary files /dev/null and b/developers/ide/images/ide_setup_intellij_import_module.png differ diff --git a/developers/ide/intellij.md b/developers/ide/intellij.md index 3b46d002bb..a1286ab840 100644 --- a/developers/ide/intellij.md +++ b/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. 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 `` 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 ``. + - [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//openhab-` (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 `` from now on for this article) with `git clone /~https://github.com//openhab-addons` (replace git user name accordingly) +1. Open IntelliJ, select the file/open, and choose the `` +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 ``/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 `` 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 ``. + +### 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 ``. 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) diff --git a/developers/index.md b/developers/index.md index c278589707..ea7b503e6b 100644 --- a/developers/index.md +++ b/developers/index.md @@ -63,22 +63,27 @@ We have prepared some step-by-step guides for the following IDEs: - - - + + - +
+ [![Visual Studio Code](./ide/images/vscode.jpg)](ide/vscode.html) + [![Eclipse IDE](./ide/images/eclipse.jpg)](ide/eclipse.html) +
[![IntelliJ IDE](./ide/images/intellij.jpg)](ide/intellij.html)
+ +[![Generic IDE](./ide/images/generic_ide.png)](ide/generic.html) +
Not sure what to choose?: openHAB maintainers use [Eclipse IDE](https://wiki.eclipse.org/Eclipse_Installer).