Skip to content

GitLab

Last edited by Sebastian Bergemann
Page history

Adding_a_new_plugin

AF3 Plugins Conventions

Naming conventions

We distinguish consistently between plugins concerning the AF3 modeling language and its user interface implementation.
The naming convention is

org.fortiss.af3.the_plugin

for the language (meta-model, semantic functionality), and

org.fortiss.af3.the_plugin.ui

for the presentation and user interaction implementation.

Top-level Packages

The modeling language plugins will adhere to the following list of top-level packages.

model: The EMF meta-model classes. This package is usually found in generated-src folder.
annotations: Implementation related to the annotation framework.
compose: Implementations of compositors.
constraint: Implementations of constraints.
generator: Implementations of generators (if the language supports that). Target language identifier is usually the next level of package names, e.g. generator.java.
prototypes: Implementation of prototypes.
simulator: Implementations of a simulator backend (if the language supports that).
utils: Utility classes and methods. Classes in this package only contain static implementations.

The user interface plugins will adhere to the following list of top-level elements.

editor: Implementations of editors.
editpart: Implementations of graphical editors’ parts.
handler: Implementations of model element handlers.
properties: Implementations of property sections.
simulator: Implementations of a simulator front-end (if the language supports that).
utils: Utility classes and methods. Classes in this package only contain static implementations.

Adding a new plugin

The addition of a plugin to AF3 mainly consists of adding the plugin to the AF3 repository, adjusting the developer product files and installer, and registering it at the maven/jenkins config files. The following section explain these steps in detail.

Preparational steps & checks

  1. Ensure that your plugin is entirely [code-reviewed](Check-list_for_Code ____Reviews): The plugin must be marked “green” in the eclipse package explorer. If not, ask a colleague (or several) to do a review of your plugin. The plugin(s) will only be added if they are “green”.
  2. Create a ticket in redmine (this page) about the integration of your plugin.
  3. Check that all resources that are required by your plugin are included in the Binary Build in build.properties (e.g., icons)
  4. In the META-INF of your plugin, set the version to 2.x.0.qualifier (x to be replaced to match the current version of AF3), the name of the plugin to your plugin name, and the name of the vendor to “fortiss GmbH”
  5. likewise, set plugin name and vendor in plugin.properties
  6. Especially for plugins that have been under development for a longer time, verify that the plugin is compliant with the plugin templates (e.g., builder configuration, scripts, directory layout, …)
    • fortiss-std-env/base-project/org.fortiss.af3.base.project.ui for model / functionality plugins
    fortiss-std-env/base-project/org.fortiss.af3.base.project.ui.zip for UI plugins

Adding an repository containing “unoffical” plugins to the AF3 repository.

  1. Close eclipse

  2. Ensure that the command line version of git is installed on your system (“git” on Linux/MacOSX, “MsysGit” recommended for windows).

  3. Create a new branch in the your local AF3 repository that matches the number of the issue you created before:

    git checkout -b <issuenum> # replace <issuenum>

  4. open a shell and go to the af3 repository of your eclipse installation (typically /autofocus3-master/git/af3).

  5. execute the followin sequence of commands, where “project-a” are the plugins to be integrated into “project-b”

    git remote add project-a https://git.fortiss.org/af3/project-a
git fetch project-a
git merge --allow-unrelated-histories project-a/master # or whichever branch you want to merge
git remote remove project-a

  6. afterwards, add the .settings submodule entry in the “.gitmodules” file located at the root of the af3 repo. this might have already be done during the merge. see the other entries about the formatting.

  7. upload the result to the server by issuing

    git push origin <issueNum>:<issueNum> # Replace <issueNum>

  8. Go to https://git.fortiss.org/af3 and log in. Create a merge request (MR) from your just uploaded branch to master.

Register the plugin with the developer product definitions

  1. Start eclipse.
  2. Create a new branch for developer product definition by right-clicking org.fortiss.af3.phoenix.product.feature and following the typical “switch to” procedure. (see Development Workflow)
  3. Add the plugin to org.fortiss.af3.phoenix.product.feature/feature.xml to the “require” section (keep lexicographic order!)
  4. Upload the result and create a MR in the af3 repository

Update Oomph installation script

  1. Import the plugin fortiss-std-dev into your local workspace: File >Import >Git >Local repository >Select the git folder of your eclipse installation (see above) >Select “fortiss-std-env” and finish the import.
  2. Create a branch for this plugin nambed by the issue number from the above steps.
  3. Open the Oomph setup file (oomph/af3.setup) in eclipse and go to “Working sets”.
  4. Add the plugin to the corresponding plugin set, e.g., “Behaviour”, if it is not yet captured by any of the existing regular expressions.
  5. Commit & push the result.
  6. Create a MR to master at https://git.fortiss.org/af3/fortiss-std-env

Adjust the Maven build process to consider the added plugins

  1. Perform a local installation for local AF3 RCP builds as described in the Local Build documentation.
  2. After a successful local build of the AF3 RCP, follow the steps described in Adding plugins / modifying the plugin list.

Adjust the Run Configurations to consider the added plugins

  1. Create a new branch for https://git.fortiss.org/af3/af3-products (according to your issue number).
  2. Add there in all three config files (win64.launch, linux64.launch, mac64.launch) your new plugins after the "selected_workspace_bundles" key similar to the already existing plugins (like <setEntry value="org.fortiss.tooling.base@default:default"/>).
  3. Commit & push the result.
  4. Create a MR to master at https://git.fortiss.org/af3/af3-products