Project

General

Profile

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

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 AdoptOpenJDK, a buildfarm sponsored by companies depending on Java.
  • Alternatively, you can also perform manual installation from the OpenJDK site.

Installation Procedure

  • Windows-only: Please ensure that the HOME variable is set (Keys: Windows + Pause -> Adjust settings -> Advanced -> Environment variables) or run this script to set the mentioned variable to the user's directory. It is read by the git implementation of eclipse. NOTE: If your user folder points to a network share, you will experience severe performance impacts, so choose a local folder instead!
  • Download the Eclipse Installer
  • Start the Eclipse installer and switch to Advanced Mode (upper-right symbol)
  • 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>
    • Bundle Pool: <Select a location for the bundle pool or leave the default>
    • Select the Next button to go to the Project page
  • On the Project page:
    • Note: If you have a stale <user> entry from a previous installation, check mark it and remove it using the Red X icon right of the filter text field
    • Hit the Green Plus icon right of the filter text field
    • 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 <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 the unzip feature for the installer.
    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 see all options
    • Customize the installation locations or accept the default (sub-folder to your user home)
    • Important for contributors: Enter your personal REST API key from the redmine page (this website):
      • Login to the current web page (top right), or register if you have not done so yet.
      • Open the My Account page (top right) in a new tab or browser window.
      • Click "Show" below the "API access key" header in the rightmost pane of the page.
      • Copy the key to the corresponding key field in the oomph installer (initialized with all 0s)
      • Keep "My Account" page open since you will need the key in a later setup step again.
  • Select Next
  • You see a list of tasks that will be executed. Just hit Finish.
  • You will be asked to confirm licenses.
  • NOTE: If an error occurs that warns 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 AutoFOCUS installations cannot be executed any more after doing this.
  • Wait until the projects are fully built and the IDE has updated the 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, clean (ONLY) the plugin "org.fortiss.tooling.kernel" such that the pseudo-errors dissappear.
  • 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!).

Note that You can clean your installation by deleting the installation root folder.
However, you might want to keep the bundle pool.

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 and click ok.

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 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.
  • 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.

Migrating from a file-based installation

  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: <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.