AF3 Build Management
====================

This page contains information about the build system that is used to build AF3. It is based on maven/tycho. 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.*

Build in Gitlab
------------------------------

The complete configuration to build an AF3 product is contained in the
[maven-releng repository](https://git.fortiss.org/af3/maven-releng).  
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.

Local Build
-----------

##### Install an AF3 developer installation for local building
The preferred platform for locally building AF3 is Linux. The build works on Windows, however
in the resulting Linux distribution the following changes have to applied:

```dos2unix autofocus3-phoenix && chmod a+x autofocus3-phoenix autofocus3-phoenix-binary```

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](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 (from a repo `repo-name`)
    - Option 1: In Eclipse's *Git Repositories* view.
         - Context menu of *Submodules* -> *Add Submodule...*
         - Submodule path: `bundles/<repo-name`
         - Paste clone URL on next wizard page
    - Option 2: On the command line: `git submodule add -b <branch> --name "bundles/<repo-name>" https://git.fortiss.org/af3/<repo-name>.git bundles/<repo-name>`
-   Create a branch of af3-features and update the git submodule of the
    maven-releng repository to point to this branch.
-   Add the plugins to the feature definition
    - AF3 feature (new branch): `/org.fortiss.af3.root/features/af3/org.fortiss.af3.phoenix.feature/feature.xml`
    - Create an additional feature (for more than 1 or 2 plugins).
-   Add new features to a separate update site in “releng/” if needed.