Skip to main content
Jump to: navigation, search

Difference between revisions of "SMILA/Documentation/HowTo/Howto set up dev environment"

(Building SMILA from command line)
(Using the target platform provided by SMILA)
 
(166 intermediate revisions by 12 users not shown)
Line 1: Line 1:
== Howto set up dev environment ==
+
<br> This HowTo describes the necessary steps for setting up a SMILA development environment.
  
=== dev env ===
+
=== Preconditions  ===
  
* ref: [[SMILA/Development Guidelines|Development Guidelines]]
+
Here is the list of things that you will definitely need for developing SMILA components:  
* https://svn.brox.de/svn/eccenca/EILF/trunk/SMILA.builder/
+
* eclipse 3.3
+
*:  plugins needed:
+
*: - extension location to WC \EILF.extension
+
  
=== Howto build and test locally ===
+
* JDK 1.7 (Java 8 is not yet supported by SMILA).
 +
* Eclipse SDK - This HowTo was tested with [http://download.eclipse.org/eclipse/downloads/drops4/R-4.4.2-201502041700/ Eclipse Classic SDK 4.4.2] (Luna SR2 Release) <br>
  
==== Setup an Eclipse instance/installation for building ====
+
=== Getting the source code ===
  
Setting up an own instance is recommended so that no extensions/features u might have installed in ur eclipse instance u use for developing interferes with the build. It probably also makes the build a little faster as the headless start of eclipse takes less time due to fewer plug-ins installed.
+
There is more than one way of getting the code into your Eclipse workspace. The following sections will describe how to get the source code from the Git repository (recommended!).  
  
# Download an eclipse SDK, starting with at least [http://archive.eclipse.org/eclipse/downloads/drops/R-3.3.2-200802211800/download.php?dropFile=eclipse-SDK-3.3.2-win32.zip eclipse-SDK-3.3.2-win32.zip]
+
As an alternative, you could download the complete source code from the [http://www.eclipse.org/smila/downloads.php release download page] or the [http://build.eclipse.org/rt/smila/nightly/ nightly build downloads] and unpack the archive into your workspace.  
# download [http://archive.eclipse.org/eclipse/downloads/drops/R-3.3.2-200802211800/download.php?dropFile=eclipse-RCP-3.3.2-delta-pack.zip eclipse-RCP-3.3.2-delta-pack.zip] from [http://archive.eclipse.org/eclipse/downloads/drops/R-3.3.2-200802211800/index.php]
+
# unzip the archive and copy '''org.eclipse.equinox.executable_<version>''' from features into your features folder under your eclipse installation.
+
# start that eclipse and add sole extension location to WC /SMILA.extension by:
+
## Menu: Help / Software Updates / Manage configuration
+
## add extension location and choose the folder SMILA.extension/eclipse from smila project folder
+
  
==== Configuring the Build ====
+
==== Installing Git Provider ====
The folder <tt>SMILA.builder</tt> contains everything needed to build SMILA and/or run all tests locally.
+
  
Whether u build from command line or from eclipse, in both cases the <tt>make.xml</tt> ant script is executed. Before execution certain properties need to be set to meet the local setup.
+
''(skip this section if Git Team Provider is already installed in your Eclipse IDE - most current Eclipse Packages do contain it)''
  
===== Setting the Target Build Platform =====
+
* Install ''Eclipse Git Team Provider'' and ''Java Implementaton of Git'' from the Eclipse software repository.
 +
* Restart Eclipse.
  
Independent of which way you are going to build, in both cases you must set the <tt>configs</tt> property in  the <tt>build.properties</tt> file to you setup.
+
==== Get source code from Git ====
  
{|
+
* Open the "Git" perspective
! Windows
+
* Select "Clone a Git repository"
| {{Codeblock|<pre>...
+
* Enter one of the following URIs for read-only access:
configs=win32,win32,x86
+
** <tt>git://git.eclipse.org/gitroot/smila/org.eclipse.smila.core.git</tt>
# ... </pre>
+
** <tt>http://git.eclipse.org/gitroot/smila/org.eclipse.smila.core.git</tt>
}}
+
(** Committers: use <tt>ssh://git.eclipse.org/gitroot/smila/org.eclipse.smila.core.git</tt> for read-write access and enter your credentials below)
|+
+
* Click "Next". In the following dialog ensure that branch "master" and other branches you need are selected (there are no other branches at the time of writing ;-)
! Linux
+
* Enter the desired location of your clone of the Git repository. You can put this into your current workspace, but this is not necessary.
| {{Codeblock|<pre>...
+
** You can activate the "Import all existing projects after clone finishes" now to import ALL projects, or you can manually import them afterwards to be a bit more selective.
configs=linux,gtk,x86
+
* Click "Finish". The Git repository will be cloned now. This will probably take a few minutes.
# ... </pre>
+
* Switch to the "Plug-in Development" perspective.
}}
+
* To import the projects into the workspace (if not done automatically):
|}
+
** Open "File" -> "Import ..." and select "Git"/"Projects from Git". Click "Next" and select "Existing local repository". Click "Next" and select "org.eclipse.smila.core - ...". Click "Next".
''Note:
+
** Select "Import existing projects" and "core" in the tree below, and click "Next". Make sure all projects are selected and click "Finish".
:The default is to build for both, windows and linux platforms. However, for this to work locally the eclipse must have the corresponding plugins installed which is usually not the case if you downloaded a platform specific distribution. If platform plugins are missing you will end up on Windows with:
+
* After a while a "Problem occurred" dialog will open and there will be lots of compile errors. This is OK, we will fix this now.
  
:<tt>...
 
:[java] D:\Program Files\eclipse33\eclipse-SDK-3.3.2-win32-smila-build\eclipse\plugins\org.eclipse.pde.build_3.3.2.v20071019\scripts\genericTargets.xml:85: Unable to find plug-in: org.eclipse.core.filesystem.linux.x86_0.0.0. Please check the error log for more details.</tt>
 
  
===== Setting Build Properties =====
+
=== Defining the target platform  ===
  
{| border="1" style="font-family:Tahoma, Verdana, Helvetica, sans-serif;font-size:100%;border-color:#CCC;border-collapse:collapse;color:black;" cellspacing="0" cellpadding="5" valign=top
+
The target platform defines the set of bundles and features that you are developing against. SMILA ships a ''Target Definition File'' that you can open in your IDE to configure the target platform automatically. This file contains all the references needed for developing SMILA with Eclipse Luna SR2 (Release 4.4.2).
! Property !! Default !! Comment
+
|-
+
|buildDirectory || <SMILA_HOME>/eclipse.build  ||
+
|-
+
|eclipse.home || <ECLIPSE_HOME>  || the location of the eclipse instance used to build smila
+
|-
+
|builder || <SMILA_HOME>/SMILA.builder  ||
+
|-
+
|eclipse.running || true  ||
+
|-
+
|pdeBuildPluginVersion || 3.3.2.v20071019 ||
+
|-
+
|equinoxLauncherPluginVersion || 1.0.1.R33x_v20080118 ||
+
|-
+
|os || win32 || rowspan=3 | these merely control under which platform the test will run. It must be one of the platforms you have build.
+
|-
+
|ws || win32 ||
+
|-
+
|arch || x86 ||
+
|-
+
|test.java.home || <JAVA_HOME> || a java 1.5 SDK instance
+
|}
+
  
 +
==== Using the target platform provided by SMILA ====
  
For the build from eclipse u pass in these values via the command line text box in the launch config on the command line these are set in a shell script.
+
* Import project "SMILA.devenv" from the "releng" directory of your local Git repository (same procedure as for importing the other projects).
 +
* Open the file <tt>SMILA.devenv/SMILA.target</tt> with the ''Target Editor''. <br>Eclipse starts downloading the referenced bundles/features which it tells you by stating "Resolving Target Definition" in its status bar. Be patient, this will take a while. After it has finished, you can click the link "Set as Target Platform" on the top right of the ''Target Definition'' editor. Doing so will cause Eclipse to start re-compiling the sources and all error markers should be gone when finished.
 +
* If you have the Checkstyle Eclipse plugin installed in your IDE, you will still get error messages. See [[SMILA/Development_Guidelines#Checkstyle |Checkstyle configuration]] for instructions on how to fix this.
  
===== Executing make.xml from within eclipse =====
+
==== Defining the target platform manually  ====
# select the SMILA.builder bundle
+
# open External Tools Dialog
+
# create a new ant build configuration or choose your configuration if exists
+
# choose the build file of this bundle, e. g. ${workspace_loc:/SMILA.builder/make.xml}
+
# insert all properties from above into the ''arguments input field (but adapt these to your setup) but prepend each with <tt>-D</tt> so each is passed into <tt>ant</tt> as a property, e.g.
+
#: -DbuildDirectory=D:/eccenca/SMILA/eclipse.build
+
#: -Declipse.home=D:/eclipse33
+
#: -Dbuilder=D:/eccenca/SMILA/SMILA.builder
+
#: -Declipse.running=true
+
#: -DpdeBuildPluginVersion=3.3.2.v20071019
+
#: -DequinoxLauncherPluginVersion=1.0.1.R33x_v20080118
+
#: -Dos=win32 -Dws=win32 -Darch=x86
+
#: -Dtest.java.home=D:/java/jre1.5.0_11
+
# Apply, close and run SMILA.builder with this external tool configuration
+
  
===== Executing make.xml from command line =====
+
* Instead of using the target definition file provided by SMILA (see above) you can also [[SMILA/Development Guidelines/Howto set up target platform|manually set your own target platform]].
  
The make.bat (or .sh) is just a shell script to set the properties that are needed for the ant script.
+
=== Launching SMILA in Eclipse IDE  ===
  
Steps:
+
If you've checked out SMILA's trunk correctly, you should have a project called '''SMILA.launch''' in your workspace. This project contains the SMILA's launch configuration for Eclipse IDE. To start SMILA directly in your Eclipse IDE, just follow the steps below:
# adjust all paths in \SMILA.builder\make.bat according to own setup
+
# execute make.bat
+
  
The whole process takes about 15 minutes at the time of writing, so be patient or get some java-like beverage ;)
+
* Click <span style="font-style: italic;">Run</span>--&gt; ''Debug Configurations'' and expand '''''OSGI Framework'''''<b>.</b>
 +
* Select the ''SMILA'' launch file.
 +
* Click '''Debug'''. <br> If everything works fine, you will get an output in the '''Console''' view similar to the following:
  
=== run junit tests for osgi bundles ===
+
<source lang="text">
* Plugin Junit Launch config
+
osgi> Persistence bundle starting...
* write config.ini and ref it from lauch config.
+
ProviderTracker: New service detected...
*:tip: use \ to brake up long lines to have better overview
+
ProviderTracker: Added service org.eclipse.persistence.jpa.osgi.PersistenceProviderOSGi
* share the launch config
+
Persistence bundle started.
For further information see: [[SMILA/Development Guidelines|Development Guidelines]]
+
[INFO ] Context /zookeeper: Registered handler(1) ZooKeeperAdminHandler, pattern /(.*)$
 +
[INFO ] Added worker webFetcher to WorkerManager.
 +
...
 +
[INFO ] HTTP server has SMILA handler RequestDispatcher for context /smila.
 +
[INFO ] HTTP server started successfully on port 8080.
 +
</source>
 +
 
 +
=== You're done  ===
 +
 
 +
Congratulations! You've just successfully checked out and configured your SMILA development environment and you can now start [[SMILA/Development Guidelines/Create a bundle (plug-in)|developing your own bundles]].
 +
 
 +
=== Additional steps ===
 +
 
 +
The following steps may be needed for special purposes. If you are a SMILA user who only wants to integrate an own component you won't need them.  
 +
 
 +
==== Checkstyle configuration ====
 +
 
 +
If you have the [http://eclipse-cs.sourceforge.net/ Eclipse Checkstyle plugin] installed, you will get a lot of error messages complaining about missing check configurations when Eclipse builds the workspace.
 +
 
 +
<source lang="text">
 +
Errors running builder 'Checkstyle Builder' on project 'org.eclipse.smila.utils'.
 +
Fileset from project "org.eclipse.smila.utils" has no valid check configuration.
 +
...
 +
</source>
 +
 
 +
You can solve this by [[SMILA/Development_Guidelines#Checkstyle|setup your Checkstyle configuration]].
 +
 
 +
==== Setting up the Eclipse build ====
 +
 
 +
See [[SMILA/Documentation/HowTo/Howto_build_a_SMILA-Distribution]] for details on how to setup a build for SMILA.
 +
 
 +
==== Add <tt>examples</tt> projects ====
 +
 
 +
The <tt>examples</tt> directory of the repository contains three simple bundles that demonstrate how to develop SMILA pipelets and workers. You can import them to your workspace just like the other projects.
 +
 
 +
==== Enabling the BPEL Designer ====
 +
 
 +
If you want to work with the SMILA extensions for Eclipse BPEL designer, you need to clone the Git repository at <tt>http://git.eclipse.org/gitroot/smila/org.eclipse.smila.tooling.git</tt> (or <tt>git://...</tt> or <tt>ssh://...</tt>). Currently, the required bundles are:
 +
 
 +
*<tt>org.eclipse.smila.processing.designer.model</tt>
 +
*<tt>org.eclipse.smila.processing.designer.ui</tt>
 +
 
 +
To compile them you need additional bundles from the [http://www.eclipse.org/bpel Eclipse BPEL Designer] in your target platform. See [[SMILA/BPEL Designer]] for more information.
 +
 
 +
 
 +
[[Category:SMILA]]

Latest revision as of 15:34, 4 May 2015


This HowTo describes the necessary steps for setting up a SMILA development environment.

Preconditions

Here is the list of things that you will definitely need for developing SMILA components:

  • JDK 1.7 (Java 8 is not yet supported by SMILA).
  • Eclipse SDK - This HowTo was tested with Eclipse Classic SDK 4.4.2 (Luna SR2 Release)

Getting the source code

There is more than one way of getting the code into your Eclipse workspace. The following sections will describe how to get the source code from the Git repository (recommended!).

As an alternative, you could download the complete source code from the release download page or the nightly build downloads and unpack the archive into your workspace.

Installing Git Provider

(skip this section if Git Team Provider is already installed in your Eclipse IDE - most current Eclipse Packages do contain it)

  • Install Eclipse Git Team Provider and Java Implementaton of Git from the Eclipse software repository.
  • Restart Eclipse.

Get source code from Git

(** Committers: use ssh://git.eclipse.org/gitroot/smila/org.eclipse.smila.core.git for read-write access and enter your credentials below)

  • Click "Next". In the following dialog ensure that branch "master" and other branches you need are selected (there are no other branches at the time of writing ;-)
  • Enter the desired location of your clone of the Git repository. You can put this into your current workspace, but this is not necessary.
    • You can activate the "Import all existing projects after clone finishes" now to import ALL projects, or you can manually import them afterwards to be a bit more selective.
  • Click "Finish". The Git repository will be cloned now. This will probably take a few minutes.
  • Switch to the "Plug-in Development" perspective.
  • To import the projects into the workspace (if not done automatically):
    • Open "File" -> "Import ..." and select "Git"/"Projects from Git". Click "Next" and select "Existing local repository". Click "Next" and select "org.eclipse.smila.core - ...". Click "Next".
    • Select "Import existing projects" and "core" in the tree below, and click "Next". Make sure all projects are selected and click "Finish".
  • After a while a "Problem occurred" dialog will open and there will be lots of compile errors. This is OK, we will fix this now.


Defining the target platform

The target platform defines the set of bundles and features that you are developing against. SMILA ships a Target Definition File that you can open in your IDE to configure the target platform automatically. This file contains all the references needed for developing SMILA with Eclipse Luna SR2 (Release 4.4.2).

Using the target platform provided by SMILA

  • Import project "SMILA.devenv" from the "releng" directory of your local Git repository (same procedure as for importing the other projects).
  • Open the file SMILA.devenv/SMILA.target with the Target Editor.
    Eclipse starts downloading the referenced bundles/features which it tells you by stating "Resolving Target Definition" in its status bar. Be patient, this will take a while. After it has finished, you can click the link "Set as Target Platform" on the top right of the Target Definition editor. Doing so will cause Eclipse to start re-compiling the sources and all error markers should be gone when finished.
  • If you have the Checkstyle Eclipse plugin installed in your IDE, you will still get error messages. See Checkstyle configuration for instructions on how to fix this.

Defining the target platform manually

Launching SMILA in Eclipse IDE

If you've checked out SMILA's trunk correctly, you should have a project called SMILA.launch in your workspace. This project contains the SMILA's launch configuration for Eclipse IDE. To start SMILA directly in your Eclipse IDE, just follow the steps below:

  • Click Run--> Debug Configurations and expand OSGI Framework.
  • Select the SMILA launch file.
  • Click Debug.
    If everything works fine, you will get an output in the Console view similar to the following:
osgi> Persistence bundle starting...
ProviderTracker: New service detected...
ProviderTracker: Added service org.eclipse.persistence.jpa.osgi.PersistenceProviderOSGi
Persistence bundle started.
[INFO ] Context /zookeeper: Registered handler(1) ZooKeeperAdminHandler, pattern /(.*)$
[INFO ] Added worker webFetcher to WorkerManager.
...
[INFO ] HTTP server has SMILA handler RequestDispatcher for context /smila.
[INFO ] HTTP server started successfully on port 8080.

You're done

Congratulations! You've just successfully checked out and configured your SMILA development environment and you can now start developing your own bundles.

Additional steps

The following steps may be needed for special purposes. If you are a SMILA user who only wants to integrate an own component you won't need them.

Checkstyle configuration

If you have the Eclipse Checkstyle plugin installed, you will get a lot of error messages complaining about missing check configurations when Eclipse builds the workspace.

Errors running builder 'Checkstyle Builder' on project 'org.eclipse.smila.utils'.
Fileset from project "org.eclipse.smila.utils" has no valid check configuration.
...

You can solve this by setup your Checkstyle configuration.

Setting up the Eclipse build

See SMILA/Documentation/HowTo/Howto_build_a_SMILA-Distribution for details on how to setup a build for SMILA.

Add examples projects

The examples directory of the repository contains three simple bundles that demonstrate how to develop SMILA pipelets and workers. You can import them to your workspace just like the other projects.

Enabling the BPEL Designer

If you want to work with the SMILA extensions for Eclipse BPEL designer, you need to clone the Git repository at http://git.eclipse.org/gitroot/smila/org.eclipse.smila.tooling.git (or git://... or ssh://...). Currently, the required bundles are:

  • org.eclipse.smila.processing.designer.model
  • org.eclipse.smila.processing.designer.ui

To compile them you need additional bundles from the Eclipse BPEL Designer in your target platform. See SMILA/BPEL Designer for more information.

Back to the top