Installation from Source Code

Installation from source code is advised when aiming at extending the framework or getting a deeper impression of its inner workings. The following sections explain some conceptual background and the procedure of installation.

Prerequisites

Some preparatory steps have to be performed in order to install DeltaEcore from source code.

Install Eclipse

Install the current release of Eclipse in either 32 bit or 64 bit (does not matter for DeltaEcore). As DeltaEcore builds upon Ecore, the easiest way is to get the “Eclipse Modeling Tools” release as it satisfies almost all modeling dependencies of DeltaEcore. The workspace for DeltaEcore will be created in the further process.

Install Subversive SVN Client

Install the current release of the Subversive SVN client. You may, in principal, install any other SVN client, but then the chckout process of the source code and setup of the workspaces has to be performed manually instead of mostly automatically with team project sets. Hence, using Subversive is highly recommended.

As Subversive has become an integral part of the Eclipse project, it is recommended to use the regular update site of the used Eclipse release (Subversive features in the Collaboration section) instead of the separate update site of the Subversive project.

The installation of Subversive requires the additional installation of an SVN connector.

Install EMFText

Install EMFText into your Eclipse to create textual languages for Ecore meta models used by DeltaEcore.

Important: Be sure to get the most recent version using the Update Site of EMFText as some of the features required by DeltaEcore have not yet made it to the official release:

EMFText Update Site:

General Concepts

Three Developer Roles

DeltaEcore is an Eclipse-based Framework for the generation of model-based delta languages. This circumstance leads to the fact that working with the source code of DeltaEcore means taking any one of three roles:

  1. Framework Developer: Extends DeltaEcore with new functionality. Will modify the source code of the framework.
  2. Delta Language Developer: Directly uses DeltaEcore to create new delta languages for source languages, e.g., DeltaJava for Java. Will create delta dialects (*.decoredialect) to extend the common base delta language of DeltaEcore with suitable delta operations for a particular language’s meta model.
  3. Variability Engineer: Indirectly uses DeltaEcore to apply delta languages to make language artifacts variable. Will create delta module (*.decore) files and use delta dialects by referencing them in the delta modules.

Three Workspaces

The distinction of the developer roles is essential due to the following reason:

Once deployed, neither of the roles needs to be aware of the creators logically before them as long as the DeltaEcore plugin with the relevant delta dialects is installed properly. However, when working with the source code directly, the relevant plugins are deployed dynamically, in order to foster immediate testing of the newly modified implementations. This results in a structure of tree workspaces:

  1. Framework: Workspace of the framework developer. When changes to the framework are to be tested dynamically, a runtime instance of Eclipse can be launched that leads to the Runtime workspace.
  2. Runtime: Workspace of the delta language developer. New delta languages can be created here for models that are registered in this instance (e.g., are defined in the framework workspace). When the defined delta languages are to be used dynamically, a new runtime instance has to be started leading to the RuntimeRuntime workspace.
  3. RuntimeRuntime: Workspace of the variability engineer. Delta languages can be applied to create variable artifacts.

Setting up the Workspaces

Create three workspaces in the same parent folder called:

  1. “DeltaEcore” (The framework workspace)
  2. “DeltaEcoreRuntime” (The runtime workspace)
  3. “DeltaEcoreRuntimeRuntime” (The runtime runtime workspace)

Workspace folders

The content of these workspaces will be created in the following sections by checking out the DeltaEcore source code.

Setting up the Framework Workspace

Setting up the framework workspace requires multiple steps. The following sections explain the procedure step by step.

Check out Framework Source Code

Download the Team Project Set for the Framework Workspace and save it locally to a temporary location. Open Eclipse in the framework workspace and choose File -> Import then select Team -> Team Project Set. In the following wizard page, select File and navigate to the previously downloaded team project set file. Click Finish and enter your FusionForge credentials when prompted. The check out of the source code and the setup of the workspace will take some time.

Importing a team project set into an Eclipse workspace

Selecting the downloaded team project set file

After successful completion, there should be all relevant projects for the framework workspace of DeltaEcore. However, they contain compile errors due to non-existent model code as this is not checked into source control and has to be recreated upon first install. Feel free to delete the previously downloaded PSF file as it’s no longer needed.

Note: For a better overview of the projects in the workspace, you can choose Top Level Elements -> Working Sets from the pull down menu of the package explorer and click ok.

Using working sets as top level elements

Generate Model Code

Many projects contain Ecore meta models that need source code to be generated. By convention, meta models and associated resources are located in a “models” sub folder of the project where applicable. To generate source code, the respective *.genmodel file has to be located within that folder and opened. Right click the root node of the genmodel and select Generate Model Code.

Generating the model code

The model code has to be generated for the following projects:

  • org.deltaecore.core.applicationorderconstraint
  • org.deltaecore.core.decore
  • org.deltaecore.core.decorebase
  • org.deltaecore.core.decoredialect
  • org.deltaecore.feature
  • org.deltaecore.feature.configuration
  • org.deltaecore.feature.configuration.migration
  • org.deltaecore.feature.constraint
  • org.deltaecore.feature.expression
  • org.deltaecore.feature.mapping
  • org.deltaecore.shellscript
  • org.emftext.language.docbook
  • org.emftext.language.ecoreid
  • org.emftext.language.umlid
  • eu.vicci.ecosystem.cl
  • eu.vicci.ecosystem.componentfaultdiagram.cfd
  • eu.vicci.ecosystem.goalstructuringnotation.gsn
  • eu.vicci.ecosystem.sft

Note: The order in which the projects are processed does not matter.

Generate Auxiliary Model Code

Some of the projects require additional code to be generated from the meta models, such as the edit or editor code. This code is generated in a similar way to the model code: Open the genmodel, right click the root node, but select Generate Edit Code or Generate Editor Code, respectively.

The edit code has to be generated for the following projects:

  • org.deltaecore.feature

The editor code has to be generated for the following projects:

  • org.deltaecore.feature

Generate Concrete Syntax Code

DeltaEcore uses multiple textual languages in the framework and as example notations. These textual languages were created using EMFText and need their respective source code generated. To generate source code for EMFText language locate the *.cs (concrete syntax) file in the model folder, right click it and select Generate Text Resource from the context menu.

Generating the concrete syntax code

The concrete syntax code has to be generated for the following projects:

  • org.deltaecore.core.applicationorderconstraint
  • org.deltaecore.core.decore
  • org.deltaecore.core.decorebase
  • org.deltaecore.core.decoredialect
  • org.deltaecore.feature
  • org.deltaecore.feature.configuration
  • org.deltaecore.feature.constraint
  • org.deltaecore.feature.expression
  • org.deltaecore.feature.mapping
  • org.deltaecore.shellscript
  • org.emftext.language.docbook
  • org.emftext.language.ecoreid
  • org.emftext.language.umlid
  • eu.vicci.ecosystem.sft

Note: If there are build errors marked within the *.cs files, the most likely reason is that you installed the official EMFText release but not the most recent version from the update site (see above).

Resolve Remaining Compilation Problems

Some projects may still contain compilation errors. Here are appropriate measures to deal with the problems.

 de.ovgu.featureide.deltaecore

(Only relevant if checked out manually.)
This project integrates DeltaEcore into FeatureIDE. The remedy to the compilation problems depends on whether you want to use this integration or not.

Set up Run Configuration for Runtime Workspace

Once all compilation errors have been resolved, it is now possible to start a runtime instance of Eclipse that uses the framework plugins. Create a run configuration for a new Eclipse instance with the following modifications:

Note that versions of the JVM starting at and above 8.0 do not support (or require) these arguments anymore.

  1. Under Main, use as Location the relative path to the previously created DeltaEcoreRuntime workspace.
  2. Under Arguments, …
    1. … change the VM arguments string “-Xmx512m” to “-Xmx1024m”
    2. …add to VM arguments the string “-XX:MaxPermSize=256m”

Setting runtime location

Setting runtime VM args

The changes of memory allocation in the runtime instance of Eclipse are not mandatory but alleviate the problem of running out of memory, which happens quite often with the modeling tools in general.

Finally, execute the run configuration to transition to the runtime workspace.

Set up the Runtime Workspace

The process of setting up of the runtime workspace is similar to that for the framework workspace but is a lot easier. To ease the setup process, leave the initially selected “Resource” perspective of Eclipse and go to the “Java” perspective by selecting Window -> Open Perspective -> Java.

Opening the "Java" Perspective

Check out Runtime Source Code

Download the Team Project Set for the Runtime Workspace and save it locally to a temporary location. Import the team project set into your workspace similar to before. The runtime workspace contains several projects that each define an example delta dialect.

Generate Delta Dialect Code

The example delta dialects of DeltaEcore each require a partial interpreter that is automatically plugged into DeltaEcore during runtime. To generate the respective source code, the *.decoredialect file has to be located. Right click the file and select Run As -> decoredialect Application.

Generating delta dialect code

The delta dialect code has to be generated for the following projects:

  • eu.vicci.ecosystem.cl.delta
  • eu.vicci.ecosystem.componentfaultdiagram.cfd.delta
  • eu.vicci.ecosystem.goalstructuringnotation.gsn.delta
  • eu.vicci.ecosystem.sft.delta
  • org.deltaecore.feature.delta
  • org.eclipse.emf.ecore.delta

Set up Run Configuration for Runtime Runtime Workspace

Set up the run configuration for a new Eclipse instance similar to before but now use as location the relative path to the previously created DeltaEcoreRuntimeRuntime workspace.

Finally, execute the run configuration to transition to the runtime runtime workspace.

Set up the Runtime Runtime Workspace

The process of setting up of the runtime runtime workspace is similar to that for the runtime workspace. Again, go to the “Java” perspective of Eclipse.

Check out Runtime Runtime Source Code

Download the Team Project Set for the Runtime Runtime Workspace and save it locally to a temporary location. Import the team project set into your workspace similar to before. The runtime runtime workspace contains several projects that each contain an example of using the delta dialects of the runtime workspace.

Use the Example Projects

The example projects each contain at least on *.decore file specifying delta modules that use the previously defined delta dialects to modify selected models to perform changes associated with variability.

Currently, DeltaEcore supports three general procedures to apply a set of delta modules to derive a particular variant:

  1. Raw mode: User has to select delta modules manually
  2. Integrated feature model mode: Uses the Hyper Feature Models of DeltaEcore and a mapping of feature expressions to delta modules.
  3. FeatureIDE mode: Uses FeatureIDE as front end and a mapping to delta modules for DeltaEcore as backend.

Only the raw mode is explained here briefly even though the other two options are more comfortable for end users. However, the raw mode introduces the least overhead in terms of additional procedures called in the framework and is, thus, most suitable during framework development.

To use variant derivation in the raw mode for the example projects, the following steps have to be performed:

  • Show the DeltaEcore Variant Creation View
    • Select Window -> Show View -> Other… from the Eclipse main menu.Selecting Show View -> Other...
    • Select Variant Creation from the category DeltaEcore.Selecting variant creation
    • The Variant Creation view of DeltaEcore appears.Showing variant creation view
  • Select delta modules used for variant derivation of one project
    • Click Add… and select a set of delta modules.Selecting delta modules
    • Click Browse… to select a folder where the respective variant should be located.Selecting variant folder
    • Click Create Variant and see the respective elements of the derived variants in the respective folder.Creating variant

Note: Explanation of the other methods of variant derivation will be explained at some future point and will be located in the general documentation section.