Contributing

1. Compilation of the complete GEMOC Studio

1.1. Introduction

The source code of the [GEMOC Studio](http://gemoc.org/studio/) is currently spread among different git repositories in Eclipse organization.

This project relies on the presence of the correct git repositories (cloned with the correct name) to locally build a working studio.

1.2. Usage

First checkout the git repositories :

git clone  https://github.com/eclipse/gemoc-studio
git clone  https://github.com/eclipse/gemoc-studio-modeldebugging
git clone  https://github.com/eclipse/gemoc-studio-execution-moccml
git clone  https://github.com/eclipse/gemoc-studio-moccml
git clone  https://github.com/eclipse/gemoc-studio-execution-ale
git clone  https://github.com/eclipse/gemoc-studio-execution-java

Note: the repositories must keep their names (Ie. do not change the destination folder name) as the maven pom file expects to find them at specific locations.

Generate the protocols code

cd gemoc-studio-modeldebugging/protocols/generators/ts/JSONSchema2APIProtocolGenerator
npm run build
npm run  generate

Then compile the Eclipse Studio using maven:

cd gemoc-studio/dev_support/tycho_full_compilation
mvn package -Dmaven.repo.local=$PWD/localm2

We use one options:

  • -Dmaven.repo.local=$PWD/localm2: use a folder called localm2 to cache all the external dependencies of the studio, instead of using the user local maven repository. Since the GEMOC Studio a full eclipse package and has around 1GB of dependencies, this avoids using this much space in a hidden folder of the user home dir.

If you prefer to use your own local maven repository (ie. in <HOME>/.m2/repository), remove the use of -Dmaven.repo.local, ie. use this command:

mvn package

If you already compiled and resolved all dependencies at least once (ie. if you filled your local maven repository with everything needed for the build), add the option -o to perform an offline only build, which is significantly faster since it skips checking all maven repositories online.

In the end, the result can be found in gemoc_studio/gemoc_studio/releng/org.eclipse.gemoc.gemoc_studio.product/target/products/, with one studio zip per platform.

The build also assemble complementary results:

  • an update site, available in gemoc_studio/gemoc_studio/releng/org.eclipse.gemoc.gemoc_studio.product/target/repository/
  • an archivable version of the web help; available in gemoc-studio/docs/org.eclipse.gemoc.studio.doc/target/publish/webhelp/

Note

You can save some time on the compilation in development mode using some of the following options of the mvn command line:

Note

The current versio compiles using Java11 and Java FX. You need to indicate the location of javafx using an environment variable JAVAFX_HOME indicating the location of your java fx installation.

1.3. Advanced usage using docker

If you have trouble to reproduce a bug in the CI or want to make sure that the CI will pass, you can run the maven build in a docker that mimic the CI environment.

1.3.1. build image

To do a full build using docker: go to the docker folder (/gemoc-studio/dev_support/full_compilation/docker), then call the command

docker-compose down && docker-compose up
or
docker build -t "gemoc/gemoc-full-compilation:latest" .

Changes commited in master branch are automatically built and deployed on docker hub: https://hub.docker.com/r/gemoc/gemoc-full-compilation

1.3.2. Manual launch

A standard full build is done using the command:

docker run -it -v $PWD/../../../..:/home/jenkins/src -v $PWD/cache-m2:/home/jenkins/.m2 --user 1000 gemoc/gemoc-full-compilation:latest ./build_gemoc.sh

where

  • $PWD/../../../.. points to the root containing all gemoc sources
  • --user 1000 makes sure to use your user uid (use id -u or `echo $UID`to get yours user uid if this isn’t 1000)

note: you must create the $PWD/cache-m2 folder before launching the docker command in order to avoid permission issues.

Once the full compilation has been done at least once (ie. and filled the m2 cache), you can run the system test only using the command

docker-compose run gemoc_full_compilation system_test_only

Or you can run a full build but including only the linux variant using:

docker run -it -v $PWD/../../../..:/home/jenkins/src -v $PWD/cache-m2:/home/jenkins/.m2 --user 1000 gemoc/gemoc-full-compilation:latest ./build_gemoc.sh linux

or

docker-compose run gemoc_full_compilation linux_offline

or

docker-compose run gemoc_full_compilation linux_no_system_test

or

docker-compose run gemoc_full_compilation linux_no_system_test_offline

1.3.3. Description of the docker env

The Dockerfile defines a docker image based on ubuntu 16.04 with maven, oracle java8, xvfb, and graphviz. It embeds an entrypoint.sh script that calls the maven command. The docker-compose.yml will mount the folder containing all gemoc repositories (ie. the place where you’ve done git clone) It also mounts a cache-m2 folder in order to speed up the compilation.

The docker-compose command is more or less equivalent to:

docker build -t gemoc/gemoc-full-compilation:latest .
docker run -v $PWD/../../../..:/home/jenkins/src -v $PWD/cache-m2:/home/jenkins/.m2 gemoc/gemoc-full-compilation:latest

Then you’ll have to manually prune unused containers after usage.

If for some reason you wish to access it interactively you can use the following command:

docker run -it -v $PWD/../../../..:/home/jenkins/src -v $PWD/cache-m2:/home/jenkins/.m2 --user 1000 gemoc/gemoc-full-compilation:latest /bin/bash

2. Compilation of the pom first jar

2.1. Introduction

Some of the components provided as part of the GEMOC Studio are now available as pomfirst. This means that the jar are compiled and provided using maven dependency system (while the Eclipse studio is compiled using manifest dependency information using tycho).

Only a subset of the components are provided as pomfirst. You can still use them in your pomfirst build but will need to rebuild the dependencies for maven. (You can also open a request https://github.com/eclipse/gemoc-studio/issues for a given jar you may require).

The source code of the [GEMOC Studio](http://gemoc.org/studio/) is currently spread among different git repositories in Eclipse organization.

This project relies on the presence of the correct git repositories (cloned with the correct name) to locally build a working studio.

2.2. Usage

First checkout the git repositories :

git clone  https://github.com/eclipse/gemoc-studio
git clone  https://github.com/eclipse/gemoc-studio-modeldebugging
git clone  https://github.com/eclipse/gemoc-studio-execution-moccml
git clone  https://github.com/eclipse/gemoc-studio-moccml
git clone  https://github.com/eclipse/gemoc-studio-execution-ale
git clone  https://github.com/eclipse/gemoc-studio-execution-java

Note: the repositories must keep their names (Ie. do not change the destination folder name) as the maven pom file expects to find them at specific locations.

Generate the protocols code

cd gemoc-studio-modeldebugging/protocols/generators/ts/JSONSchema2APIProtocolGenerator
npm run build
npm run  generate

Then compile and install the pomfirst component:

cd gemoc-studio/dev_support/pomfirst_full_compilation
mvn install

Note

Most of the pomfirst component are completely recompiled from the same sources as their tycho equivalent but using maven dependencies instead of platform target. This is NOT only a repackaging of the .class and ensure that the dependencies are all defined.

They typically use maven-resources-plugin to copy the java sources.

Note

gemoc-studio/dev_support/pomfirst_full_compilation/pom.xml is a convenient central place to compile all of them across the GEMOC repositories in one command.

3. Developing new features

3.1. Developing new Addons

[85]

GEMOC addons mecanism is the simpliest way to contribute new features to GEMOC. Most of the features in GEMOC have been developed using it.

Basically, it uses Eclipse plugin extension point in order to provide additional feature to an existing engine.

The main extension point is org.eclipse.gemoc.gemoc_language_workbench.engine_addon which allows to declare a new class that implements the IEngineAddon interface.

3.1.1. Create an Addon

Minimal steps to get an addons:

  • Create a plugin project (or contribute to an existing one)
  • In the MANIFEST.MF or plugin.xml editor, open the extensions tab, Add, uncheck "Show only extension from the required plugins", search for "gemoc" and select the org.eclipse.gemoc.gemoc_language_workbench.engine_addon extension point, accept to add the dependency to the plugin. (see Figure 63, “New Extension for Engine Addon screenshot”)
  • add an addon entry in the extension point (see Figure 64, “EngineAddon extension point details screenshot”) provide a name and a description that will help the end user to know if she wish to enable the addon or not in the launch tab when configuring her model execution.
  • Create the class implementing org.eclipse.gemoc.xdsmlframework.api.engine_addon.IEngineAddon (a click on Class*: in the extension editor allows to open a wizard that simplify this task)
  • you can now override any of the default methods of the interface (cf. Figure 57, “Execution Framework API Interfaces overview”). If the user select the addon in the launch tab, these methods will be called by the engine.
New Extension forEngine Addon screenshot

Figure 63. New Extension for Engine Addon screenshot


EngineAddon extension point details screenshot

Figure 64. EngineAddon extension point details screenshot


Tip

An Engine addon may be generic and apply to any language, but it can also be language specific. In that case, you should prefer to add its code in the project containing the dsl file of the language and declare it in the plugin.xml.

This way, the addon will be available only for this specific language.

Add language specific Engine Addon on DSL

Figure 65. Add language specific Engine Addon on DSL


This can be useful in order to create language specific GUI (with input/output) and complex model animation. (see Section 3.2, “Define an animation representation using an engine addon”)

Tip

In the extension declaration, setting Default to true will activate the addon by default when creating a new launch configuration. The user is still able to disable the addon manually.

3.1.2. Controling call to addon

Note

The calls from the engine to the methods of IEngineAddons block the model execution. Thus, except if this is the expected behavior, the addons should avoid to do complex/long running/blocking task directly in the

For a given notification to IEngineAddon (for example aboutToExecuteStep), the order of calls to all registered addons is by default not ensured.

However, an addon can declare some EngineAddonSortingRule in order to indicate if the addon mus be called before or after another addon for a given EngineEvent.

The other addon can be identified either via its id or any tag that has been associated to it.

Tip

When starting a model execution the console logs some informations about which addon has been enabled and when each addon will be called compared to other addons.

The implicit GemocDebug addon is in charge to lock the execution when it receives a pause command. Addons that displays some information on the UI may wish to be called before it in order to make sure to provide updated information.

This snippet show how to add a rule that enforce this.

public class MyAddon implements IEngineAddon {

	@Override
	public void aboutToExecuteStep(IExecutionEngine<?> engine, Step<?> logicalStepToApply) {
		// do some refresh action
	}

	@Override
	public List<EngineAddonSortingRule> getAddonSortingRules() {  1
		ArrayList<EngineAddonSortingRule> sortingRules = new ArrayList<EngineAddonSortingRule>();
		sortingRules.add(new EngineAddonSortingRule( this,
				EngineAddonSortingRule.EngineEvent.aboutToExecuteStep,
				EngineAddonSortingRule.Priority.BEFORE,
				Arrays.asList(IGemocDebugger.GROUP_TAG))); 2
		return sortingRules;
	}
}

1

create a rule to ensure good behavior with GemocDebugger. The debugger addon will stop the execution in this event, this make sure to be called before it in order to properly do the task (refresh the view, save info, etc)

2

use the group tag so this rule will work with any GemocDebugger implementation.

Tip

See Section 3, “GEMOC framework” for more details about the extension point and other supported features.

3.2. Developing new engines

[86]

As seen in Figure 49, “Components overview”, the framework is organized in several layers. The most complete layer is the GEMOC Framework which offers most of the advanced features. Thus, implementing an engine for a new technology consist in 2 main parts:

  • implementing subclasses for the classes from XDSML Framework in order to have the part dedicated to the Language Workbench,
  • and implementing subclasses for the classes from Execution Framework in order to have the part dedicated to the Modeling Workbench

4. Distributing new features

TODO add info about how to distribute contribution and new features

5. Documentation

[87]

The GEMOC documentation (this document) structure is designed to:

  • allow both online and eclipse help output,
  • display an outline that helps organizing contributions,
  • maintain the documentation sources as close as possible of the documented element in order to associate documentation commits to the code commits,
  • use a rich but human readable syntax,
  • ease modification.

As it supports include directives, we chose Asciidoc syntax with the appropriate tool chain.

Some of the diagrams are generated using plantuml.

The document is organized as follow:

Tip

In order to ease modifications, every files must start with a footnote allowing to retrieve the source file in the git repositories.

Tip

To edit the documentation we recommand the use of plantuml eclipse plugin and eclipse asciidoc editor . You can install them in an Eclipse using either the market place or the following update site: https://ascii-uml.github.io/eclipse/