AF3-Developer-Installation.md

 AF3 Developer Installation with Oomph
 =====================================
 
-Updating an existing installation
----------------------------------
-
-Our setup allows updating existing installations almost seamlessly.
-Updates are received automatically if you installed AF3 - Developer
-installation by using the link
-`https://git.fortiss.org/af3/fortiss-std-env/raw/master/oomph/af3.setup`
-during the oomph setup (see below).  
-If there are any additional required to update from one version to
-another, they will be announced by mail on the AF3 developer list and
-also recorded here.
-
-To migrate from a local file-based installation to a URL-based one,
-please find the required instructions at the bottom of this page.
-
-Java Compiler Version 11
-------------------------
+Active development of AF3 is performed on Windows x64 and Linux x64 platforms. While the macOS x64 platform might work to a certain extend, it is unsupported. Since AutoFOCUS 2.21, no longer macOS binaries will be provided.
 
-The AF3 source must be compiled using a Java compiler version 11. We
-recommend OpenJDK since we use it for building internally.
+Java Compiler Version 11+
+-------------------------
 
-**Notes**
-
--   **Linux**: Your distribution probably already packaged OpenJDK, so
-    you just have to install the openjdk-11 package from you package
-    manager. **BEWARE:** Ubuntu 18.04 has a package named
-    “openjdk-11-jdk” that installs OpenJDK 10. Do not use it! Instead,
-    search for a PPA that offers the correct package.
--   **Windows/MacOS:** OpenJDK can be obtained from
-    [Adoptium](https://adoptium.net/?variant=openjdk11), a buildfarm hosted by the Eclipse Adoptium project.
+The AF3 source must be compiled using a Java compiler version 11 or higher. We recommend the [latest LTS release of the *Eclipse Temurin* distribution](https://adoptium.net/de/temurin/releases) of OpenJDK on any development platform for the following reasons (tested with version jdk-17.0.3+7):
+- The fortiss AF3 team uses it internally for development and in its CI pipeline
+- Permissive license
+- Availability for all supported development platforms
+  - Windows: MSI installer (recommended) or ZIP archive
+  - Linux: tar.gz archive
 
 Installation Procedure
 ----------------------
@@ -41,13 +22,15 @@ Installation Procedure
     - NOTE: The HOME variable is read by the git implementation of Eclipse. If it points to a network share, you will experience severe performance impacts, so choose a local folder instead!
 -   Download the [Eclipse Installer](https://www.eclipse.org/downloads/) and start it
     -  Be sure to get a recent version that bundles a JRE. Otherwise the installation may fail due to SSL certificate issues
-    - Tested with [2021-09 a.k.a 1.22.0 Build 5169](https://www.eclipse.org/downloads/packages/release/2021-09/r)
+    - Tested with [2022-03 a.k.a 1.24.0 Build 5396](https://www.eclipse.org/downloads/packages/release/2022-03/r)
     -  After starting, switch to *Advanced Mode* (“burger icon” in the upper-right corner)
 -   On the **Product** page select:
     -   Eclipse Modeling Tools
     -   Product Version: 2019-12
-    -   Java 1.8+ VM: <Select your JDK 11 Installation or leave the
-        default>
+    -   Java 1.8+ VM:
+         - *Manage Virtual Machines...* (on the very right)
+         - *Browse...*
+         - Select the root directory of your Eclipse Temurin installation (e.g., `C:\Program Files\Eclipse Adoptium\jdk-17.0.3.7-hotspot`)
     -   Bundle Pool:
         <Select a location for the bundle pool or leave the default>
     -   Select the **Next** button to go to the Project page
@@ -59,20 +42,8 @@ Installation Procedure
     -   Select **Eclipse Projects** from the Catalog drop-down box
     -   Copy and paste the following link to the text field:
         `https://git.fortiss.org/af3/fortiss-std-env/raw/master/oomph/af3.setup`
-        -   Note 1: Using this link, instead of installing via a local
-            file, ensures that your installation will remain up-to-date.
-            Available updates will be indicated directly after each
-            startup of eclipse. You are recommended to install them.
-        -   Note 2: If you are working with the eclipse platform itself
-            (AF3 platform updates), you may consider using a file-based
-            installation from a common (local) `fortiss-std-env`
-            repository. It allows you test modifications to the setup
-            easily by updating the setup file via git. Please remember
-            to import this repository in your developer installation
-            manually to receive remote updates by pulling.
     -   Hit **OK**
-    -   There is now a new folder / category entry called **<span
-        style="text-align:left;">User&gt;</span>** and the **AutoFOCUS 3
+    -   There is now a new folder / category entry called **User** and the **AutoFOCUS 3
         (Developer)** project below it
     -   **Check-mark** the project and click **Next**
     -   Depending on the state of your installer, you may need to install
@@ -80,7 +51,7 @@ Installation Procedure
         The installer is relaunched afterwards and you have to reselect the
         **AutoFOCUS 3 (Developer)** project.
 -   On the **Product Variable** page:
-    -   Check “Show all variables” at the bottom of this dialog page to
+    -   Check *Show all variables* at the bottom of this dialog page to
         see all options
     -   Customize the installation locations or accept the default (sub-folder to your user home)
     -   Select **Next**
@@ -92,86 +63,71 @@ Installation Procedure
     package explorer icons (you should see gray, red, yellow or green
     code rating bullets in the top-left corner of each project icon).
 -   **NOTE**: If there are build errors after the compilation (see *Problems* view), ...
-    - ... clean (ONLY) the plugin “org.fortiss.tooling.kernel” such that the
+    - ... clean (ONLY) the plugin `org.fortiss.tooling.kernel` such that the
     pseudo-errors disappear.
     - ... clean all plugins in the workspace.
-    - ... reload the target platform. Make sure that the target platform
-      has been resolved before reloading!
-    - ... add the require plugins in the OS-specific debug configuration
-      (`Debug` -> `Debug Configurations ...` -> `Eclipse Application` ->
-      e.g. `win64` -> `Add Required Plug-ins`).
+    - ... reload the target platform. Make sure that the target platform has been resolved before reloading!
+    - ... add the require plugins in the OS-specific debug configuration (`Debug` -> `Debug Configurations ...` -> `Eclipse Application` -> e.g. `win64` -> `Add Required Plug-ins`).
     - ... restart AutoFOCUS3.
--   Next, one typically switches to the Java perspective by typing
-    “Java” into the Quick Access" box in the top-right corner and
-    clicking on the “Perspective” item in the list (Not the View!).
+-   Next, one typically switches to the Java perspective by typing *Java* into the *Quick Access* box in the top-right corner and clicking on the *Perspective* item in the list (not the view!).
 
 Starting AF3
 ------------
 
 - Go to “Run >Run” or “Run >Debug” to start af3.
-- You will be prompted to select a launch configuration. Select the one which matches
-your operating system.
+- You will be prompted to select a launch configuration. Select the one which matches your operating system.
 - In the *Plug-ins* tab, hit *Add required Plug-Ins*, *Apply*, *Debug*/*Run*
 - In you encounter errors in the console, check the FAQ section below
 
 Notes on cleaning up
 --------------------
 - You can clean your installation by deleting the installation root folder. However, you might want to keep the bundle pool.
-- If the installation fails with error that a certain plugin could not
-  be downloaded to the p2 cache (checksum), please select a different
-  p2 pool in the first page of the installer. Alternatively, you can
-  also delete the contents of the p2 pool , but beware: Old AutoFOCUS3
-  installations cannot be executed any more after doing this.
+- If the installation fails with error that a certain plugin could not be downloaded to the p2 cache (checksum), please select a different p2 pool in the first page of the installer. Alternatively, you can also delete the contents of the p2 pool , but beware: Old AutoFOCUS3 installations cannot be executed any more after doing this.
 
-FAQ
----
--   <u>Question</u>: Oomph installer cannot find update sites? (Problem
-    occurred on Windows)  
-    <u>Answer</u>: Deactivate proxy servers.
--   <u>Question</u>: I’m experiencing thousands of build errors! Some
-    are indicating missing eclipse packages.  
-    <u>Answer</u>: In this case, you have to reload the target platform
-    since eclipse got confused. Therefore, open the plugin
-    “target-definition” in the package explorer and open
-    `org.fortiss.af3.target.target`. Then, please wait until the target
-    platform is resolved. Afterwards, please click “Reload target
-    platform” in the top-right corner of the editor and a rebuild should
-    take place, removing any error markers. Maybe you have to re-execute
-    the last step to trigger the rebuild.
--   <u>Question</u>: Launching AF3 causes SIGSEGV on Linux and kills
-    Java VM within “libgdk-x11-2.0.so”. What now?  
-    <u>Answer</u>: In your launch configuration, on the ‘Environment’
-    tab, add a new variable called ‘SWT\_GTK3’ and set its value to ‘0’.
-    JVM is linked against GTK2, therefore we need to tell the launcher
-    not to use GTK3 with this setting.
--   <u>Question</u>: Rating files and git interaction seems very slow.  
-    <u>Answer</u>: Please ensure you completed step 1 of the
-    installation instructions. If the environment variable HOME does not
-    point to a local directory, heavy network traffic occurs that causes
-    these performance issues.
--   <u>Question</u>: Rating for files is shown, but I cannot change the
-    rating via the context menu.  
-   <u>Answer</u>: The rating can only be changed in the Package
-    Explorer view. Make sure, you are not using e.g. the Model Explorer.
--   <u>Question</u>On Windows, I encounter the the following exception when starting AutoFOCUS3. In particular, the DSE does not work.
-    ``java.lang.UnsatisfiedLinkError: [...]\plugins\com.microsoft.z3_2.18.[...]\lib\x64\msvcp120.dll: Can't find dependent libraries``
-    <u>Answer</u>Installing the update for the [Microsoft Visual C++ 2013 Update 5 Redistributable Package](https://support.microsoft.com/en-us/topic/update-for-visual-c-2013-and-visual-c-redistributable-package-5b2ac5ab-4139-8acc-08e2-9578ec9b2cf1) provides the missing runtime library.
+Updating an existing installation
+---------------------------------
+Our setup allows updating existing installations almost seamlessly. Updates are received automatically if you installed *AF3 - Developer installation* by using the link `https://git.fortiss.org/af3/fortiss-std-env/raw/master/oomph/af3.setup`
+during Oomph setup. 
+
+If there are any additional required to update from one version to another, they will be announced by mail on the AF3 developer list and also recorded here.
 
 Migrating from a file-based installation
-========================================
+-----------------------------------------
+While a URL-based installation is recommended for most developers (since it updates automatically, see above), a file based developer installation might be useful if you are working with the Eclipse platform itself (AF3 platform updates). In this case, you you may consider using a file-based         installation from a common (local) `fortiss-std-env` repository. It allows you test modifications to the setup easily by updating the setup file via git. Please remember to import this repository in your developer installation  manually to receive remote updates by pulling.
+
+In order to switch a file-based installation to an URL-based installation, perform the following steps:
 
 1.  Open the file
-    q<HOME>/.eclipse/org.eclipse.oomph.setup/setups/org.eclipse.projects.setup@
-    in a text editor of your choice. In Windows, substitute `<HOME>`
-    with `C:\Users\<Username>`; In Linux/MacOS with the home folder
-    `/home/<Username>`.
-2.  Search for the line mentioning `af3.setup` and replace the line with
-    the following:
+    `<HOME>/.eclipse/org.eclipse.oomph.setup/setups/org.eclipse.projects.setup` in a text editor of your choice. In Windows, substitute `<HOME>` with `C:\Users\<Username>`; In Linux/MacOS with the home folder `/home/<Username>`.
+2.  Search for the line mentioning `af3.setup` and replace the line with the following:
     `<project href="https://git.fortiss.org/af3/fortiss-std-env/raw/master/oomph/af3.setup#/"/>`
 3.  Start (or restart) an AutoFOCUS 3 developer installation and check
     that the corresponding Oomph file points to the update location:
     Open “Window/Edit >Preferences >Oomph >Setup Tasks” and
     check the window title.
-4.  Ensure that the option “Skip automatic task execution at startup
-    time” is UNCHECKED to receive updates.
+4.  Ensure that the option *Skip automatic task execution at startup
+    time* is *UNCHECKED* to receive updates.
+
+FAQ
+---
+-   **Question**: Oomph installer cannot find update sites? (Problem occurred on Windows)  
+    **Answer**: Deactivate proxy servers.
+-   **Question**: I’m experiencing thousands of build errors! Some are indicating missing Eclipse packages.  
+    **Answer**: In this case, you have to reload the target platform
+    - open the plugin *target-definition* in the package explorer and open
+    `org.fortiss.af3.target.target`.
+    - Please wait until the target platform is resolved.
+    - Click “Reload target platform” in the top-right corner of the editor and a rebuild should
+    take place, removing any error markers.
+    - Maybe you have to re-execute the last step to trigger the rebuild.
+-   **Question**: Launching AF3 causes SIGSEGV on Linux and kills Java VM within `libgdk-x11-2.0.so`. What now?  
+    **Answer**: In your *Launch configuration*, on the *Environment* tab, add a new variable called `SWT_GTK3` and set its value to `0`.
+    JVM is linked against GTK2, therefore we need to tell the launcher not to use GTK3 with this setting.
+-   **Question**: Rating files and git interaction seems very slow.  
+    **Answer**: Please ensure you completed step 1 of the installation instructions. If the environment variable HOME does not point to a local directory, heavy network traffic occurs that causes these performance issues.
+-   **Question**: Rating for files is shown, but I cannot change the rating via the context menu.  
+    **Answer**: The rating can only be changed in the *Package Explorer* view. Make sure, you are not using e.g. the *Model Explorer*.
+-   **Question**: On Windows, I encounter the the following exception when starting AutoFOCUS3. In particular, the DSE does not work.
+    ``java.lang.UnsatisfiedLinkError: [...]\plugins\com.microsoft.z3_2.18.[...]\lib\x64\msvcp120.dll: Can't find dependent libraries``
+    **Answer**: Installing the update for the [Microsoft Visual C++ 2013 Update 5 Redistributable Package](https://support.microsoft.com/en-us/topic/update-for-visual-c-2013-and-visual-c-redistributable-package-5b2ac5ab-4139-8acc-08e2-9578ec9b2cf1) provides the missing runtime library.