sailing-analytics/doc/DEVELOPMENT

This file explains the development environment and some typical
usecases you will need to work with race analysis project.

IDE
---
We use Eclipse as development environment - version 3.7.x (www.eclipse.org)

Additional mandatory installations:
- Git (file versioning system)
- Maven 3.x (build system)

TODO: Explain at least "on-boarding" use case (what to install, where
to get it, prerequisites, Bugzilla, git, git account and SSH keys, SAP
internal vs. external, file share, Wiki, project import into Eclipse,
JDK setup 1.6/1.7, Eclipse JRE config, ...). Distinguish setup
variants: a) SAP-internal; b) extenral; c) offline

Configure the IDE
-----------------

1. Target Platform

After the import of all required projects from the local git
repository into your eclipse workspace you need to setup the target
platform.  A target platform is an Eclipse concept to define the set
of java classes (from a set of jars/libs) your compiler can use to
build the sources.  We have defined some target-platforms for the
project which can be found inside the project
"com.sap.sailing.targetplatform" in the folder 'definitions'.  There
you will find 1 definition: race-analysis-p2-remote. This is the default
to use in your IDE and the maven build. When testing changes to the
target platform, generate the race-analysis-p2-lcoal target definition
with the java/com.sap.sailing.targetplatform/scripts/createLocalTargetDef.sh
script.
The target definition contains a list of URLs to
different p2 repositories containing the actual bundles. The URLs can
be either URLs to local or remote repositories depending on your
access to those repositories. Normally you should bind your target
platform to central (remote) repositories in order to keep the content
up-to-date.  In case you don't have access to specific remote
repositories you can create a local copy of a p2 repository and change
the URL to this local copy.

!!!ATTENTION!!!

It's important that we can NOT use any other options
(like directories or update site) than p2 repositories for the target
platform definition. The reason is that Tycho (the tool we use for the
maven/osgi build integration) does only support p2 repositories (in
version 0.14.0). Therefore we must convert any jars/libs/etc.  into a
p2 repository if we want to use them in our target definition. Eclipse
equinox provides an application supporting the creation of p2
repositories from a directory with of jar files and a feature.xml
(org.eclipse.equinox.p2.publisher.UpdateSitePublisher).  You can use
the the script createLocalBaseP2repository.sh (in project
com.sap.sailing.targetplatform/scripts) as a template.

The currently used target platform types:
a) Remote p2 repositories (like http://download.eclipse.org/releases/indigo)
b) SAP Nexus repositories (like http://nexus:8081/nexus/content/...)
c) Our own p2 repository served by our central server via Apache WebServer (http://sapcoe-app01.pironet-ndh.com/p2/...)

Local maven build
-----------------

TODO: how to run a maven build; which current working directory to
use? For example, when to delete
git/java/com.sap.sailing.gwt.ui/com.sap.sailing.*?

If you run a local build with maven the used target platform defintion
is 'race-analysis-p2-maven-local'. The reference to this definition is
defined in the pom.xml of the /git/java folder.

The "SAP Race Analysis" Product
-------------------------------

The project com.sap.sailing.feature.p2build contains an eclipse
product definition with the name "SAP Race Analysis".  This product
contains a list of features defining the product.  These features are:

- com.sap.sailing.feature (contains all development bundles and it's dependencies)
- com.sap.sailing.feature.runtime (contains additional libraries only needed at runtime)

The maven/tycho build creates an deployable eclipse product containing
all required runtime artifacts based on this product defintion.  This
is also the basis for the server installation. The resulting files can
be found in /bin/products/raceanalysis.product.id/<os>/<ws>/<arch>/...

Target-Platform related projects
--------------------------------

com.sap.sailing.targetplatform.base -> contains all files required to
build a p2 repository for all library files defining the base target
platform for the sailing project

com.sap.sailing.targetplatform -> contains the p2 repository
generation scripts and the target platform definitions (.target files)

com.sap.sailing.feature -> contains the feature.xml for the race
analysis project itself (required for the product build)

com.sap.sailing.feature.runtime -> contains the feature.xml for
additional runtime libraries which are not required for the source
build (e.g. jetty.osgi bundle)

com.sap.sailing.feature.p2build -> contains the product defintion
(.product file) for the race analysis project (required for the
product build)

Typical development usecases affecting the target platform and the maven build
------------------------------------------------------------------------------

1. Adding an external open source library

To add a new library which can not be found in any SAP repository you
need to follow some steps.

a) Check if the library is already OSGi-enabled (normally this means
there is a manifest.mf in the META-INF folder of the jar file
containing valid OSGi metadata.

b) In case the library is not OSGi-enabled someone has to create such
a OSGI-enabled version (ask the technical lead of the project)

c) Add the library to an appropriate target folder in the project
com.sap.sailing.targetplatform.base (e.g. target-base)

d) Add a corresponding entry to the corresponding feature.xml in the
project com.sap.sailing.targetplatform.base

e) Rebuild the base target platform by running the script
createLocalBaseP2repository.sh
(com.sap.sailing.targetplatform/scripts)

f) Test the new overall target platform by settings the race-analysis-p2-ide-p2admin.target as target platform
   in the IDE
   
g) The admin of the central p2 repository must now replace the content of the central server
   /home/trac/p2-repositories/sailing with the content of the new local base p2 repository
   (com.sap.sailing.targetplatform/base/gen/p2)
 
g) Reload the target platform in the IDE

2. Adding a library from an internal SAP repository (e.g. Nexus)

not used yet.

3. Adding an existing remote p2 repository as new source of libraries

a) Add the URL of the remote p2 repository to all target definition
files in com.sap.sailing.targetplatform/defintions

b) Select the features of the p2 repository you want to use in the project

c) Reload the target platform

4. Adding a GWT library to the com.sap.sailing.gwt.ui project

a) Copy the library (the jar file) to the folder /WEB-INF/lib
b) Add the library to the bundle classpath (in the META-INF/manifest.mf file)
c) Add a build dependency for the GWT compiler to the pom.xml
d) Add the library to the central maven repository /home/trac/maven-repositories
   by using the mvn install:install -file command

5. Adding an GWT extension library (with source code)

TODO (see Highcharts example)

6. Adding a self created p2 repository from a maven based external
project as new source of libraries

Example: Integration of 'Atmosphere' framework (Server push technology) 

TODO

Typical usecases changing the features and product definition
-------------------------------------------------------------

1. Adding a new bundle project

a) add a new bundle project in the IDE

b) add the project to the product definition by adding it to the
feature.xml in the project com.sap.sailing.feature

c) add the project to the launch configurations in com.sap.sailing.server

d) add the project to the main pom.xml (/java dir in the git repository)


TODO: launch OSGi runtime (debug vs. run), compile / launch GWT application
in hosted / non-hosted mode, maven-compile GWT app and launch non-hosted, ...

TODO: How does our git branch structure work? (master -> dev -> test
-> prod1 -> prod2) When to merge from where to where?

TODO: Server Deployment: how to use the screen sessions on sapsailing.com?
How to deploy changes from master branch to dev server, etc.?

TODO: keep this documentation in WikiMarkup format and explain how the
process of updating this documentation and synchronizing with the Wiki
shall work. Consider using a Wiki branch in git that represents the
last deployment.

TODO: runtime installation, e.g., as done for Hawaii on separate laptops