Created page with "{{ScoutPage|cat=Tutorial 5.0}} == Introduction == This tutorial shows how to build an existing Scout application using [http://www.eclipse.org/tycho/ Maven Tycho]. Therefore..."
New page
{{ScoutPage|cat=Tutorial 5.0}}
== Introduction ==
This tutorial shows how to build an existing Scout application using [http://www.eclipse.org/tycho/ Maven Tycho]. Therefore we use the [[{{BASEPAGENAME}}/Minicrm/Minicrm Step-by-Step|Minicrm application]] as base Scout application to integrate it into the Maven Tycho world.
== Installation / Prerequisites ==
This tutorial assumes that your environment fulfills the following requirements.
=== Eclipse ===
==== Eclipse for Scout Developers Luna ====
see [[Scout/HowTo/4.0/Install_Scout_SDK]]
==== [http://eclipse.org/m2e/ m2eclipse] ====
Install m2e: Help > Install New Software...
Updatesite-URL: http://download.eclipse.org/releases/luna/
Choose General Purpose Tools: m2e - Maven Integration for Eclipse
Install m2e connectors: ''Window > Preferences > Maven > Discovery > Open Catalog''
choose: Tycho Configurator
=== [http://maven.apache.org Maven] ===
Installation guide: http://maven.apache.org/download.html#Installation
== Maven Tycho Integration of existing Plugins ==
=== Create new Eclipse Project (used as parent POM) ===
Create a project called ''org.eclipsescout.demo.minicrm.parent''.
Create a file pom.xml inside the new project:
<?xml version="1.0" encoding="UTF-8"?>
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<modelVersion>4.0.0</modelVersion>
<groupId>org.eclipsescout.demo.minicrm</groupId>
<artifactId>org.eclipsescout.demo.minicrm.parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>pom</packaging>
<name>minicrm - parent</name>
</project>
[[File:Create_eclipse_project.png]]
=== Generate POMs for existing projects / plug-ins ===
extraDirs must list all plugin projects.
<source lang="bash">
cd <to org.eclipsescout.demo.minicrm.parent package>
mvn org.eclipse.tycho:tycho-pomgenerator-plugin:generate-poms -DgroupId=org.eclipsescout.demo.minicrm -Dversion=1.0.0-SNAPSHOT -DextraDirs=../org.eclipsescout.demo.minicrm.client,../org.eclipsescout.demo.minicrm.server,../org.eclipsescout.demo.minicrm.shared,../org.eclipsescout.demo.minicrm.ui.rap,../org.eclipsescout.demo.minicrm.ui.swing,../org.eclipsescout.demo.minicrm.ui.swt
</source>
=== Convert every project into a Maven Project: ===
* Refresh all projects with F5
* Convert all projects to maven projects starting with org.eclipsescout.demo.minicrm.parent:
Rightclick on the project and choose: ''Configure > Convert to Maven Project...''
=== Resolve Warnings caused by the previous steps (see Problems-View)===
* Delete every bin directory and fix build.properties files (Cause: The project's output folder was changed from /bin to /target/classes)
[[File:Remove_bin_output_build_properties.png]]
* Delete duplicate Maven Coordinates: (in pom.xml files: delete groupId and version already defined in parent pom)
[[File:Duplicate_groupId_and_version.PNG]]
=== Extend parent POM configuration ===
Add Eclipse and RAP platform Repositories (using [http://maven.apache.org/guides/introduction/introduction-to-profiles.html Maven Profiles]) to org.eclipsescout.demo.minicrm.parent
<source lang="xml">
<profiles>
<profile>
<id>platform-luna</id>
<activation>
<activeByDefault>true</activeByDefault>
<property>
<name>platform-version-name</name>
<value>luna</value>
</property>
</activation>
<properties>
<eclipse.repo.url>http://download.eclipse.org/releases/luna</eclipse.repo.url>
<rap.repo.url>http://download.eclipse.org/rt/rap/2.3</rap.repo.url>
<platform.version>[3.8,3.9)</platform.version>
<tycho.version>0.20.0</tycho.version>
</properties>
</profile>
</profiles>
<repositories>
<repository>
<id>eclipse platform</id>
<url>${eclipse.repo.url}</url>
<layout>p2</layout>
</repository>
<repository>
<id>rap platform</id>
<url>${rap.repo.url}</url>
<layout>p2</layout>
</repository>
</repositories>
</source>
=== Replace existing [http://maven.apache.org/pom.html#Build Build settings]===
Replace the following block in the pom.xml of org.eclipsescout.demo.minicrm.parent
<source lang="xml">
<build>
<plugins>
<plugin>
<groupId>org.eclipse.tycho</groupId>
<artifactId>tycho-maven-plugin</artifactId>
<version>0.20.0</version>
<extensions>true</extensions>
</plugin>
</plugins>
</build>
</source>
with the following block:
<source lang="xml">
<build>
<plugins>
<plugin>
<groupId>org.eclipse.tycho</groupId>
<artifactId>tycho-maven-plugin</artifactId>
<version>${tycho.version}</version>
<extensions>true</extensions>
</plugin>
</plugins>
<pluginManagement>
<plugins>
<plugin>
<groupId>org.eclipse.tycho</groupId>
<artifactId>target-platform-configuration</artifactId>
<version>${tycho.version}</version>
<configuration>
<filters>
<!-- work around Equinox bug 348045 -->
<filter>
<type>p2-installable-unit</type>
<id>org.eclipse.equinox.servletbridge.extensionbundle</id>
<removeAll />
</filter>
</filters>
</configuration>
</plugin>
</plugins>
</pluginManagement>
</build>
</source>
If you only want to build for a specific platform (e.g. win32) you can add the following configuration to the parent pom:
<source lang="xml">
<build>
...
<plugin>
<groupId>org.eclipse.tycho</groupId>
<artifactId>target-platform-configuration</artifactId>
<configuration>
<environments>
<environment>
<os>win32</os>
<ws>win32</ws>
<arch>x86</arch>
</environment>
</environments>
</configuration>
</plugin>
...
</source>
=== Build the parent POM ===
<source lang="bash">
mvn clean install
</source>
Now the build should be successful:
<source lang="bash">
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] org.eclipsescout.demo.minicrm.parent .............. SUCCESS [ 0.171 s]
[INFO] org.eclipsescout.demo.minicrm.shared .............. SUCCESS [ 1.992 s]
[INFO] org.eclipsescout.demo.minicrm.client .............. SUCCESS [ 0.986 s]
[INFO] org.eclipsescout.demo.minicrm.client.mobile ....... SUCCESS [ 0.314 s]
[INFO] org.eclipsescout.demo.minicrm.jasperreports ....... SUCCESS [ 2.568 s]
[INFO] org.eclipsescout.demo.minicrm.server.jasperreports SUCCESS [ 0.305 s]
[INFO] org.eclipse.scout.minicrm.reports ................. SUCCESS [ 0.091 s]
[INFO] org.eclipsescout.demo.minicrm.server .............. SUCCESS [ 0.748 s]
[INFO] org.eclipsescout.demo.minicrm.ui.rap .............. SUCCESS [ 0.354 s]
[INFO] org.eclipsescout.demo.minicrm.ui.swing ............ SUCCESS [ 0.266 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 18.723 s
[INFO] Finished at: 2014-05-13T11:32:54+01:00
[INFO] Final Memory: 65M/517M
[INFO] ------------------------------------------------------------------------
</source>
== Build Eclipse Scout Swing client application (building an Eclipse Product) ==
:1. Create new Eclipse Project (holding the client Product)
File > New > Project.
Enter the name "org.eclipsescout.demo.minicrm.swing.product"
:2. Add / Create Swing client Product and config.ini
:* Copy the config.ini and the minicrm-swing-client.product into the new project with Copy&Paste
:* Important: Tycho only supports *.product file in the project root
:* Important: The *.product file has to contain the attribute 'uid' (correspond to the ID field in the Product Configurator view) and it must be the same as the product.id element in the next step. In this case it's ''org.eclipsescout.demo.minicrm.ui.swing.product''.
:3. Create POM configuration
:* Create a pom.xml file with the following contents:
<source lang="xml">
<project xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd" xmlns="http://maven.apache.org/POM/4.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.eclipsescout.demo.minicrm</groupId>
<artifactId>org.eclipsescout.demo.minicrm.parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
<relativePath>../org.eclipsescout.demo.minicrm.parent/</relativePath>
</parent>
<artifactId>org.eclipsescout.demo.minicrm.ui.swing.product</artifactId>
<packaging>eclipse-repository</packaging>
<name>minicrm - ui.swing.product</name>
<properties>
<product.finalName>minicrm</product.finalName>
<product.id>org.eclipsescout.demo.minicrm.ui.swing.product</product.id>
<product.outputDirectory>${project.build.directory}/products/${product.id}/win32/win32/x86</product.outputDirectory>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.eclipse.tycho</groupId>
<artifactId>tycho-p2-director-plugin</artifactId>
<executions>
<execution>
<id>materialize-products</id>
<phase>package</phase>
<goals>
<goal>materialize-products</goal>
</goals>
</execution>
</executions>
<configuration>
<products>
<product>
<id>${product.id}</id>
</product>
</products>
</configuration>
</plugin>
<!-- Workaround: Use an existing config.ini file (caused by the problem that tycho will always generate a default one) -->
<plugin>
<artifactId>maven-resources-plugin</artifactId>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<resources>
<resource>
<directory>${project.build.directory}/../</directory>
<filtering>false</filtering>
<includes>
<include>config.ini</include>
</includes>
</resource>
</resources>
<outputDirectory>${product.outputDirectory}/configuration</outputDirectory>
<overwrite>true</overwrite>
</configuration>
</execution>
</executions>
</plugin>
<!-- Configure the assembly plugin to build the final file (war or zip) -->
<plugin>
<artifactId>maven-assembly-plugin</artifactId>
<configuration>
<descriptors>
<descriptor>assembly.xml</descriptor>
</descriptors>
<finalName>${product.finalName}</finalName>
<appendAssemblyId>false</appendAssemblyId>
</configuration>
<executions>
<execution>
<id>make-assembly</id>
<phase>package</phase>
<goals>
<goal>single</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
</source>
:* Create an assembly.xml file with the following contents:
<source lang="xml">
<assembly>
<id>org.eclipsescout.demo.minicrm.client.zip</id>
<formats>
<format>zip</format>
</formats>
<includeBaseDirectory>false</includeBaseDirectory>
<fileSets>
<!-- exported product files -->
<fileSet>
<directory>${product.outputDirectory}</directory>
<outputDirectory>/${product.finalName}</outputDirectory>
<excludes>
<exclude>p2/**</exclude>
<exclude>eclipsec.exe</exclude>
<exclude>artifacts.xml</exclude>
</excludes>
</fileSet>
</fileSets>
</assembly>
</source>
:4. Convert to a Maven Project: ''Configure > Convert to Maven Project...''
:5. Update the parent POM
:* Extend the ''modules'' by the new Maven Module.
:* Define the newly used Maven Plugins in ''pluginManagement'' in the parent pom.xml file.
<source lang="xml">
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-resources-plugin</artifactId>
<version>2.5</version>
<configuration>
<encoding>UTF-8</encoding>
</configuration>
</plugin>
<plugin>
<groupId>org.eclipse.tycho</groupId>
<artifactId>tycho-p2-director-plugin</artifactId>
<version>${tycho.version}</version>
</plugin>
</source>
:6. Build parent POM
Run the following command on the commandline in the directory ''org.eclipsescout.demo.minicrm.parent''.
<source lang="bash">
mvn clean install
</source>
After successfully building, your directory ''org.eclipsescout.demo.minicrm.product'' should like that:
[[File:Structure_of_swing_product.PNG]]
== Build Eclipse Scout Server WAR (building an Eclipse Product) ==
=== Create new Eclipse Project (holding the server Product) ===
File > New > Project
Name: ''org.eclipsescout.demo.minicrm.server.product''
=== Add / Create server Product ===
Copy & Paste the config.ini and the minicrm-server.product from the ''org.eclipsescout.demo.minicrm.server/products/production'' folder into the newly created project.
IMPORTANT: Note that the uid (or ID in the configuration view) of the *.product file must be the same as in the pom.xml file in the next step. In this case it's ''org.eclipsescout.demo.minicrm.server.product''
=== Create POM configuration ===
Create a pom.xml file in the new project with the following content:
<source lang="xml">
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
<parent>
<groupId>org.eclipsescout.demo.minicrm</groupId>
<artifactId>org.eclipsescout.demo.minicrm.parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
<relativePath>../org.eclipsescout.demo.minicrm.parent/</relativePath>
</parent>
<artifactId>org.eclipsescout.demo.minicrm.server.product</artifactId>
<packaging>eclipse-repository</packaging>
<properties>
<product.id>org.eclipsescout.demo.minicrm.server.product</product.id>
<product.outputDirectory>${project.build.directory}/products/${product.id}/win32/win32/x86</product.outputDirectory>
<product.finalName>minicrm</product.finalName>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.eclipse.tycho</groupId>
<artifactId>tycho-p2-director-plugin</artifactId>
<executions>
<execution>
<id>materialize-products</id>
<phase>package</phase>
<goals>
<goal>materialize-products</goal>
</goals>
</execution>
</executions>
<configuration>
<products>
<product>
<id>${product.id}</id>
</product>
</products>
</configuration>
</plugin>
<!-- Workaround: Use an existing config.ini file (caused by the problem that tycho will always generate a default one) -->
<plugin>
<artifactId>maven-resources-plugin</artifactId>
<executions>
<execution>
<phase>package</phase>
<goals>
<goal>copy-resources</goal>
</goals>
<configuration>
<resources>
<resource>
<directory>${project.build.directory}/../</directory>
<filtering>false</filtering>
<includes>
<include>config.ini</include>
</includes>
</resource>
</resources>
<outputDirectory>${product.outputDirectory}/configuration</outputDirectory>
<overwrite>true</overwrite>
</configuration>
</execution>
</executions>
</plugin>
<!-- Configure the assembly plugin to build the final server war file -->
<plugin>
<artifactId>maven-assembly-plugin</artifactId>
<configuration>
<descriptors>
<descriptor>assembly.xml</descriptor>
</descriptors>
<finalName>${product.finalName}</finalName>
<appendAssemblyId>false</appendAssemblyId>
</configuration>
<executions>
<execution>
<id>make-assembly</id>
<phase>package</phase>
<goals>
<goal>single</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>
</source>
=== Create a assembly.xml file in the new project with the following content: ===
<source lang="xml">
<assembly>
<id>org.eclipsescout.demo.minicrm.server.war</id>
<formats>
<format>war</format>
</formats>
<includeBaseDirectory>false</includeBaseDirectory>
<fileSets>
<!-- web-inf template -->
<fileSet>
<directory>${basedir}/templates/WEB-INF</directory>
<outputDirectory>/WEB-INF</outputDirectory>
<includes>
<include>**</include>
</includes>
</fileSet>
<!-- exported product files -->
<fileSet>
<directory>${product.outputDirectory}</directory>
<outputDirectory>/WEB-INF/eclipse</outputDirectory>
<includes>
<include>configuration/**</include>
<include>plugins/**</include>
</includes>
</fileSet>
</fileSets>
</assembly>
</source>
=== Convert Maven project ===
Convert to a Maven Project: ''Configure > Convert to Maven Project...''
=== Update the parent POM ===
:* Extend the ''modules'' by the new Maven Module
:*. Add WEB-INF template to match [http://www.eclipse.org/equinox/server/http_in_container.php Equinox in a Servlet Container] requirements (directory location has to match the referred ''fileSet'' in assembly.xml)
:* A running WEB-INF template can be extracted from a Scout SDK exported war file. Details can be found {{ScoutLink|Tutorial/3.8/Deploy_to_Tomcat#Export_Scout_Application|name=here}}.
=== Build parent POM ===
Run the following command in the ''org.eclipsescout.demo.minicrm.parent'' directory to build the server product.
<source lang="bash">
mvn clean install
</source>
Your ''org.eclipsescout.demo.minicrm.server.product'' folder should now look like that:
[[File:Folder_structure_server_product.PNG]]
== Testing an Eclipse Scout Client/Server Application (using JUnit/Maven Tycho Surefire) ==
{{note|TODO|This tutorial is incomplete and needs to be updated}}
Using Maven Tycho Surefire you can test your Eclipse Scout Application automatically. A sample application is on https://github.com/innovad/scout.autotest.demo. More details tbd.
=== Plugin/Fragment/Feature Setup ===
Create the required testing plugins and fragments for your Scout application. You will have to create a plugin and a fragment for each module (client, server, shared) to be tested. We recommend to use the following naming conventions:
:* org.yourapp.client
:* <b>org.yourapp.client.test</b>
:** A plugin holding some support classes (no JUnit tests here)
:* <b>org.yourapp.client.test.fragment</b>
:** A fragment with host <b>org.yourapp.client</b> containing the JUnit tests. The tests will be loaded with the plugin to be tested by the OSGi framework.
:* org.yourapp.server
:* <b>org.yourapp.server.test</b>
:** similar as above
:* <b>org.yourapp.server.test.fragment</b>
:** similar as above
:* org.yourapp.shared
:* <b>org.yourapp.shared.test</b>
:** similar as above
:* <b>org.yourapp.shared.test.fragment</b>
:** similar as above
:* org.yourapp.client.feature
:* org.yourapp.server.feature
:* org.yourapp.server.product
:* org.yourapp.ui.swing.product
:* org.yourapp.ui.swing
:* org.yourapp.parent
:* org.yourapp.target
=== Testing Server ===
=== Testing Shared ===
=== Testing Client ===
=== Debugging a Test ===
* Add the "debugPort" to your pom.xml
<source lang="xml"><plugin>
<groupId>org.eclipse.tycho</groupId>
<artifactId>tycho-surefire-plugin</artifactId>
<version>${tycho.version}</version>
<configuration>
<debugPort>18081</debugPort>
</configuration>
</plugin>
</source>
* Create a new Debug Configuration in Eclipse of type "Remote Java Application" (localhost:18081)
* Tycho stops with "Listening for transport dt_socket at address: 18081"
* At this point, Run your Debug Configuration
== Advanced Topics ==
=== Support [http://marketplace.eclipse.org/content/rayo-look-and-feel-eclipse-scout Rayo Look and Feel for Eclipse Scout] ===
Add new P2-''Repository'' with the corresponding Update Site URL
=== Support [http://marketplace.eclipse.org/content/jdbc-drivers-eclipse-scout JDBC Drivers for Eclipse Scout] ===
Add new P2-''Repository'' with the corresponding Update Site URL
=== Integrate the JRE into the client zip ===
Extend the assembly.xml's ''fileSets'' definition:
<source lang="xml">
<!-- integrate the JRE into the client zip -->
<fileSet>
<directory>/path/to/jre</directory>
<outputDirectory>/${product.finalName}/jre</outputDirectory>
</fileSet>
</source>
=== Bundle client and server together (to support direct client download) ===
{{note|TODO|Add a description}}