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.
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.
Java Compiler Version 11
------------------------
Java Compiler Version 11+
-------------------------
The AF3 source must be compiled using a Java compiler version 11. We
recommend OpenJDK since we use it for building internally.
**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`)
- ... 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.
<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:
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:
-**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.
**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.
