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 build works on Windows as well as on Linux. The preferred platform for locally building AF3 is Linux. For both build, it is needed to have an AF3 developer installation, but with a small change to the normal one. Follow the the instructions of the usual [AF3 Developer Installation](AF3 Developer Installation), but when you need to select a setup file (or the link to it), you use this one: ```https://git.fortiss.org/af3/fortiss-std-env/-/raw/master/oomph/af3-releng.setup``` . This will install a developer installation ready to build the RCP with maven. You will get the master of "maven-releng" ("org.fortiss.af3.root") as the only repository within this installation. ##### Update to the latest or wanted version of the af3 plugins When you have your AF3 developer installation with the "maven-releng" repository: 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” or switch each submodule separately to the branch you need for your build. ##### Triggering a maven build When you have your AF3 developer installation with the "maven-releng" repository and the wanted versions of the submodules (e.g., all masters of the plugins, see previous step): 1. While being in the "Java" view/perspective, navigate in the menu bar to “Run > Run configurations” 2. Select under "Maven Build" the configuration “Build All” and click run. Note: There are also preconfigured launches for cleaning and running the tests. 3. After 10-15 minutes the build should be done: - The artifacts can be found in `\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 do not seem to work for the moment and can be ignored. - If you are using Linux you have to apply an additional command in the end, when you have a locally built AF3: ```dos2unix autofocus3-phoenix && chmod a+x autofocus3-phoenix autofocus3-phoenix-binary``` . So, if you have finished the steps above, use this command in the resulting AF3 folder. - 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 /OpenJDK11/bin/javaw.exe` . - Start/Test the local build by executing the AF3 start file: "autofocus3-phoenix(.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 repository - 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 command line 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 - see next explicit section: [Adjust your build](https://git.fortiss.org/af3/af3/-/wikis/Setting_up_a_local_build#adjust-your-build) Adjust your build --------------------------- Often, you do not want to have/build your current build/product just with the masters of the AF3 plugins, but you want to add your own stuff (based on own branches, submodules, etc.). These are steps you might need (not all are needed for all situations!): - If you have own/new submodules you want to integrate: 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/` - Paste clone URL on next wizard page - Option 2: On the command line: `git submodule add -b --name "bundles/" https://git.fortiss.org/af3/.git bundles/` - If not already done: Add the plugins to the feature definition ([https://git.fortiss.org/af3/af3-features](https://git.fortiss.org/af3/af3-features)), what is already described here: [Register the plugin with the developer product definitions](https://git.fortiss.org/af3/af3/-/wikis/Adding_a_new_plugin#register-the-plugin-with-the-developer-product-definitions) - Modify AF3 feature (create and commit a new branch for this): `/org.fortiss.af3.root/features/af3/org.fortiss.af3.phoenix.feature/feature.xml` - Create an additional feature (for more than 1 or 2 plugins). - If needed, add new features to a separate update site in “releng/”. - What is usually always needed is to adjust the POM file: - Go to your maven build installation (see above: [Local Build](https://git.fortiss.org/af3/af3/-/wikis/Setting_up_a_local_build#local-build)), open in the maven-releng repository the "bundles" folder and adjust the "pom.xml" (create a new branch for this change before committing!). Add your plugins to the others in the same way (a new "module" entry for each plugin).