Merge commit '6ac9f36044943ed4d7277fa9b42a2cee443a21b6' into HEAD
openHAB Build Server
commit
890d8f157e
|
|
@ -73,8 +73,8 @@ def process_file(indir, file, outdir, source)
|
|||
puts " (add-on is from ESH)"
|
||||
source = "https://github.com/eclipse/smarthome/blob/master/extensions/#{addon_type}/org.eclipse.smarthome.#{addon_type}.#{addon}/README.md"
|
||||
elsif !(file =~ /things/) then
|
||||
puts " (add-on is from openhab2-addons)"
|
||||
source = "https://github.com/openhab/openhab2-addons/blob/master/addons/#{addon_type}/org.openhab.#{addon_type}.#{addon}/README.md"
|
||||
puts " (add-on is from openhab-addons)"
|
||||
source = "https://github.com/openhab/openhab-addons/blob/master/addons/#{addon_type}/org.openhab.#{addon_type}.#{addon}/README.md"
|
||||
end
|
||||
|
||||
out.puts "source: #{source}" if source != ""
|
||||
|
|
|
|||
|
|
@ -142,7 +142,6 @@ def process_main_docs(docs_source_dir)
|
|||
|
||||
puts " -> images"
|
||||
FileUtils.cp_r("#{docs_source_dir}/developers/bindings/images", "docs/developer/bindings/images")
|
||||
FileUtils.cp_r("#{docs_source_dir}/developers/legacy/images", "docs/developer/legacy/images")
|
||||
FileUtils.cp_r("#{docs_source_dir}/developers/osgi/images", "docs/developer/osgi/images")
|
||||
FileUtils.cp_r("#{docs_source_dir}/developers/ide/images", "docs/developer/ide/images")
|
||||
|
||||
|
|
|
|||
|
|
@ -49,7 +49,7 @@ You can read a bit more below about our external ressources and how we get them.
|
|||
### Automatically Generated Parts
|
||||
|
||||
Those parts include __all__ add-on documentation files, no matter if they are from the `openhab-core` repo, the
|
||||
`openhab1-addons` repo, the `openhab2-addons` repo or any special binding repo like *habmin*, *zwave* or the *alexa skill*.
|
||||
`openhab1-addons` repo, the `openhab-addons` repo or any special binding repo like *habmin*, *zwave* or the *alexa skill*.
|
||||
|
||||
We are keeping all those files at their original location, because it simply doesn't make sense to keep them here.
|
||||
Imagine you want to do an improvement of the zwave binding and have to update the readme file in a completely different place.
|
||||
|
|
|
|||
|
|
@ -877,11 +877,11 @@ Various binding related questions are answered in our [Binding development FAQ](
|
|||
|
||||
Once you are happy with your implementation, you need to integrate it in the Maven build and add it to the official distro.
|
||||
|
||||
* Add a new line in the [bundle pom.xml](https://github.com/openhab/openhab2-addons/blob/master/bundles/pom.xml).
|
||||
* Add a new line in the [binding pom.xml](https://github.com/openhab/openhab2-addons/blob/master/bom/openhab-addons/pom.xml).
|
||||
* Add a new line in the [bundle pom.xml](https://github.com/openhab/openhab-addons/blob/master/bundles/pom.xml).
|
||||
* Add a new line in the [binding pom.xml](https://github.com/openhab/openhab-addons/blob/master/bom/openhab-addons/pom.xml).
|
||||
* If you have a dependency on a transport bundle (e.g. upnp, mdns or serial) or an external library,
|
||||
make sure to add a line for this dependency in the `/src/main/feature/feature.xml` file in your binding folder. See the other bindings as an example.
|
||||
* Add your binding to the [CODEOWNERS](https://github.com/openhab/openhab2-addons/blob/master/CODEOWNERS) file so that you get notified by Github when someone adds a pull request towards your binding.
|
||||
* Add your binding to the [CODEOWNERS](https://github.com/openhab/openhab-addons/blob/master/CODEOWNERS) file so that you get notified by Github when someone adds a pull request towards your binding.
|
||||
|
||||
> Please make sure you add the above entries at their alphabetically correct position!
|
||||
|
||||
|
|
|
|||
|
|
@ -12,7 +12,7 @@ title: Contribution
|
|||
The main parts of openHAB can be found in the following repositories:
|
||||
|
||||
* [openHAB Core](https://github.com/openhab/openhab-core): This repo contains the core framework bundles of which the openHAB runtime is constructed.
|
||||
* [openHAB 2 Add-ons](https://github.com/openhab/openhab2-addons): Add-ons (such as bindings, voice services, etc.) of openHAB can be found within this repository. They cannot be used with an openHAB 1.x runtime, since they provide features that the old runtime does not support.
|
||||
* [openHAB Add-ons](https://github.com/openhab/openhab-addons): Add-ons (such as bindings, voice services, etc.) of openHAB can be found within this repository. They cannot be used with an openHAB 1.x runtime, since they provide features that the old runtime does not support.
|
||||
* [openHAB 1 Add-ons](https://github.com/openhab/openhab1-addons): Legacy add-ons that were developed for openHAB 1. Most of them are working smoothly on the openHAB 2 runtime and thus they are made available for backward compatibility reasons. They are not suggested for new users, though.
|
||||
* [openHAB Distro](https://github.com/openhab/openhab-distro): This repo contains all parts that are required for assembling the binary distribution of openHAB.
|
||||
|
||||
|
|
|
|||
|
|
@ -69,7 +69,7 @@ Code styles files are located in here: https://github.com/openhab/static-code-an
|
|||
|
||||
The rules are defined using the Eclipse Java Formatter definitions. There are plugins available for several IDEs that support these definitons.
|
||||
|
||||
* Official [openHAB Eclipse IDE setup](ide.html) is preconfigured
|
||||
* Official [openHAB Eclipse IDE setup](ide/eclipse.html) is preconfigured
|
||||
* Eclipse standalone installation
|
||||
- You can manually import [openhab_codestyle.xml](https://raw.githubusercontent.com/openhab/static-code-analysis/master/codestyle/src/main/resources/openhab_codestyle.xml) via `Eclipse Preferences -> Java -> Code Style -> Formatter` and [openhab.importorder](https://raw.githubusercontent.com/openhab/static-code-analysis/master/codestyle/src/main/resources/openhab.importorder) via `Eclipse Preferences -> Java -> Code Style -> Organize Imports`
|
||||
* IntelliJ using plugin https://plugins.jetbrains.com/plugin/6546-eclipse-code-formatter
|
||||
|
|
|
|||
|
|
@ -31,14 +31,14 @@ This guide describes the steps to setup Eclipse and how to debug an add-on in Ec
|
|||
|
||||
|
||||
|
||||
1. Under `GitHub Projects > openHAB` select `openHAB Development` and any desired option from `openHAB Add-ons` (includes all add-ons from openhab2-addons repo), `openHAB ZigBee Binding` or `openHAB Z-Wave Binding`.
|
||||
1. Under `GitHub Projects > openHAB` select `openHAB Development` and any desired option from `openHAB Add-ons` (includes all add-ons from openhab-addons repo), `openHAB ZigBee Binding` or `openHAB Z-Wave Binding`.
|
||||
|
||||
|
||||
|
||||
| Selection | Install if |
|
||||
|-------------------------|---------------------------------------|
|
||||
| **openHAB Development** | **Debug/Demo Environment (Required)** |
|
||||
| openHAB Add-ons | Installs all openHAB 2 Add-ons |
|
||||
| openHAB Add-ons | Installs all openHAB Add-ons |
|
||||
| openHAB ZigBee Binding | ZigBee Binding Development |
|
||||
| openHAB Z-Wave Binding | Z-Wave Binding Development |
|
||||
| openHAB BACNet Binding | BACNet Binding Development |
|
||||
|
|
@ -46,12 +46,12 @@ This guide describes the steps to setup Eclipse and how to debug an add-on in Ec
|
|||
| openHAB Core Framework | Core Framework Development |
|
||||
|
||||
::: warning Attention
|
||||
If you have selected `openHAB Add-ons` the installer will check out the [openHAB 2.x Add-ons](https://github.com/openhab/openhab2-addons/) repository and all add-on projects are imported in Eclipse.
|
||||
If you have selected `openHAB Add-ons` the installer will check out the [openHAB Add-ons](https://github.com/openhab/openhab-addons/) repository and all add-on projects are imported in Eclipse.
|
||||
|
||||
Select `OH2 Add-ons` and from right-click menu select "Close Projects": *this significantly speeds up the setup*.
|
||||
Re-open only the binding project(s) you would like to work on.
|
||||
|
||||
If you want to develop a new binding or a specific binding it is recommended to clone your own fork of [openHAB 2.x Add-ons](https://github.com/openhab/openhab2-addons/) and import only the projects you work on.
|
||||
If you want to develop a new binding or a specific binding it is recommended to clone your own fork of [openHAB Add-ons](https://github.com/openhab/openhab-addons/) and import only the projects you work on.
|
||||
:::
|
||||
|
||||
|
||||
|
|
@ -77,7 +77,7 @@ This guide describes the steps to setup Eclipse and how to debug an add-on in Ec
|
|||
:::
|
||||
|
||||
Setup tasks will personalize the IDE with openHAB code formatting tools, configurations and a demo app.
|
||||
Setup tasks will also download openHAB latest projects you have selected during installation. Like `openhab-distro` and the add-ons `openhab2-addons` project if you have selected it.
|
||||
Setup tasks will also download openHAB latest projects you have selected during installation. Like `openhab-distro` and the add-ons `openhab-addons` project if you have selected it.
|
||||
|
||||
Click bottom right button in the IDE for Progress.
|
||||
|
||||
|
|
|
|||
|
|
@ -13,7 +13,7 @@ The following steps will only need to be done once to setup both VSCode and your
|
|||
|
||||
1. Install Java Extension Pack for VSCode (https://marketplace.visualstudio.com/items?itemName=vscjava.vscode-java-pack)
|
||||
|
||||
2. Clone the addons (https://github.com/openhab/openhab2-addons.git or preferably your own fork) to %BASE%\openhab2-addons
|
||||
2. Clone the addons (https://github.com/openhab/openhab-addons.git or preferably your own fork) to %BASE%\openhab-addons
|
||||
|
||||
3. If you want to setup openHAB code formatting guidelines, add the following to the VSCode settings:
|
||||
|
||||
|
|
@ -28,17 +28,17 @@ The following steps will only need to be done once to setup both VSCode and your
|
|||
The following steps will show you how to setup a specific bundle for development with VSCode. These steps will show how to setup the Russound bundle but are generic to any bundle in the system.
|
||||
|
||||
1. Ensure the bundle builds correctly (natively with maven)
|
||||
1. Open console to the bundle location (example: `%BASE%\openhab2-addons\bundles\org.openhab.binding.russound`)
|
||||
1. Open console to the bundle location (example: `%BASE%\openhab-addons\bundles\org.openhab.binding.russound`)
|
||||
2. `mvn clean install -DskipChecks` in the console to build the bundle
|
||||
3. Should produce a jar file in the 'target' directory of the bundle(example: `%BASE%\openhab2-addons\bundles\org.openhab.binding.russound\target\org.openhab.binding.russound-2.5.0-SNAPSHOT.jar`)
|
||||
3. Should produce a jar file in the 'target' directory of the bundle(example: `%BASE%\openhab-addons\bundles\org.openhab.binding.russound\target\org.openhab.binding.russound-2.5.0-SNAPSHOT.jar`)
|
||||
|
||||
2. Open VSCode and then open the folder of the bundle. From VSCode - use `File->Open Folder->choose bundle directory` (example: `%BASE%\openhab2-addons\bundles\org.openhab.binding.russound`)
|
||||
2. Open VSCode and then open the folder of the bundle. From VSCode - use `File->Open Folder->choose bundle directory` (example: `%BASE%\openhab-addons\bundles\org.openhab.binding.russound`)
|
||||
|
||||
3. Create a ".vscode" directory under the bundle (example: `%BASE%\openhab2-addons\bundles\org.openhab.binding.russound\.vscode`)
|
||||
3. Create a ".vscode" directory under the bundle (example: `%BASE%\openhab-addons\bundles\org.openhab.binding.russound\.vscode`)
|
||||
|
||||
|
||||
|
||||
4. Download [tasks.json](https://raw.githubusercontent.com/openhab/openhab-docs/master/developers/ide/examples/vscode/tasks.json) to the .vscode directory (example: `%BASE%\openhab2-addons\bundles\org.openhab.binding.russound\.vscode\tasks.json`)
|
||||
4. Download [tasks.json](https://raw.githubusercontent.com/openhab/openhab-docs/master/developers/ide/examples/vscode/tasks.json) to the .vscode directory (example: `%BASE%\openhab-addons\bundles\org.openhab.binding.russound\.vscode\tasks.json`)
|
||||
|
||||
|
||||
|
||||
|
|
@ -55,7 +55,7 @@ The following steps will show you how to setup a specific bundle for development
|
|||
7. Start the openHAB instance with the debug option - `start.bat debug` from a console in the openHAB home directory. You should see the following line printed somewhere in the karaf console:
|
||||
`Listening for transport dt_socket at address: xxxx` (where xxxx should be 5005)
|
||||
|
||||
8. Download [launch.json](https://raw.githubusercontent.com/openhab/openhab-docs/master/developers/ide/examples/vscode/launch.json) to the .vscode directory (example: `%BASE%\openhab2-addons\bundles\org.openhab.binding.russound\.vscode\launch.json`)
|
||||
8. Download [launch.json](https://raw.githubusercontent.com/openhab/openhab-docs/master/developers/ide/examples/vscode/launch.json) to the .vscode directory (example: `%BASE%\openhab-addons\bundles\org.openhab.binding.russound\.vscode\launch.json`)
|
||||
|
||||
|
||||
|
||||
|
|
@ -83,7 +83,7 @@ You can now make changes, set breakpoints, etc.
|
|||
|
||||
1. May take openHAB a few seconds to realize there is a new bundle and to reinitilize it after it's been copied. Be a little bit patient.
|
||||
2. You must run the `mvn Compile (Online)` task atleast once to allow the offline compile to occur. You should use the `mvn Compile (Offline)` task for most of your development as it's quicker since it uses the cache files. When you are ready to commit (or release a test bundle) - you should run the `mvn Compile (Release)` task to include code checks (and resolve them).
|
||||
3. Win10+ allows forward slashes as part of it's path. If you use backward slashes instead - you will need to double up on them since tasks.json uses a backward slash as a delimiter. Example: `c:\\\\openhab2`
|
||||
3. Win10+ allows forward slashes as part of it's path. If you use backward slashes instead - you will need to double up on them since tasks.json uses a backward slash as a delimiter. Example: `c:\\\\openhab`
|
||||
|
||||
## Tasks
|
||||
|
||||
|
|
|
|||
|
|
@ -81,7 +81,7 @@ Not sure what to choose?: openHAB maintainers use [Eclipse IDE](https://wiki.ecl
|
|||
To start developing a new binding a script is available to generate the basis for your new binding.
|
||||
This script is specific for binding addons. Follow these steps to generate your binding:
|
||||
|
||||
1. From the command line in `openhab2-addons/bundles` directory to create a skeleton of a new binding `mynewbinding` run:
|
||||
1. From the command line in `openhab-addons/bundles` directory to create a skeleton of a new binding `mynewbinding` run:
|
||||
|
||||
On Linux:
|
||||
```
|
||||
|
|
@ -97,14 +97,14 @@ This script is specific for binding addons. Follow these steps to generate your
|
|||
|
||||
1. Accept with `Y` when the skeleton configuration asks for it.
|
||||
|
||||
1. From `openhab2-addons` root you can build only your binding with maven using the `-pl` option:
|
||||
1. From `openhab-addons` root you can build only your binding with maven using the `-pl` option:
|
||||
```
|
||||
mvn clean install -pl :org.openhab.binding.mynewbinding
|
||||
```
|
||||
Where `mynewbinding` is the name of your new binding.
|
||||
Some additional maven options that may help:
|
||||
* `-U`: Forces all dependencies to be downloaded again.
|
||||
* `-am`: Builds all projects in openhab2-addons your project dependends on.
|
||||
* `-am`: Builds all projects in openhab-addons your project dependends on.
|
||||
* `-o`: Won't update any dependencies.
|
||||
* `-DskipChecks`: Skips the static analysis checks
|
||||
* `-DskipTests`: Skips the unit tests
|
||||
|
|
|
|||
|
|
@ -26,7 +26,7 @@ Test a not included add-on is very straight forward:
|
|||
|
||||
All developers are encouraged to help on this in order to quickly make as many 1.x add-ons compatible with the openHAB 2 runtime as possible.
|
||||
Here is what you need to do:
|
||||
- Setup a the [openHAB 2 IDE](../development/ide.html).
|
||||
- Setup a the [openHAB 2 IDE](../#setup-the-development-environment).
|
||||
- Import your 1.x add-on from your local openHAB 1 git clone into your workspace.
|
||||
- If it compiles, the first major step is already done. If not, try to figure out why there are compilation problems and if you cannot solve them, ask on the mailing list for help.
|
||||
- After adding some configuration, start up the runtime through the launch configuration (make sure your bundle is activated and started by default) from within the IDE.
|
||||
|
|
|
|||
|
|
@ -1,91 +0,0 @@
|
|||
---
|
||||
layout: developersguide
|
||||
title: IDE setup
|
||||
---
|
||||
|
||||
{% include base.html %}
|
||||
|
||||
# Setting up an IDE for openHAB
|
||||
|
||||
If you are a developer yourself, you might want to setup a development environment, so that you can debug and develop openHAB yourself.
|
||||
|
||||
Note that the project build is completely mavenized - so running "mvn install" on any repository root will nicely build all artifacts. For development and debugging, we recommend using an Eclipse IDE though. It should be possible to use other IDEs (e.g. NetBeans or IntelliJ), but you will have to work out how to resolve OSGi dependencies etc. yourself. So unless you have a strong reason to go for another IDE, we recommend using Eclipse.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Please ensure that you have the following prerequisites installed on your machine:
|
||||
|
||||
1. [Git](https://git-scm.com/downloads)
|
||||
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)
|
||||
|
||||
## 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:
|
||||
|
||||
1. Download the [Eclipse Installer](https://wiki.eclipse.org/Eclipse_Installer)
|
||||
2. Launch the Eclipse Installer and switch to "Advanced Mode" in the top right menu:
|
||||
|
||||
3. Choose the "Eclipse IDE for Java Developers" and select "Next":
|
||||
|
||||
4. Expand "Github Projects", then "openHAB".
|
||||
|
||||
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.
|
||||
|
||||
### Option 1: Installation of IDE for Add-on Development
|
||||
|
||||
[](http://github.com/badges/stability-badges)
|
||||
|
||||
Warning: The following step by step guide is only for the old build-system.
|
||||
* **A binding created via this old way will not be accepted in the official openhab2-addons repository!**
|
||||
* The migration to the new build-system is a work in progress. Migrated bindings will not be accessible in the IDE.
|
||||
* We are working on a new step by step guide after the migration is done. Watch [Issue 5005](https://github.com/openhab/openhab2-addons/issues/5005) for further information and progress.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
### Option 2: Installation of IDE for Core Development
|
||||
|
||||
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).
|
||||
|
||||
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.
|
||||
|
||||
### Start Coding & Contributing
|
||||
|
||||
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.
|
||||
|
||||
## Refreshing the IDE
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 83 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 33 KiB |
|
|
@ -1,103 +0,0 @@
|
|||
---
|
||||
layout: developersguide
|
||||
title: Target platform
|
||||
---
|
||||
|
||||
{% include base.html %}
|
||||
|
||||
Target platform
|
||||
=====
|
||||
|
||||
## Introduction
|
||||
|
||||
The *Target Platform* is a collection of plug-ins which your workspace will be built and run against. It describes the platform that you are developing for. It can be used from [Tycho Maven plugins](tycho.html) as well.
|
||||
|
||||
## Target Definition
|
||||
|
||||
*Target platform* can be defined in a *target definition* file. *Target Definition is a way of determining the plug-ins to add to the state. You can have multiple target definitions, but only one definition can be selected as the target platform.* (Source: [Eclipse documentation][target-platform]).
|
||||
|
||||
Target definitions are stored in a file with the extension `.target`. The openHAB target platform definition looks like this (it will be most probably changed when you read this article - for the latest version check in the [openhad-distro](https://github.com/openhab/openhab-distro/blob/master/launch/openhab.target)):
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
|
||||
<?pde version="3.8"?>
|
||||
<target name="openHAB Target Platform" sequenceNumber="156">
|
||||
<locations>
|
||||
<location includeAllPlatforms="false" includeConfigurePhase="false" includeMode="planner" includeSource="true" type="InstallableUnit">
|
||||
<unit id="org.eclipse.smarthome.feature.runtime.core.feature.group" version="0.0.0"/>
|
||||
<unit id="org.eclipse.smarthome.feature.runtime.binding.feature.group" version="0.0.0"/>
|
||||
<unit id="org.eclipse.smarthome.feature.runtime.console.equinox.feature.group" version="0.0.0"/>
|
||||
<unit id="org.eclipse.smarthome.feature.runtime.rest.feature.group" version="0.0.0"/>
|
||||
<unit id="org.eclipse.smarthome.feature.test.feature.group" version="0.0.0"/>
|
||||
<repository location="http://download.eclipse.org/smarthome/updates-stable/"/>
|
||||
</location>
|
||||
<location includeAllPlatforms="false" includeConfigurePhase="true" includeMode="planner" includeSource="true" type="InstallableUnit">
|
||||
<unit id="org.eclipse.equinox.sdk.feature.group" version="3.10.2.v20150204-1316"/>
|
||||
<repository location="http://download.eclipse.org/releases/luna/201502271000"/>
|
||||
</location>
|
||||
<location includeAllPlatforms="false" includeConfigurePhase="false" includeMode="planner" includeSource="true" type="InstallableUnit">
|
||||
<unit id="org.openhab.feature.p2.feature.group" version="0.0.0"/>
|
||||
<repository location="https://dl.bintray.com/openhab/p2/openhab-core/2.0.0.x"/>
|
||||
</location>
|
||||
<location includeAllPlatforms="false" includeConfigurePhase="true" includeMode="planner" includeSource="true" type="InstallableUnit">
|
||||
<unit id="org.openhab.deps.runtime.feature.group" version="0.0.0"/>
|
||||
<unit id="org.openhab.deps.test.feature.group" version="0.0.0"/>
|
||||
<repository location="https://dl.bintray.com/openhab/p2/openhab-deps-repo/1.0.6"/>
|
||||
</location>
|
||||
<location includeAllPlatforms="false" includeConfigurePhase="false" includeMode="planner" includeSource="true" type="InstallableUnit">
|
||||
<unit id="net.minidev.asm" version="1.0.2"/>
|
||||
<unit id="com.jayway.jsonpath.json-path" version="2.0.0"/>
|
||||
<unit id="org.mapdb.mapdb" version="1.0.9"/>
|
||||
<unit id="net.minidev.json-smart" version="2.1.1"/>
|
||||
<repository location="http://eclipse.github.io/smarthome/third-party/target/repository"/>
|
||||
</location>
|
||||
</locations>
|
||||
</target>
|
||||
```
|
||||
|
||||
This file lists the different repositories (or also "update sites"), where the plug-ins are stored, and artifacts ("installable units"). To find more about update sites and installable units, take a look at the [p2 short overview](equinox.html#vi-p2).
|
||||
|
||||
## openHAB target platform
|
||||
|
||||
The `openHAB target platform` definition file is located in the [openhad-distro](https://github.com/openhab/openhab-distro/blob/master/launch/openhab.target) repository. It contains all the external dependencies that are needed from the openHAB bundles.
|
||||
|
||||
## Target Platform Editor in Eclipse IDE
|
||||
|
||||
Eclipse has a graphical interface for working with the target platform. It is located in the `Window` -> `Preferences` -> `Plug-in Development` -> `Target Platform`(See Fig.1).
|
||||
|
||||
### Selecting
|
||||
|
||||
Depending on the repositories that you have selected in the installation process, you might have many options in this window. For openHAB development choose `openHAB Target Platform`. Make sure that it is checked and that it is "Active".
|
||||
|
||||
Hint! If for some reason the target platform that you want to use is missing from this list, the easiest way to add it is to close this window and simply drag and drop the target definition file into Eclipse. In the top right corner you will see a button `Set as current target platform`.
|
||||
|
||||
### Reloading
|
||||
|
||||
During the development process, some projects might fail to build. There could be several possible problems in this case, two of them are related with the target platform:
|
||||
|
||||
- you have updated your plugins repository, but you have not updated the target platform in Eclipse (or the openhab-distro repository). The updated versions of the bundles require new dependencies that are not present in the current target platform that you are using;
|
||||
- your last update of the target platform in Eclipse has failed. In this case the content of the target platform may not be complete.
|
||||
|
||||
In both cases the first thing to do is to check, if there are any problems with the target platform. Open the `Target Platform` window (See Fig.1). If you see a red cross in front of the `openHAB Target Platform` select it and click on `Edit`(Fig.2). A new window will pop up and Eclipse will try to connect to all repositories listed in the target definition file. If some of the plug-ins are not downloaded, it will download all missing bundles. This may take some minutes, so be patient. After the process has finished, if no problems were found, you can click on `Finish`.
|
||||
|
||||
You go back to the previous window and don't forget to to click on `Reload`. After you save your actions with `OK` or `Apply`, Eclipse will try to rebuild all the projects in your workspace.
|
||||
|
||||
### Editing
|
||||
|
||||
You may wonder, why you have to edit the content of the target platform. If you are developing new binding, that requires a library that is not included in the target platform and you want to setup a quick test, it might be easier to add a folder with the required `.jar` file to your target platform.
|
||||
|
||||
You can edit the target definition file with any text editor that you want, but you might find it easier to edit the content of the target platform from the Eclipse UI. In order to do that, you have to:
|
||||
|
||||
- open the `Target Platform` dialog window (see Fig.1);
|
||||
- click on `Edit`(see Fig.2);
|
||||
- in the `Locations` tab select `Add..`;
|
||||
- Select `Folder` and follow the wizard.
|
||||
|
||||
|
||||
## Further Reading
|
||||
|
||||
- <http://www.vogella.com/tutorials/EclipseTargetPlatform/article.html>
|
||||
- <https://wiki.eclipse.org/PDE/Target_Definitions>
|
||||
- <http://help.eclipse.org/neon/index.jsp?topic=%2Forg.eclipse.pde.doc.user%2Fconcepts%2Ftarget.htm>
|
||||
|
||||
[target-platform]: http://help.eclipse.org/mars/index.jsp?topic=%2Forg.eclipse.pde.doc.user%2Fconcepts%2Ftarget.htm
|
||||
|
|
@ -1,133 +0,0 @@
|
|||
---
|
||||
layout: developersguide
|
||||
title: Tycho
|
||||
---
|
||||
|
||||
{% include base.html %}
|
||||
|
||||
Tycho
|
||||
=====
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
[Tycho][Tycho] *is a set of [Maven][Maven] plugins and extensions for building Eclipse plugins and OSGi bundles with Maven* as it is described in the [Tycho project homepage][Tycho-home]. Tycho uses the Eclipse components metadata as much as possible (e.g. for plug-ins and bundles it determines the dependencies via the ```MANIFEST.MF```file).
|
||||
|
||||
Integrate your bundle with the Tycho build
|
||||
------------------------------------------
|
||||
openHAB project is building the bundles with Tycho, so knowledge about how is Tycho functioning can help you to integrate your work with the build.
|
||||
|
||||
Let's take a look at the pom.xml that is automatically generated, when you create a binding using the [binding skeleton](../development/bindings.html#creating-a-skeleton):
|
||||
|
||||
```xml
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://maven.apache.org/POM/4.0.0" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
|
||||
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
||||
<parent>
|
||||
<groupId>org.openhab.binding</groupId>
|
||||
<artifactId>pom</artifactId>
|
||||
<version>2.0.0-SNAPSHOT</version>
|
||||
</parent>
|
||||
|
||||
<groupId>org.openhab.binding</groupId>
|
||||
<artifactId>org.openhab.binding.mybinding</artifactId>
|
||||
<version>2.0.0-SNAPSHOT</version>
|
||||
|
||||
<name>MyBidning Binding</name>
|
||||
<packaging>eclipse-plugin</packaging>
|
||||
|
||||
</project>
|
||||
```
|
||||
The generated pom file has done almost everything that is needed to integrate your new binding. We will use it as example to show several Tycho requirements in order to build your bundle:
|
||||
|
||||
- the `artifactId` in the pom file must match the `Bundle-Sumbolic-Name` from the `MANIFEST.MF` file;
|
||||
- the `version` in the pom file must match the `Bundle-Version` from the `MANIFEST.MF` (Eclipse components use `qualifier` as a suffix, Maven uses `SNAPSHOT`, but Tycho maps these values correctly);
|
||||
- include a `packaging` attribute in the pom file. In this example the packaging type is set to `eclipse-plugin` in the pom.xml file. For more information about the packing types that Tycho understands follow the [link](https://wiki.eclipse.org/Tycho/Packaging_Types).
|
||||
|
||||
Notice that is also important to have a "link" between the pom file in your bundle and the parent pom (the `parent` element).
|
||||
|
||||
Only one thing must be done more in order to have your bundle included in the openHAB build. You will have to add your binding as a module to the parent pom as well.
|
||||
|
||||
Configure Tycho
|
||||
---------------------------
|
||||
|
||||
A Tycho build is configured via the standard Maven configuration files - the pom.xml files.
|
||||
|
||||
The openHAB project is divided into modules. In the pom, located in the root of the repository, there is a configuration of the Tycho plugins, that will be used from all modules. We will just mention a few settings that are applied there:
|
||||
|
||||
- Repositories are defined. This will be the place, where Tycho will search for dependencies;
|
||||
- Compiler is selected.
|
||||
|
||||
If you are developing a new binding, you might want to override these settings or add a new confugiration for some of the Tycho plug-ins. A case when you have to configure Tycho individually for a project is when you want to implement a test plugin. Test plugins are executed with the [tycho-surefire-plugin](https://eclipse.org/tycho/sitedocs/tycho-surefire/tycho-surefire-plugin/test-mojo.html). You can find more information, how to implement a test plugin and configure the `tycho-surefire-plugin` in the [Eclipse SmartHome documentation](http://www.eclipse.org/smarthome/documentation/development/testing.html).
|
||||
|
||||
Executing a Tycho build
|
||||
-----------------------
|
||||
|
||||
You can check if all dependencies are resolved with:
|
||||
|
||||
`mvn clean verify`
|
||||
|
||||
Tycho build is executed just like a standard Maven build. You can use:
|
||||
|
||||
`mvn clean install`
|
||||
|
||||
You can execute tests with:
|
||||
|
||||
`mvn clean integration-test`
|
||||
|
||||
Tests are executed in a test runtime (based on [OSGi](osgi.html)).
|
||||
|
||||
Target platform
|
||||
----------------
|
||||
|
||||
[Target platform](targetplatform.html) is the set of plug-ins which you can use for your development or your build process to resolve the project dependencies.
|
||||
|
||||
If you are using a [target definition file](targetplatform.html#target-definition), the file should contain only "Software site" locations (i.e. *location* elements with *type="InstallableUnit"*).
|
||||
|
||||
When you execute the build, the bundles that are available (can be used as dependencies) form the **effective content of the target platform**. It consists of the following plug-ins:
|
||||
|
||||
- all plug-ins included in the target platform with the Tycho configuration (the configuration is done in the pom files). Multiple approaches exist here, for more details, you can take a look in the [Tycho Target platform documentation](https://wiki.eclipse.org/Tycho/Target_Platform#Which_approach_shall_I_use_for_the_target_platform_of_my_project.3F);
|
||||
- other artifacts from the same reactor (the Maven [reactor](https://maven.apache.org/guides/mini/guide-multiple-modules.html), i.e. everything that is built together in the same `mvn` call);
|
||||
- locally built artifacts in the local Maven repository. Just like in a normal Maven build, a Tycho build uses artifacts that have been built locally and installed into the local Maven repository. They are implicitly added to the target platform.
|
||||
|
||||
Dependency resolution troubleshooting
|
||||
-------------------------------------
|
||||
|
||||
If you develop a new bundle, you might have dependencies that can not be resolved from Tycho. In case of dependency resolution failure, Tycho will display an error message on the console. The message might be confusing, so we will take a look at one example:
|
||||
|
||||
```
|
||||
[INFO] Resolving dependencies of MavenProject: com.mycorp:com.mycorp.myplugin:0.1.0-SNAPSHOT @ C:\Source\MyProject\com.mycorp.myplugin\pom.xml
|
||||
[INFO] {osgi.ws=win32, osgi.os=win32, osgi.arch=x86_64, org.eclipse.update.install.features=true}
|
||||
[ERROR] Cannot resolve project dependencies:
|
||||
[ERROR] Software being installed: com.mycorp.myplugin 0.1.0.qualifier
|
||||
[ERROR] Missing requirement: com.mycorp.mylib 0.1.0.qualifier requires 'package org.eclipse.someproject [1.8.2,2.0.0)' but it could not be found
|
||||
[ERROR] Cannot satisfy dependency: com.mycorp.myplugin 0.1.0.qualifier depends on: bundle com.mycorp.mylib 0.0.0
|
||||
```
|
||||
Source: <https://wiki.eclipse.org/Tycho/Dependency_Resolution_Troubleshooting>
|
||||
|
||||
This error message means that a mandatory dependency of the project can not be resolved. This can be either direct or transitive dependency. In case it is transitive you will see one or more rows like (`Cannot satisfy dependency: [artifact] depends on: [dependency]`), which will track the dependencies chain. Important is to note which package (in case of package dependency) or bundle(for plugin dependency) is missing. In this case this is the package `org.eclipse.someproject` with version range [1.8.2,2.0.0).
|
||||
|
||||
For more detailed explanation of the error message take a look at - <https://wiki.eclipse.org/Tycho/Dependency_Resolution_Troubleshooting>.
|
||||
|
||||
In order to debug Tycho resolution problems run **mvn** with the flags
|
||||
**-Dtycho.debug.resolver=true** and **-X**.
|
||||
|
||||
This will display all the bundles that are available in the target platform for this module. In the displayed list you can search, if the required bundle has a mismatching version or it is missing at all.
|
||||
|
||||
In order to resolve the problem, you will have to include the bundle that is exporting the missing package (or the required bundle) to the effective content of the target platform.
|
||||
|
||||
Further Reading
|
||||
----------
|
||||
- <https://wiki.eclipse.org/Tycho/Target_Platform>
|
||||
- <https://wiki.eclipse.org/Tycho/Packaging_Types>
|
||||
- <https://github.com/FTSRG/cheat-sheets/wiki/Maven-and-Eclipse#tycho>
|
||||
- <http://www.vogella.com/tutorials/EclipseTycho/article.html>
|
||||
- <http://www.vogella.com/tutorials/EclipseTargetPlatform/article.html>
|
||||
- <https://wiki.eclipse.org/PDE/Target_Definitions>
|
||||
|
||||
[target-platform]: http://help.eclipse.org/mars/index.jsp?topic=%2Forg.eclipse.pde.doc.user%2Fconcepts%2Ftarget.htm
|
||||
[Tycho]: https://eclipse.org/tycho/sitedocs/index.html
|
||||
[Maven]: https://maven.apache.org/
|
||||
[Tycho-home]: https://eclipse.org/tycho/
|
||||
Loading…
Reference in New Issue