Project

General

Profile

AF3 Product Distillery

Using the Maven/Tycho build environment already used on the Jenkins build server,
the product distillery allows to build the AF3 Phoenix Product on the local developer
machine.

Legal Advice

Note that you are not allowed to publish your version of the AF3 product without
explicit permission of the AF3 development team. You are furthermore disallowed
to use or to change or to extend or to overwrite the AutoFOCUS 3 logo and/or the
product branding. You may propose your own branding as part of the permission process.

Setup the distillery environment

This page is composed of the folloing sections, corresponding merely to the steps which are necessary to transform the standard developer installation
into the product distillery environment installation:

  1. Check Java version to avoid Out-of-memory problems
  2. Setup a separate Eclipse and workspace installation
  3. Install the Maven Integration for Eclipse (m2e feature)
  4. Replace the fortiss-std-env with its distillery
  5. Check out additional Maven projects required to run the build
  6. Customize the product by adding Your own plugins to the build
  7. Create the product ZIP archives
  8. Custom Branding
  9. FAQ

1. Java version

This procedure has been confirmed to work with Java 8, but not
with Java 6. The behavior with Java 7 is currently untested and uncofirmed.

2. Separate Eclipse and workspace

The distillery procedure is to some extent destructive to Your
workspace and Eclipse installation.

It introduces the Maven extension and a replacement for the
fortiss-std-env. This also introduces build errors detected
by the Maven extension, which can be ignored, but may hinder
Your everyday development activities.

Furthermore, there it may result in many SVN changes, which are
certainly not to be uploaded to the Subversion server.

Therefore, we recommend that You setup a separate Eclipse instance
and a separate developer workspace for the AF3 distillery.
Follow the developer installation as usual.

3. Install Maven Integration for Eclipse

  1. Go to Help -> Install new software
  2. Enter the following update site: http://download.eclipse.org/releases/kepler.
  3. Pick m2e - Maven Integration for Eclipse (there might be several, but they should all be equivalent)
  4. (optional) Enable Debug Output in the Maven section of the Eclipse preferences
  5. Restart Eclipse (Eclipse should already suggest it)

Ignore errors reported by Eclipse (more precisely by the Maven extension).
Maven does not know about the Tycho build components, but it will when we run the
build.

4. Replace the fortiss-std-env with the distillery-std-env

  1. delete the plugin fortiss-std-env
  2. Go to File -> Import...
  3. Choose: Checkout projects from SVN
    (warning: so far it looks familiar, but please pay attention to the next step before going further)
  4. Choose the existing location https://orion.fortiss.org/svn/af3
  5. Select the project https://orion.fortiss.org/svn/af3/distillery/distillery-std-env and click Next
    -> the checkout dialog will propose fortiss-std-env, this is expected; keep it this way
  6. Click Next again (and not directly Finish as usual)
  7. Uncheck "Use default workspace location"
  8. Choose the "plugins" sub-directory of your workspace
  9. Now hit Finish

This particular procedure is necessary because of a pitfall introduced by buckminster materialization: All the
plugin projects reside in a plugins sub-directory of your workspace location.
Unfortunately, the Maven build is run on the hard disk locations instead of the
Eclipse workspace abstraction.

5. Checkout additional Maven projects

Apply the same procedure as for distillery-std-env to check out the following projects (yes, they have to be checked out one by one):
  1. https://orion.fortiss.org/svn/af3/distillery/org.fortiss.af3.phoenix.distillery.application
    (this project replaces af3.rcp.application and is used for custom branding)
  2. https://orion.fortiss.org/svn/af3/distillery/org.fortiss.af3.phoenix.distillery.p2site
  3. https://orion.fortiss.org/svn/af3/distillery/org.fortiss.af3.phoenix.distillery.p2site.build
  4. https://orion.fortiss.org/svn/af3/distillery/org.fortiss.af3.phoenix.distillery.p2site.feature
    (used to build an update site)
  5. https://orion.fortiss.org/svn/af3/distillery/org.fortiss.af3.phoenix.distillery.product
  6. https://orion.fortiss.org/svn/af3/distillery/org.fortiss.af3.phoenix.distillery.product.build
  7. https://orion.fortiss.org/svn/af3/distillery/org.fortiss.af3.phoenix.distillery.product.feature
    (used to build the product from the update site)
  8. https://orion.fortiss.org/svn/af3/distillery/org.fortiss.eclipse.rcp.help.feature
    (repackaging of a couple of Eclipse features needed to enable the help system in the products)

6. Customize the product to your needs

(the reason you are doing this entire procedure)

  1. Again using the same procedure as before (i.e., ensuring that the location is plugins), check out any additional plugins or branched alternatives you want to
    have in the custom project and apply any patches to the plugins already part
    of the main product release
  2. Make sure your plugins contain a pom.xml like all other plugin projects
  3. Add your plugins to /org.fortiss.af3.phoenix.distillery.p2site.build/pom.xml (use the already
    specified plugins as reference template)
  4. Add your plugins to /org.fortiss.af3.phoenix.distillery.p2site.feature/feature.xml
  5. Add your plugins to /org.fortiss.af3.phoenix.product.feature/feature.xml

7. Create the product

  1. Right-click /org.fortiss.af3.phoenix.distillery.p2site.build/pom.xml and choose
    Run as ... -> Maven Install to build the update site, which is located at
    /org.fortiss.af3.phoenix.distillery.p2site/target.
  2. Right-click /org.fortiss.af3.phoenix.distillery.product.build/pom.xml and choose
    Run as ... -> Maven Install to build the product ZIPs, which are located at
    /org.fortiss.af3.phoenix.distillery.product/target.

You may have to refresh these to projects by hitting F5.

8. Custom Branding

The distillery branding is located in two of the projects checked out earlier:
  1. org.fortiss.af3.phoenix.distillery.application contains the splash screen image
    and the workbench advisor including the icons registered with it.
    You may want to look at the repository revision 13263 of this project to have an
    example or use corresponding Eclipse documentation sources.
  2. org.fortiss.af3.phoenix.distillery.product contains the product file, which is
    responsible to configure the native OS launcher application.
    You may want to look at the repository revision 13235 of this project to have an
    example or use corresponding Eclipse documentation sources.

9. FAQ and Common Problems / Errors

MANIFEST.MF vs. pom.xml

If your plugin version in META-INF/MANIFEST.MF is "1.0.0.qualifier" then your pom.xml
must contain the version "1.0.0-SNAPSHOT".

Is there a quick way to check if dependencies are all well?

Run "Maven Clean" target instead of "Maven Install" on the P2 site build.

Adding a plugin resulted in a dependency error although Eclipse version works perfect?

  1. Check the on-disk location of the missing plugin if it is really next to all others.
  2. Check if /org.fortiss.af3.phoenix.distillery.p2site.build/pom.xml includes the plugin.
  3. Check if /org.fortiss.af3.phoenix.distillery.p2site.feature/feature.xml includes the plugin.