Project

General

Profile

AF3 Build Management

This page contains information about the build system that is used to build AF3.
It is based on maven/tycho and uses Jenkins for regular builds. Nevertheless, it
is easily possible to generate an equivalent build locally, or to create derivate
products.

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.

Release engineering repository

The complete configuration to build an AF3 product is contained in the maven-releng repository.
This repository follows the standard structure of release engineering repositories that use maven/tycho (see https://github.com/vogellacompany/tycho-example), except that the product is located in the top level and not within the releng folder. Furthermore, this repository contains only the build recipe. Any actual content required for the build is acquired using git submodules such that we can use identical repositories in an eclipse-based environment and maven.

The build itself is controlled by environment variables passed by invoked maven commands. These variables activate build profiles in the maven configuration.
The following build flags are configured:

build.emf     --- activates the emf code generation. REQUIRED WHEN SETTING "build.af3" OR "build.kernel".
build.af3     --- activates the compilation of AF3 plugins.
build.tooling --- activates the compilation of tooling kernel plugins.
build.tests   --- runs the JUnit integration tests on the resulting product.

The build flags are used for a modular build configuration. For instance, another project could only depend on the tooling and implement a product that is totally different from AF3.
The flag "build.tooling" just produces a p2 update site that can be reused by subsequent builds. This update site is ignored if the flag is specified. Thus, the combination of "build.af3" and "build.tooling" will not use the tooling update site.
An equivalent mechanism is implemented for "build.tests" that additionally uses an AF3 p2 update site.

Notes
  • We use the maven phase "verify" for building, not "package", which is the default. We are forced to use this phase, since we must perform post-package product patching (no other phase qualifies). This is also the reason to introduce the "build.tests" flag to skip the testing phases that are located between the "packaging" and "verify" phases.
  • The flag "build.emf" is required to avoid triggering the code generation multiple times.

Repository Structure

The repository is structured as follows:

bundles  --- contains any standard eclipse plugin and the emf code generator.
features --- contains any tooling kernel or af3 feature definition (set of plugins).
products --- contains product descriptions (set of features): Produces the resulting zips.
releng   --- common build configuration and p2 update sites.
tests    --- JUnit integration or module tests of the application, or single fragments respectively.

Bundles

The bundle folder is composed of the following repositories:

af3           --- Git submodule of the AF3 plugins.
af3-rcp       --- Git submodule containing the org.fortiss.af3.rcp.application plugin.
emf-generator --- Contains the EMF code generator and its launch configuration.
kernel        --- Git submodule of the tooling kernel plugins.

Two maven POM files are found in this folder:

pom.xml               --- Specifies the to-be-compiled eclipse plugins activated by the given build flags.
pom-bundle-parent.xml --- Compilation-specific configuration: Currently, it only adds the required OpenJFX libraries to the tycho classpath.

The pom.xml file is the entry point for the compilation, whereas the pom-bundle-parent.xml is included from bundle repos (such as af3).

Note that all plugins are build pom-less: This means that no pom.xml config file is needed within standard eclipse plugins. It is only required at the level above. Therefore, a maven extension is specified within the ".mvn" folder within the root of the maven-releng repository.

Features

Contains the tooling kernel and af3 feature as git submodules. Each of these features contains the full set of plugins as of now. However they might be regrouped acc. to functionality groups in future.

Products

Contains the AF3 Phoenix product as git submodule.

Releng

Contains the following modules:

org.fortiss.af3.configuration --- Common configuration of all maven modules such as maven plugin versions and configuration. Moreover, commonly used variables are specified here.
org.fortiss.af3.target        --- Target definition file that specifies all available plugins of the compilation and runtime platform. The definition of p2 sites is only allowed here. (There is only one exception in the product)
org.fortiss.af3.update        --- Contains the configuration to produce the AF3 p2 update site.
org.fortiss.tooling.update    --- Contains the configuration to produce the Tooling kernel update site.

Tests

Contains a git submodule containing the AF3 JUnit tests.

Jenkins setup

There exist four Jenkins jobs:

tooling-kernel                 --- Builds the tooling kernel p2 update site and provides it to other jobs (build flags: "build.tooling" + "build.emf")
af3-p2site-product             --- Builds the AF3 product and p2 update site and provides it to other jobs (build flags: "build.af3" + "build.emf")
af3-product-test               --- Executes the integration tests on the final product (build flags: "build.tests")
af3-phoenix-nightly-10-results --- Aggregates the OS-specific products from the af3-p2site-product job and offers them to a cron job to copy them to a publicly accessible download folder.

All the jobs listed above trigger the jobs listed below them in order.

Local Build

Install an AF3 developer installation for local building

Use the oomph script at https://git.fortiss.org/af3/fortiss-std-env/raw/master/oomph/af3-releng.setup when following the instructions at AF3 Developer installation. This will install a developer installation ready to build the RCP with maven.

Update to the latest version of the af3 plugins

  1. Open the view "Git Repositories" from the "Quick access" box in the top-right corner of eclipse.
  2. Navigate to "maven-releng > Submodules".
  3. Select all submodules, open the context menu, and select "Switch to > master"

Triggering a maven build

  • In the menu, go to "Run > Run configurations".
  • Select the m2e configuration "Build All" and click run. NOTE: There are also preconfigured launches for cleaning and running the tests.
  • After 10-15 minutes the build should be done:
    • The artifacts can be found in <root dir>\git\maven-releng\products\af3\org.fortiss.af3.phoenix.product\target\products.
    • To start the product, extract the ZIP file for your platform. The extracted versions in the same directory currently do not seem to work.
    • You may have to add the following to autofocus3-phoenix.ini to enable start the product in case JDK/JRE 11 is not in the system path: -vm <path to>/OpenJDK11/bin/javaw.exe

Creating a derivate product

  • First setup a local build as described above.
  • All required configuration changes are done on the basis of the maven-releng repository.
  • Modifying the maven-releng repostory
    • Create a separate branch of the repository.
    • Perform the below modifications, depending on your task.

Using different branches

  • Edit the git submodule branch pointer of each repository for which you need a different branch than master.
    This can be done from eclipse (View: Git repositories) or by modifying the .gitmodules file in the root of the maven-releng clone.
  • Update the submodule from the GUI, or manually by git submodule update --remote --recursive --checkout from the commandline at the root of the maven-releng clone. NOTE: Sometimes, the latter requires the "--force" option. But beware: this resets any change in submodules.

Adding plugins / modifying the plugin list

  • Add additional eclipse plugins as git submodules in the bundles folder (either within eclipse, or by git submodule add -b <branch> --name "bundles/<repo-name>" https://git.fortiss.org/af3/<repo-name>.git bundles/<repo-name> from the command line).
  • Add the plugins to the AF3 feature (new branch), or an additional feature (for more than 1 or 2 plugins).
  • Add new features to a separate update site in "releng/" if needed.
  • Create a branch of af3-rcp and update the git submodule of the maven-releng repository to point to this branch.
  • Add the plugins as dependencies to "bundles/af3-rcp/org.fortiss.af3.rcp.application".

Adding a jenkins job

  • Create a copy of the af3-p2site-product job and adjust the maven-releng repository specification to point to your branch.
  • If kernel changes are required, create a copy as well and update the branch pointer.
    Additionally, you need to update af3-p2site-product to fetch the p2 artifact from this job (Artifacts to copy).
  • Optionally, you can trigger unit-test, or a copy thereof (for modified unit tests).