View source for Kura/Getting Started

=Prerequisites=
Before installing Kura, you need to have the following programs installed in your OS. (note: The local emulation mode will only work on the Linux or MAC OS X operating system.)

==Java==
*Install Java JDK 1.8 from Oracle [http://www.oracle.com/technetwork/java/javase/downloads/index.html here].
*Set the JAVA_HOME environment variable to the installation directory for the JDK.
*Add JAVA_HOME/bin to your system PATH.
*Verify Java installation by running: java -version

==Maven==
*Install Maven version 3.3.x from [http://maven.apache.org here].
**Note: You ''must'' use version 3.3.x or greater to have a successful build.
*Set the M2_HOME environment variable to the installation directory for Maven
*Add M2_HOME/bin to your system PATH.
*Verify Maven installation by running: mvn --version

==Eclipse==

=== For the Eclipse Installer based setup ===

* Download and install the most recent version of the Eclipse Installer from https://eclipse.org/downloads/

=== For the manual setup ===
*Install latest version of Eclipse for Java EE Developers from [https://www.eclipse.org/downloads/ here].
*Install maven plugin for eclipse (m2e) using Eclipse's "Install New Software..." dialog
*Install Tycho connector for m2e maven plugin by following: http://www.sebastianbauer.info/index.php?page=tutorials&which=justify
**NOTE: Maven connector plugin installer breaks on JDK 1.7.0_40. Downgrade the JDK used by Eclipse to a lower version, install the Tycho connector for m2e and then move up the JRE used by Eclipse again.

=Building=

== All on one ==

It is possible to build all Kura project with a single build step:
<pre>
$ git clone -b develop https://github.com/eclipse/kura.git kura.git
$ cd kura.git
$ ./build-all.sh
</pre>

== Single step build ==
*Create a git directory for your cloned repository (ex: mkdir ~/git).
**The remainder of this document will assume ~/git to be the source code directory.
*Change to the new directory and clone the repo
<pre>git clone -b develop https://github.com/eclipse/kura.git</pre>
*Build the target platform
<pre>
cd ~/git/kura/target-platform
mvn clean install
</pre>
*Build the core components
<pre>
cd ../kura
#Build with CAN support
mvn -Dmaven.test.skip=true -f pom.xml -Pcan clean install
#Build without CAN support
mvn -Dmaven.test.skip=true -f pom.xml clean install
</pre>
*Prepare the for the Eclipse workspace
<pre>
mvn -f manifest_pom.xml eclipse:clean && mvn -f manifest_pom.xml eclipse:eclipse
mvn -f pom_pom.xml eclipse:clean && mvn -f pom_pom.xml eclipse:eclipse
</pre>
*If mvn clean install fails in kura (unexpected element (uri:"", local:"snapshot-store")), try to delete /tmp/snapshot-store.xml
*If mvn clean install fails in test compilation run it with "-Dmaven.test.skip=true" option.

==Potential Build Errors==
*If the build fails with the following message:
<pre>
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-antrun-plugin:1.7:run (raspberry-pi-jars) on
project distrib: An Ant BuildException has occured: The following error occurred while executing this line:
[ERROR] ~/kura/kura/distrib/src/main/ant/build_equinox_distrib.xml:296: Execute failed: java.io.IOException: Cannot run program "~/kura/kura/distrib/target/../src/main/sh/create_installer.sh" (in directory "~/kura/kura/distrib"): error=2, No such file or directory</pre>

Then check line endings of the shell script with:

<pre>
$ file ~/kura/kura/distrib/src/main/sh/create_installer.sh
~/kura/kura/distrib/src/main/sh/create_installer.sh: POSIX shell script, ASCII text executable, with CRLF line terminators</pre>

It should not show 'CRLF line terminators'. If it does, see this StackOverflow question for a fix.

* If you get a "peer not authenticated" error when attempting to download artifacts from Github, try following these steps:
** https://www.liferay.com/web/neil.griffin/blog/-/blogs/fixing-suncertpathbuilderexception-caused-by-maven-downloading-from-self-signed-repository
** http://www.xinotes.net/notes/note/1685/

=Configure Eclipse=

== For the Eclipse Installer based setup ==

* Start the Eclipse Installer
* Switch to advanced mode (in simple mode you cannot add the custom installer)
* Select "Eclipse for Committers" and select a JRE 1.8+ -> Next
* Add a new installer by URL: https://raw.githubusercontent.com/eclipse/kura/develop/kura/setups/kura.setup -> Check and next
* Update Eclipse Kura Git repository's username and customize further settings if you like (e.g. Root install folder, Installation folder name) -> Next
: Note that the 'user' Developer Type is under development and cannot run Kura emulator with GUI support, yet.
* Leave all Bootstrap Tasks selected -> Finish
* Accept the licenses
* Wait for the installation to finish
* At first startup Eclipse IDE will checkout the code and perform a full build
* A few Working Sets will be prepared

== For the manual setup ==

*Eclipse Juno or newer required
*Set perspective to Java (not Java EE)
*Install Maven 2 Eclipse (m2e) if it's not already installed
**Help | Install New Software | Add
**Then enter this URL: http://download.eclipse.org/releases/juno (or the Eclipse release that you have installed - Kepler should have m2e installed by default)
**You will find m2e under the 'General Purpose Tools' section of the Eclipse Installer
*Install eGit (via the same URL under the Collaboration section, or "Java implementation of Git")
*Restart Eclipse
*In Eclipse select import and under Maven, select 'Existing Maven Projects'
**Browse to kura/kura in your git repository, and select all projects
**If prompted, go ahead and install Tycho Project Configurators (Eclipse will need to restart)
*Link all projects to the git repository:
**Select all projects
**Right-click and select Team > Share Project > Git
*Expand the target-definition project and open the 'kura-equinox_3.8.1.target' file. Click 'Set as Target Platform' in the upper right area of the center pane. Alternatively, or if this doesn't work, browse to Windows | Preferences | Plug-in Development | Target Platform. Then select Kura Target Platform Equinox 3.8.1 and click the Reload button.
*After setting this and letting Eclipse rebuild - there should be no errors in the workspace
*It may happen that you still have errors stating that some Projects are not up to date. In this case right click on the corresponding Projetcs, then Maven > Update Project
*If you have remaining errors
**'distrib': open its pom.xml and choose the quick fix to permanently mark the goal as ignored. Right-click on project and select Maven > Update Project.
**'org.eclipse.kura.web'
***Ensure the web profile was included in the Maven build command (-Pweb)
***Right-click on project and select Properties. Select Java Build Path, click the Source tab, and click Add Folder. Browse to target/generated-sources and click the box next to gwt.
***In some instances the project may need to be deleted from the Eclipse workspace and re-imported.
**'org.eclipse.kura.protocol.can'
***Ensure the can profile was included in the Maven build command (-Pcan)

=Emulator=

# Right-click the Kura_Emulator_[OS].launch file (in src/main/resources of the org.eclipse.kura.emulator project), and doing a 'Run as OSGi Framework'. This will result in errors, because by default this runs all tooling target platform bundles as well as the 'real' target platform bundles.
# After running once, you can go to 'Run Configurations' and reduce the bundle set that is running.
## The easiest way to do this is right-click on the Kura_Emulator_[OS].launch file and select Run As > Run Configurations.
## Click the 'Deselect All' button to deselect all bundles, and just check the Kura bundles in the workspace, excluding all the *.test bundles. Then click 'Add required bundles' to add all of the dependencies to the runtime configuration.
## Click the Apply button, and the Run button. This should start an error free OSGi/Kura runtime in the console without errors. You can type 'ss' to see the running components.

In case the JVM cannot find/load the native libraries try passing the java.library.path to the VM:

# Right click on the Kura_Emulator_Linux.launch,
# select Run As | Run Configurations,
# select the Arguments tab and add the system property to the VM Arguments. For example for a 64 bit Linux add:<pre>-Djava.library.path=${workspace_loc}/kura/kura/org.eclipse.kura.linux/lib/linux/x86/linux64</pre>

=Testing=
You can execute tests within Eclipse by right clicking any *.test bundle and going to run as 'Junit Plug-in Test'. This will execute all tests within that bundle. These are also automatically run during the maven integration-test phase during command line builds.

=Running on a target device=
==Raspberry-Pi==
Click [[Kura/Raspberry_Pi | here]] for information on running Kura on the Raspberry Pi.

==BeagleBone==
Click [[Kura/BeagleBone | here]] for information on running Kura on the BeagleBone.

==General==
===Deploy and Run===
*Make sure a Java VM is installed on the target device
*After a clean install, archives for supported devices can be found in the kura/kura/distrib/target directory. The archives are of the format "kura-[target-device]_2.0.0-SNAPSHOT.zip" (e.g. "kura-raspberry-pi_2.0.0-SNAPSHOT.zip").
*If it does not exist, create an /opt/eclipse directory on the target device. Copy the appropriate archive to the /opt/eclipse directory and extract the contents of the ZIP file.
*To start Kura, execute the script located in the newly extracted directory: /opt/eclipse/kura-[device name]_1.0.0-SNAPSHOT/bin/start_kura_background.sh
*A log of Kura activity is stored in /var/log/kura.log. Kura activity can be continuously monitored by issuing the command:
<pre>tail -f /var/log/kura.log</pre>

=Stopping Kura=
To stop Kura from the command line, issue the command:
<pre>killall java hostapd named dhcpd</pre>

=Reinstalling Kura=
*To completely reinstall Kura, issue the following commands:
<pre>
  rm -fr /opt/eclipse/kura*
  rm -fr /tmp/.kura/
  rm /etc/init.d/firewall
  rm /etc/dhcpd-*.conf
  rm /etc/named.conf
  rm /etc/wpa_supplicant.conf
  rm /etc/hostapd.conf
  rm /tmp/coninfo-*
  rm /var/log/kura.log
  killall java hostapd named dhcpd
</pre>
*Then extract the new ZIP file and start Kura.

=Control Kura through OSGi=
*Connect to the OSGi console by issuing the below command on the target device:
<pre>telnet 127.0.0.1 5002</pre>
*While in the console, to exit the OSGi console but leave Kura running, issue the command "disconnect"
*While in the console, to exit the OSGi console and stop Kura, issue the command "exit"

=Google Web Toolkit=
You need the Google Web Toolkit 2.4.0 which is not available for Eclipse Juno from the update site. If you are lucky you might have installed the version 2.4.0 for Eclipse Indigo. In this case browse to Window | Preferences | Google | Web Toolkit. Select Use specific SDK and browse to the install location, for example .eclipse/org.eclipse.platform_3.7.0_1011460474/plugins/com.google.gwt.eclipse.sdkbundle_2.4.0.v201206290132-rel-r37/gwt-2.4.0/ in your home directory.

==Debugging==

*To get more useful log messages and errors when running GWT on a remote device, you can have it connect to a development code server, which can be launched from Eclipse. With this setup, it will display source files, line numbers, and stack traces in the GWT log.
*Deploy and launch Kura on the target device.
**In Eclipse on your local machine, right-click on the org.eclipse.kura.web project, select "Run As" > "Run Configurations...". Select "Web Application" and click the "New launch configuration" button.
**Select the "Server" tab and ensure "Run built-in server" is NOT checked.
**Select the "GWT" tab. In the "URL" box, enter the url for the remote device (e.g. "http://192.168.1.123/kura"), then click "Apply". Then click "Run".
**Once it launches, it will give you a url (e.g. "http://192.168.1.123/kura?gwt.codesvr=127.0.0.1:9997").
**Open this url in a browser, and it should connect to the development code server.
***Note that the first time you open the url in a browser, it may prompt you to install the GWT Developer Plugin - go ahead and do this.
*If you get a blank page logging in to the web UI at http://localhost:8080/kura, right click on the web project then select Google and GWT Compile.