Notice: This Wiki is now read only and edits are no longer possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.
Difference between revisions of "Papyrus-RT/Developer/Design/0.8/Codegen Architecture Details"
Line 46: | Line 46: | ||
|org.eclipse.papyrusrt.codegen-feature | |org.eclipse.papyrusrt.codegen-feature | ||
|The code generator feature (separately installable) | |The code generator feature (separately installable) | ||
− | |||
− | |||
− | |||
|- | |- | ||
|org.eclipse.papyrusrt.rts-feature | |org.eclipse.papyrusrt.rts-feature | ||
Line 135: | Line 132: | ||
*The "generator starter" (<code>UMLRTGenerator</code>) | *The "generator starter" (<code>UMLRTGenerator</code>) | ||
− | + | :This class is the one that begins the generation process from the UI or the standalone, and invokes the "generation director" (below). | |
*The "generation director" (<code>CppCodeGenerator</code>): | *The "generation director" (<code>CppCodeGenerator</code>): | ||
− | + | :This class drives the generation process. More on this below. | |
*The "C++ code pattern" (<code>CppCodePattern</code>): | *The "C++ code pattern" (<code>CppCodePattern</code>): | ||
− | + | :This class provides an interface to the C++ language meta-model, as it is used in this transformation. | |
− | + | :It produces and keeps track of which C++ element has been generated for any given (xtumlrt) model element. | |
*The <code>AbstractCppGenerator</code> base class: | *The <code>AbstractCppGenerator</code> base class: | ||
− | + | :This is the base class for individual code generators for specific UML-RT elements. | |
*The <code>GeneratorManager</code>: | *The <code>GeneratorManager</code>: | ||
− | + | :This tracks generator instances for different types of elements. | |
− | + | :It is a base class for Eclipse-based and stand-alone generator managers. | |
*The UML2 model translation classes: | *The UML2 model translation classes: | ||
− | + | :These translate a UML2 model into an xtUMLrt model. | |
+ | *<code>UML2ChangeTracker</code>: | ||
+ | :Responsible of keeping track of model changes | ||
*The actual generator classes for: [^1] | *The actual generator classes for: [^1] | ||
**Basic (Passive) classes (<code>BasicClassGenerator</code>) | **Basic (Passive) classes (<code>BasicClassGenerator</code>) | ||
Line 156: | Line 155: | ||
The following diagram shows the class diagram with the general structure of the code generator: | The following diagram shows the class diagram with the general structure of the code generator: | ||
− | [[File: | + | [[File:Example.jpg]] |
The generation director (<code>CppCodeGenerator</code>) is instantiated and run from the <code>UMLRTGenerator</code> in either the org.eclipse.papyrusrt.codegen.papyrus plugin (if executed within the Eclipse GUI) or from the org.eclipse.papyrusrt.codegen.standalone (if executed standalone). | The generation director (<code>CppCodeGenerator</code>) is instantiated and run from the <code>UMLRTGenerator</code> in either the org.eclipse.papyrusrt.codegen.papyrus plugin (if executed within the Eclipse GUI) or from the org.eclipse.papyrusrt.codegen.standalone (if executed standalone). | ||
Line 171: | Line 170: | ||
There are two versions of this class. One in org.eclipse.papyrusrt.papyrus, invoked from within Papyrus, and one in org.eclipse.papyrusrt.standalone, invoked from the stand-alone generator. | There are two versions of this class. One in org.eclipse.papyrusrt.papyrus, invoked from within Papyrus, and one in org.eclipse.papyrusrt.standalone, invoked from the stand-alone generator. | ||
+ | |||
+ | This class contains references to: | ||
+ | *<code>UML2xtumlrtModelTranslator</code> | ||
+ | *<code>UML2ChangeTracker</code> | ||
+ | *<code>CppCodePattern</code> | ||
+ | *<code>CppCodeGenerator</code> | ||
==CppCodeGenerator== | ==CppCodeGenerator== | ||
Line 198: | Line 203: | ||
It mostly provides methods to create C++ model elements on demand for specific types of xtUMLrt model elements and contexts. These are stored in tables for future reference so that the same C++ model element is returned for the same xtUMLrt model element. This allows the generation of target C++ model elements to occur in any order, which means that code generators can be invoked in any order as they will obtain the C++ model elements when needed. | It mostly provides methods to create C++ model elements on demand for specific types of xtUMLrt model elements and contexts. These are stored in tables for future reference so that the same C++ model element is returned for the same xtUMLrt model element. This allows the generation of target C++ model elements to occur in any order, which means that code generators can be invoked in any order as they will obtain the C++ model elements when needed. | ||
− | For example, suppose that there is a <code>Capsule C1</code> with a port typed with a <code>Protocol P1</code> in the model. If the input list of target elements is <code>[P1,C1]</code>, then <code>ProtocolGenerator.generate</code> is invoked first on <code>P1</code>, which will in turn invoke the <code>CppCodePattern.getCppClass</code> method to obtain the C++ class model element for <code>P1</code>. Then, <code>CapsuleGenerator.generate</code> is invoked on <code>C1</code>, which will generate the code for its ports, and when doing so, it will try to obtain the C++ class for <code>P1</code> from the <code>CppCodePattern</code>, and since it was already computed for <code>P1</code>, it obtains the same C++ model element. If the input list of target elements was <code>[C1,P1]</code>, the C++ class for <code>P1</code> will be created when the <code>CapsuleGenerator</code> is translating <code>C1</code> and tries to obtain the | + | For example, suppose that there is a <code>Capsule C1</code> with a port typed with a <code>Protocol P1</code> in the model. If the input list of target elements is <code>[P1,C1]</code>, then <code>ProtocolGenerator.generate</code> is invoked first on <code>P1</code>, which will in turn invoke the <code>CppCodePattern.getCppClass</code> method to obtain the C++ class model element for <code>P1</code>. Then, <code>CapsuleGenerator.generate</code> is invoked on <code>C1</code>, which will generate the code for its ports, and when doing so, it will try to obtain the C++ class for <code>P1</code> from the <code>CppCodePattern</code>, and since it was already computed for <code>P1</code>, it obtains the same C++ model element. If the input list of target elements was <code>[C1,P1]</code>, the C++ class for <code>P1</code> will be created when the <code>CapsuleGenerator</code> is translating <code>C1</code> and tries to obtain the corresponding C++ class for the protocol, while the execution of <code>ProtocolGenerator.generate</code> will obtain that class as it has already been computed. |
+ | |||
+ | |||
+ | ==UML2ChangeTracker== | ||
+ | |||
+ | TBA | ||
+ | |||
+ | ==The model element generators== | ||
+ | |||
+ | ===CapsuleGenerator=== | ||
+ | |||
+ | TBA | ||
+ | |||
+ | ===CapsuleGenerator=== | ||
+ | |||
+ | TBA | ||
+ | |||
+ | ===ProtocolGenerator=== | ||
+ | |||
+ | TBA | ||
+ | |||
+ | ===StateMachineGenerator=== | ||
+ | |||
+ | TBA | ||
+ | |||
+ | ===CompositionGenerator=== | ||
+ | |||
+ | TBA | ||
+ | |||
+ | |||
+ | ---- | ||
[1]: The generators for state machines and the overall model composition are defined in the org.eclipse.papyrusrt.codegen.statemachines and org.eclipse.papyrusrt.codegen.structure plugins respectively. | [1]: The generators for state machines and the overall model composition are defined in the org.eclipse.papyrusrt.codegen.statemachines and org.eclipse.papyrusrt.codegen.structure plugins respectively. |
Revision as of 14:21, 20 August 2015
Contents
Overview
The code generator input is a UML2 model (org.eclipse.uml2) with the UML-RT profile applied to it. The output is a CDT project (C++).
More precisely, the input to the generator is a list of UML2 elements that have changed. When invoked from within Papyrus, the tool keeps track of which elements have changed since the last generation.
There are two intermediate meta-models:
- xtUMLrt: a meta-model that simplifies UML-RT and contains a common core shared with xtUML.
- Cpp: a meta-model of a sub-set of C++.
The overall generation process is depicted in the following diagram:
The rationale for the intermediate models is as follows:
- The xtUMLrt meta-model is intended to simplify UML2, in order to simplify the generator itself, while allowing customization, isolating the generator from the toolset, and providing a common language that allows its eventual extension to support xtUML.
- The Cpp meta-model isolates the generator from issues such as formatting, body/header file generation, file regeneration avoidance, CDT project and makefile generation, etc.
The core of the code generator consists of separate sub-generators for different kinds of elements. Namely:
- Capsules
- (Passive) classes
- Protocols
- State machines
- Deployment composition/structure
With the exception of the state machine generator, these translate an xtUMLrt model directly into a C++ model. The state machine generator performs some further intermediate steps on the xtUMLrt model before generating the C++ model. These steps are detailed below.
Plugins
The following tables provide a description of the features and plugins that form the code generator.
Features/Releng | Description |
---|---|
org.eclipse.papyrusrt.releng | Feature packaging |
org.eclipse.papyrusrt | The top-level feature that groups all plugins |
org.eclipse.papyrusrt.codegen-feature | The code generator feature (separately installable) |
org.eclipse.papyrusrt.rts-feature | The RTS feature (separately installable) |
Plugins | Description |
---|---|
org.eclipse.papyrusrt.codegen | The top-level plug-in that provides the Activator |
org.eclipse.papyrusrt.codegen.cpp | The core of the generator. Includes Capsule, Class and Protocol generators |
org.eclipse.papyrusrt.codegen.cpp.rts | Cpp model representation of the RTS elements |
org.eclipse.papyrusrt.codegen.cpp.statemachines.flat | State machine generator (from flat state machines) |
org.eclipse.papyrusrt.codegen.cpp.structure | Deployment structure generator |
org.eclipse.papyrusrt.codegen.lang | Base for language-specific plugins |
org.eclipse.papyrusrt.codegen.lang.cpp | The Cpp intermediate meta-model |
org.eclipse.papyrusrt.codegen.statemachines.flat | State machine flattener |
org.eclipse.papyrusrt.codegen.statemachines.flat.model | Extensions to the xtUMLrt meta-model for SM generation |
org.eclipse.papyrusrt.codegen.papyrus | Papyrus integration |
org.eclipse.papyrusrt.codegen.standalone | Standalone generator (does not require Eclipse instance running) |
org.eclipse.papyrusrt.protocoleditor | Papyrus protocol editor |
org.eclipse.papyrusrt.rts | The RTS (a clone of the umlrt.rts git repository) and UML-RT runtime model library |
org.eclipse.papyrusrt.utils | Utilities used by several plugins |
org.eclipse.papyrusrt.codegen.cpp.profile | New C++ profile |
org.eclipse.papyrusrt.xtumlrt.common.model | The common xtUMLrt meta-model (intermediate representation) |
org.eclipse.papyrusrt.xtumlrt.umlrt.model | The UML-RT-specific extensions to the common xtUMLrt meta-model |
org.eclipse.papyrusrt.xtumlrt.xtuml.model | The xtUML-specific extensions to the common xtUMLrt meta-model |
org.eclipse.papyrusrt.xtumlrt.platform.model | Base for platform/target specific meta-models |
org.eclipse.papyrusrt.xtumlrt.platform.cpp.model | Extensions for C++ generation |
Tests | Description |
---|---|
org.eclipse.papyrusrt.codegen.lang.cpp.test | Unit tests for the Cpp intermediate metamodel |
org.eclipse.papyrusrt.codegen.lang.test | Unit tests for the base lang plugins |
The generator core
The core is in the org.eclipse.papyrusrt.codegen.cpp plugin. This plugin includes:
- The "generator starter" (
UMLRTGenerator
)
- This class is the one that begins the generation process from the UI or the standalone, and invokes the "generation director" (below).
- The "generation director" (
CppCodeGenerator
):
- This class drives the generation process. More on this below.
- The "C++ code pattern" (
CppCodePattern
):
- This class provides an interface to the C++ language meta-model, as it is used in this transformation.
- It produces and keeps track of which C++ element has been generated for any given (xtumlrt) model element.
- The
AbstractCppGenerator
base class:
- This is the base class for individual code generators for specific UML-RT elements.
- The
GeneratorManager
:
- This tracks generator instances for different types of elements.
- It is a base class for Eclipse-based and stand-alone generator managers.
- The UML2 model translation classes:
- These translate a UML2 model into an xtUMLrt model.
UML2ChangeTracker
:
- Responsible of keeping track of model changes
- The actual generator classes for: [^1]
- Basic (Passive) classes (
BasicClassGenerator
) - Capsules (
CapsuleGenerator
) - Protocols (
ProtocolGenerator
)
- Basic (Passive) classes (
- Utility classes
The following diagram shows the class diagram with the general structure of the code generator:
The generation director (CppCodeGenerator
) is instantiated and run from the UMLRTGenerator
in either the org.eclipse.papyrusrt.codegen.papyrus plugin (if executed within the Eclipse GUI) or from the org.eclipse.papyrusrt.codegen.standalone (if executed standalone).
UMLRTGenerator
This class has a generate
method that receives a list or target EObject
elements, expected to be instances of org.eclipse.uml2.uml.Element
. Roughly, it does the following:
- Determine the set of related elements that have changed in the editor and add them to a set of changes
- Determine the folder where the code for the elements should be generated (and create a CDT project if needed)
- Translate each UML element to xtUMLrt (the intermediate representation)
- Invoke the
CppCodeGenerator.generate
method on the target list - Write (M2T) the resulting Cpp models to their target folders
There are two versions of this class. One in org.eclipse.papyrusrt.papyrus, invoked from within Papyrus, and one in org.eclipse.papyrusrt.standalone, invoked from the stand-alone generator.
This class contains references to:
UML2xtumlrtModelTranslator
UML2ChangeTracker
CppCodePattern
CppCodeGenerator
CppCodeGenerator
This class has the main method generate
that performs the generation.
The input is a list of target xtUMLrt model elements (typically translated from UML2 by the UI or the standalone generator). This input is passed to the constructor of CppCodeGenerator
.
The generate process itself performs the following steps:
- Eliminate from the target list, elements which have been explicitly marked as "not to be generated".
- "Collection": creates an instance of each code generator class (
AbstractCppGenerator
sub-classes) according to the type of element. This computes on the fly the transitive closure of affected elements. One generator instance is created for each model element.- For
Model
orPackage
elements, it recursively collects the generators for Entities (Classes and Capsules) as well as Protocols in the model/package. - For
Protocols
(non-built-in system protocols), creates aProtocolGenerator
and Capsule generators for each capsule in the model which has a port typed by the protocol. - For
StructType
elements, creates aBasicClassGenerator
- For
Capsule
elements, creates aCapsuleGenerator
, and aStateMachineGenerator
or anEmptyStateMachineGenerator
(if it has no state machine). Furthermore, if the capsule has been marked as the "top" capsule, it creates aCompositionGenerator
, to create the deployment structure.
- For
- Prune the list of generators to exclude those corresponding to elements that have already been generated and have not changed (according to the change-set)
- Generation: invokes the
generate
method on each individual generator instance. The result for each element is an element in the C++ model. - Consume (clean) the set of changed elements
The M2T step is performed by the UMLRTGenerator
class of either the org.eclipse.papyrusrt.papyrus plugin, if it is executed from within Papyrus, or from the org.eclipse.papyrusrt.standalone plugin, if it is invoked from the stand-alone generator.
CppCodePattern
This class provides an interface to the Cpp meta-model and is used to share C++ model elements generated by different parts of the generator.
It mostly provides methods to create C++ model elements on demand for specific types of xtUMLrt model elements and contexts. These are stored in tables for future reference so that the same C++ model element is returned for the same xtUMLrt model element. This allows the generation of target C++ model elements to occur in any order, which means that code generators can be invoked in any order as they will obtain the C++ model elements when needed.
For example, suppose that there is a Capsule C1
with a port typed with a Protocol P1
in the model. If the input list of target elements is [P1,C1]
, then ProtocolGenerator.generate
is invoked first on P1
, which will in turn invoke the CppCodePattern.getCppClass
method to obtain the C++ class model element for P1
. Then, CapsuleGenerator.generate
is invoked on C1
, which will generate the code for its ports, and when doing so, it will try to obtain the C++ class for P1
from the CppCodePattern
, and since it was already computed for P1
, it obtains the same C++ model element. If the input list of target elements was [C1,P1]
, the C++ class for P1
will be created when the CapsuleGenerator
is translating C1
and tries to obtain the corresponding C++ class for the protocol, while the execution of ProtocolGenerator.generate
will obtain that class as it has already been computed.
UML2ChangeTracker
TBA
The model element generators
CapsuleGenerator
TBA
CapsuleGenerator
TBA
ProtocolGenerator
TBA
StateMachineGenerator
TBA
CompositionGenerator
TBA
[1]: The generators for state machines and the overall model composition are defined in the org.eclipse.papyrusrt.codegen.statemachines and org.eclipse.papyrusrt.codegen.structure plugins respectively.