OpenHAB
/
openhab-docs
mirror of https://github.com/openhab/openhab-docs.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Updated docs wrt IDE setup (both add-on and core development IDEs) (#897) 

* Updated docs wrt IDE setup (both add-on and core development IDEs)

Signed-off-by: Kai Kreuzer <kai@openhab.org>
pull/901/head
Kai Kreuzer 2019-02-14 21:30:32 +01:00 committed by GitHub
parent c45056baa3
commit 23925fc5fd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 41 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
developers/development/ide.md
View File

@ -19,7 +19,7 @@ Please ensure that you have the following prerequisites installed on your machin
1. [Maven 3.x](https://maven.apache.org/download.cgi) (optional, Eclipse m2e can also be used)
1. [Oracle JDK 8](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html)
## Installation
## Installing the Eclipse IDE
The Eclipse IDE is used for openHAB developments. The Eclipse Installer automatically prepares the IDE so that it comes with all required plug-ins, the correct workspace encoding settings, pre-configured code formatters and more. Simply follow these steps:
@ -28,41 +28,57 @@ The Eclipse IDE is used for openHAB developments. The Eclipse Installer automati
![Step 0](images/ide0.png)
3. Choose the "Eclipse IDE for Java Developers" and select "Next":
![Step 1](images/ide1.png)
4. Expand "Github Projects", then "openHAB". Select the "openHAB Development" item and any other entries that you want to have available in your workspace (you can select multiple/all of them). Click "Next" when you are finished.
5. Now provide an installation folder (don't use spaces in the path on Windows!) and your Github id (used to push your changesets to) and select "Next".
6. The installation will now begin when pressing "Finish".
7. Once it is done, you will see the Eclipse Welcome Screen, which you can close by clicking "Workbench" on the top right. You will see that the installer not only set up an Eclipse IDE instance for you, but also checked out all selected git repositories and imported all projects into the workspace.
8. Your workspace should now fully compile and you can start the runtime by launching the "openHAB_Runtime" launch configuration.
4. Expand "Github Projects", then "openHAB".
Note that you will find the sources in a subfolder called "git" within your selected installation folder. You can use any kind of git client here, if you do not want to use the git support from within the Eclipse IDE.
If you want to push changes, you need to do so to your personal fork of the repository in order to create a pull request. You will find more details in the ["How to contribute"](../contributing/contributing.html) documentation.
From here, you can now follow two different paths: One for add-on/binding development (the right choice for most developers) or one for the core framework development.
Both are currently based on different build systems and thus require separate IDE setups.
## Building, Running and Debugging
### Option 1: Installation of IDE for Add-on Development
Now that you have the development environment set up, let's try to build, run and debug.
1. Select (double-click) the "openHAB Add-on Development" item and any other entries (apart from "openHAB Core Development") that you want to have available in your workspace (you can select multiple/all of them). Click "Next" when you are finished.
2. Now provide an installation folder (don't use spaces in the path on Windows!) and your Github id (used to push your changesets to) and select "Next".
3. The installation begins when you press "Finish".
4. Once it is done, you will see the Eclipse Welcome Screen, which you can close by clicking "Workbench" on the top right. You will see that the installer not only set up an Eclipse IDE instance for you, but also checked out all selected git repositories and imported all projects into the workspace.
5. Your workspace should now fully compile and you can start the runtime by launching the "openHAB_Runtime" launch configuration.
Building:
In the Package Explorer tab you will see the openHAB components that were checked out from Git.
Open the "Infrastructure > launch" folder.
Right click on openHAB_Runtime.launch, select "Run as > openHAB_Runtime".
You should now see output in the console window.
Building for the purpose of running is done from within eclipse. First take a look at the problems tab and check for existing errors. If you see something there after a clean install, do Help > Perform Setup Tasks. If errors remain, try to find them in the project. In my case a couple of bindings were failing to compile for unknown reasons. Simply right click on the offenders and "close project" them.
Debugging is done in the same way as running, but instead of Run as, select "Debug as > openHAB_Runtime".
openHAB will launch, and the debugger will stop at any breakpoint that you have set in the code.
Let's do a Clean/Build cycle. Project > Clean ... > Clean all projects/Start build immediately. Eclipse should now take a short time to build everything. Check the Problems tab for errors. All errors should now be gone, and we can proceed to running.
Note that projects from your workspace are not by default started by the launch config.
To add them, you must right click on openHAB_Runtime.launch > Run as > Run configurations ... and go to the Plug-ins tab.
In the Workspace section, select all add-ons that you want to be included in the launch.
Note, that if you wish to produce a distribution binary that you will later copy to a different machine, you will need to build in a different manner. Distribution builds are done with maven. Go into the root directory of the project and run 'mvn install'
### Option 2: Installation of IDE for Core Development
Running:
1. Select (double-click) the "openHAB Core Development" item and click "Next".
2. Now provide an installation folder (don't use spaces in the path on Windows!) and your Github id (used to push your changesets to) and select "Next".
3. The installation begins when you press "Finish".
4. Trust any certificate you are asked for.
5. Once it is done, you will see the Eclipse Welcome Screen, which you can close by clicking "Workbench" on the top right. The initial tasks are executed. Wait until the bottom right corner of the IDE does not show "Build" or "Refreshing workspace" or any other progress messages.
6. Select "Help", "Perform Setup Tasks..." and press "Finish".
7. The dialog disappears but could be opened again using the icon in the (bottom) status bar (near to the left side). You should open it and check it, because the chance is high that a restart is requested. The process (perform setup tasks) continues after the restart has been done. You can bring the dialog to the front after the restart using the same icon. Wait until all tasks have finished (wait for an empty buttom right status field).
In the Package Explorer tab you will see the OpenHAB components that were installed. Open the "Infrastructure > launch" folder. Right click on openHAB_Runtime.launch, select "Run as > openHAB_Runtime". You should now begin to see output in the console window.
To launch the openHAB Core runtime from the IDE, open Demo -> org.openhab.core.demo.app and open "app.bndrun".
In the opened editor either click "Run OSGi" or "Debug OSGi" and the runtime will be started up.
Debugging:
### Start Coding & Contributing
For this exercise we will need the "ESH Extensions" package installed. Go into "ESH Extensions/org.eclipse.smarthome.binding.yahooweather" folder. This is the yahoo weather binding and we will use it as an example. Let's add a small change to the code, and put a breakpoint on the location so that we can see our changes show up in the debugger.
Note that for both options, you will find the sources in a subfolder called "git" within your selected installation folder.
You can use any kind of git client here, if you do not want to use the git support from within the Eclipse IDE.
If you want to push changes, you need to do so to your personal fork of the repository in order to create a pull request.
You will find more details in the ["How to contribute"](../contributing/contributing.html) documentation.
Open YahooWeatherHandler.java and take a look at line 60. It is the log print from the initialize function.
## Refreshing the IDE
logger.debug("Initializing YahooWeather handler.");
If you have resolution errors of dependencies or other unexplicible errors, you might have to update your IDE.
To do so, select Help -> Perform Setup Tasks.
Add some text to the string and save the file. Now put a breakpoint on this line. Build as above.
Debugging is done in the same way as running, but instead of Run as, select "Debug as > openHAB_Runtime". OpenHAB will launch, and the debugger will stop at the breakpoint, but our change won't be there. To fix this we need to let eclipse know that we've made changes to this binding.
Right click on openHAB_Runtime.launch > Run as > Run configurations ... Go to the Plug-ins tab. Notice that under "Target Platform" org.eclipse.smarthome.binding.yahooweather is checked. But, under Workspace the same org.eclipse.smarthome.binding.yahooweather is not checked. Do so now. Try the debug session again. You should now see the modified code show up in the debugger.
If the errors remain, do a Clean/Build cycle. Project > Clean ... > Clean all projects/Start build immediately.
Eclipse should now take some time to build everything.
Check the Problems tab for errors.
All errors should now hopefully be gone.