EMDW Model Compiler User Guide

Installation

Required Eclipse

• Eclipse IDE for Eclipse Committers (Mars)

Installing EMDW Model Compiler features from update site

• EMDW-Common and EMDW-MC composite update site
  • Release update site: http://static.incquerylabs.com/projects/ericsson/releases/emdw-0.2.0/
  • Milestone Update site: http://static.incquerylabs.com/projects/ericsson/milestones/latest/
  • Select and install the xUML-RT Model Compiler category
  • CI update site: http://static.incquerylabs.com/projects/ericsson/emdw-ci/
    • Warning: while we work hard to keep the CI build usable at all times, you may run into installation and usability issues!
• Categories:
  • xUML-RT Model Compiler: Installs the core EMDW-MC features and all of their essential requirements.
    • Note that compiling and running the generated code is not considered a feature and therefore the Eclipse CDT is not installed if you select all features of this category.
  • xUML-RT Model Compiler Developer Features: Includes a full-featured version of the tools needed for developing the EMDW framework
    • EMF-IncQuery SDK
    • VIATRA Tranformation API
    • Eclipse C/C++ Development Tools (CDT) (please note that if you would like to execute the generated C++ code segments within Eclipse you need this feature)
    • CUTE C++ testing framework

Some security warnings may appear regarding unsigned content, this is normal for Eclipse plugins not provided by Eclipse.org, just click OK. In addition, accept all licenses as well.

After the installation has completed and Eclipse has restarted, you should see the new features in the installation details window and in the Installation history.

Opening models with Papyrus

If you did not install CDT features

Papyrus has its own perspective defined for working with UML models. In the Project explorer related files of a given "model set" (files with same name as a UML model but using different extensions) are collapsed into a virtual element (the virtual element's name will be the same as contained elements'). You can open this virtual element like a directory to access the individual files. Note that double-clicking on any of these files will not open the Papyrus editor, instead use the Open action from the local menu. Since the Model Compiler generates additional files with the same name as the UML model, these will also be put under the model set (.xtuml, .trace and .cppmodel).

If you installed CDT features

In Papyrus perspective in the Project Explorer you will not see the model by default. Open Customize View... and remove the checkbox from Di view then you will see the original files (not the virtual element mentioned before).

Importing example projects

There is a simple model packaged up with the installation of EMDW. Just select New, Example... and then in the xUML-RT model examples category, select Advanced Ping-Pong example model.

Next, select the project from the list to add the example to your workspace.

The project contains an UML model that can be used to try out the model compiler, a readme describing the example and any special instructions (for example, to copy a prepared main.cc file into the generated source folder).

Invoking the code generation

The model compiler can be executed using the local menu of the Papyrus Model Explorer view when the selection is a Model object (this is the root element). Click on the Generate CPP code for selected UML model entry to generate the C++ code.

After the generation is complete, the workspace will contain a new project named com.ericsson.emdw.cpp.generated.code.<model_file_name>

The followings are not generated yet:

• any files related to elements outside of components (e.g. global classes or type definitions)

Compiling the generated code

The generated project contains a Makefile in the root directory and the code is set up with an empty main file so simply calling make in the command line is enough to compile the whole project.

Setting up the main file

In order to use the generated code, the generated main.cc file should be edited with the instantiation of those classes that are needed to start the application and the main loop to process events generated during the execution of a given component instance.

The following is a simply example from the Ping-Pong model available from the example projects and also in the repository on this link: https://github.com/IncQueryLabs/EMDW-Common/blob/master/examples/com.incquerylabs.emdw.example.pingpongsimple/main.cc

#include "PingPongSimple/Component/Component_def.hh"

int main(int , char **) {
    using namespace ::PingPongSimple::Component;

    Ping* pi = new Ping();
    Pong* po = new Pong();
    Component* comp = Component::get_instance();

    pi->R1_pong = po;
    po->R1_ping = pi;

    pi->perform_initialization();
    po->perform_initialization();

    for (int i = 0; i < 20; ++i) {
        comp->process();
    }

    delete pi;
    delete po;
}

Using external entities in the model

For using external entities with c++ implementation in the model, see Using external entities

For advanced users with experience in using CDT

You can import the generated project into CDT with selecting Import, Project from existing Makefile. This should set up the project with the proper CDT preferences and both compiling and running works from inside Eclipse. However, dealing with complexities like toolchains and paths may be required.

Troubleshooting

• Currently, only classes within components are supported (you can use packages both outside and inside components for hierarchy).
• In some cases, you may find that the xtUML model is not created or does not contain every information that you wanted to model in your UML model. This may be caused by not satisfying some of the assumed validation rules.
• The UML-to-xtUML transformation starts immediately after opening the Papyrus editor and modifications are mapped as they are made. However, you have to save your UML model in order to trigger the saving of the .xtuml file as well.
• In some cases, the C++ code generation may fail without writing anything on the disk or showing any errors. This may be caused by not satisfying some of the assumed validation rules.