Configuring Transformation Configuration Properties

If you double-click on a TC file the transformation configuration editor will open. This editor lets you edit all the properties that are stored in the TC. The editor uses several tabs to group related properties. In this chapter we go through the TC properties as they appear in the TC editor.

Main tab

This tab contains the main properties that must be set-up for all kinds of TCs.

Artifact type specifies if generated C++ code should be compiled into an executable (default) or a library. There is also the choice of external library, which makes it possible to represent an external C++ library by means of a TC. This is useful in order to integrate the building of external code with building the model. See External Libraries for more information.

A special kind of executable TC is the “C++ Test Executable”. It works in the same way as a regular executable except that it does not specify a top capsule. This kind of TC is useful in order to build executables which run unit tests of model elements.

Note that some TC properties are only relevant for one particular artifact type. For example, a top capsule can only be specified for C++ executables.

Environment is usually set to "TargetRTS". However, if none of the generated C++ files will depend on anything from the RT services library you may instead set it to "Standalone". In that case the application will not link with the TargetRTS library and hence be smaller.

Sources specify which elements that will be transformed to C++ when building the TC. Elements that are contained in a specified source element will also be transformed. It can be convenient to specify a single top-level package as the only source element. Thereby the TC does not have to be updated when new elements are added to the package. However, this approach also means that some elements may be unnecessarily transformed and compiled, if the package contains elements that do not need to be translated to C++. This will increase the time it takes to build the TC. See Managing the Sources of a Transformation Configuration for more information about different ways in which you can manage the list of source elements for a TC.

The Target properties specify the name and location of an Eclipse CDT project to which generated C++ files will be written. This project can either be created and updated when the TC is built, or you may use an existing project which you maintain manually. In the latter case the properties on the “Target Configuration” tab are not used, and corresponding properties from the target CDT project is used instead for building generated code. Note that if you go for the latter approach you do not have all build properties located in the TC, but some are then located in the CDT project. The default and the recommended choice is to automatically generate the CDT project from the TC. Use then the Workspace output path property to specify the location of the CDT project and all generated code. You may use an absolute path for this property, but more commonly a relative path which then will be resolved against the Location property (which by default is the location of the workspace). Note that the name of the CDT project (either existing or generated) will be determined from the last segment of the output path. Read more about the "Automatically create and update target project" property in Building Generated Code.

You can document a TC by writing a comment in the Documentation field. The comment has no impact on building the TC.

References tab

A TC may reference other TCs. Use the buttons in this tab to add or remove TC references. You can navigate to referenced TCs by double-clicking on them.

Inherited transformation configurations lists other TCs from which this TC inherits. TC inheritance is a mechanism that allows you to group common properties in a single TC rather than to duplicate them into many TCs. See Transformation Configuration Inheritance for more information about transformation configuration inheritance.

Prerequisite transformation configurations lists other TCs which are "prerequisites" of this TC. When a TC is built, all its prerequisite TCs will first be built. This can for example be useful when building an executable TC that links with libraries built by other TCs (added as prerequisites). See Prerequisite transformation configurations for more information.

The relationships to other TCs that you create using the References tab are important in order to understand what happens when the TC is built. If there are many TCs and relationships it can be useful to visualize this graphically. You can do this by means of the Project Explorer context menu command Visualize - Explore in Graphs. Read more about this feature in the built-in help topic Model RealTime User's Guide – Articles – Editing - Diagrams - Visualizing TC relationships graphically.

Code Generation tab

This tab contains all properties that control how to translate the source elements of the TC to C++ code.

Top capsule is a property that is only available for an executable TC. It specifies which capsule that should be automatically incarnated when the executable is run. The top capsule is hence the entry point of the application. The top capsule is always a source element of the TC (explicitly or implicitly), or is located in one of the source elements.

Compile data classes individually controls how data classes (i.e. passive classes) are compiled. By default this property is set, which means that each data class will be built separately by a dedicated rule in the generated makefile. It can look something like this:

DataClass$(OBJ_EXT) : ../DataClass.cpp ../UnitName.h ../DataClass.h
    @$(FEEDBACK) Compiling Doc_target:DataClass
    $(1_CC) $(CC_HEAD) $(1_CCFLAGS) $(1_INCPATHS) ../DataClass.cpp $(CC_TAIL)

If you set this property to false, then make rules for data classes will not be generated, and instead they will be included at the end of the generated unit file (by default called
UnitName.cpp):

#define PRAGMA_IMPLEMENTED
#include "DataClass.cpp"

The main reason for not compiling data classes individually would be to improve compilation time (compiling one big file can be faster than compiling several small files). However, if you use a build system that supports parallelization of make rules, then the opposite may be true.

Generate code qualifiers is by default turned off. If it is turned on an extra line will be generated before each user code snippet. This line contains the fully qualified name of the UML element to which the code snippet belongs. This information can make it easier to understand the connection between generated C++ code and the model. It can also be used by 3rd party tools that analyze generated C++ code.

Here is an example of what a generated user code snippet could look like with this property turned on. The first line will not be generated when this property is off. 

// ELEMENT: HelloWorld::HelloWorld::State Machine::Region1::Initial::Initial
//{{{USR platform:/resource/DoxygenTest/HelloWorld.emx#_xjldcPkAEeGEhK1G362qaA
log.log("Hello World from C++ Capsule");
context()->abort();
//}}}USR

Generate fully qualified state names can be useful to set if you have hierarchical state machines where the same state name is used more than once. The rtg_state_names array in generated code will then contain fully qualified state names which can make debugging and trouble-shooting easier.

Optimize handling of frequent triggers is an optimization property for generating C++ code that is more efficient in handling frequently triggered state machine triggers. If you know that some triggers in your capsules' state machines get triggered much more frequently than others, you can mark those triggers with the <> keyword. When this property is set the generated rtsBehavior function will contain special if-statements for matching the current state, and the event and port of the current message, with the state, event and port of the frequent triggers. These if-statements are placed early in the rtsBehavior function to ensure that as little code as possible needs to execute when dispatching a message for a frequent trigger. Here is an example of what such an if-statement may look like:

if (/* frequent trigger*/ LIKELY(stateIndex == 4/*Initial*/ && portIndex == 2/*p*/ && signalIndex == PROTO::Base::rti_IE1) )
{
    chain3_e1();
    return;
}

Note that the code uses a macro LIKELY which is generated into the unit name header file. For GCC the macro is defined like this to give the compiler a hint that it's likely that the condition will be true:

#define LIKELY(x) \_\_builtin\_expect((x),1)

The property Context sensitive library build can be set in order to optimize the build of prerequisite library TCs so that their lists of source elements are filtered to avoid building elements that are not referenced by the source elements of the built TC. Each library will hence be analyzed to determine what parts of the library that are necessary in the context of the built TC, and only those parts will be built. This can significantly speed-up the build of a TC with prerequisite TCs. See Context Sensitive Library Builds for more information about this feature.

Default arguments is a property that is only available for a TC that builds an executable or test executable. It specifies the default command-line arguments to use, in case the executable is started without providing any command-line arguments. The arguments should be a comma-separated list of valid C++ strings. Here is an example:

Output subdirectory is usually left empty. However, if you target the same CDT project from multiple TCs you may want to place the code that is generated from each TC into a separate subdirectory, in order to avoid naming conflicts between generated files and to make the structure of the CDT project more clear.

Unit name specifies the base name of the "unit" files. By default this property is "UnitName" which means that the unit files will be called "UnitName.cpp" and “UnitName.h”. The unit files contain certain information that applies to the whole unit of code that is generated from a TC. For example, you will find the mapping of logical threads to physical threads in “UnitName.cpp”. The RTMain::entryPoint() function, which is the generated application's entry point, is also located there.

The unit header file is included in each generated implementation file.

Unit subdirectory is usually left empty, but in case you want the unit file to be generated into a specific subdirectory you can specify it here. One reason for using this property could be that the specified unit file name clashes with the name of another generated file.

Include unit header file without subdirectory path can be set to just use the name of the header unit file in #include directives, without the unit subdirectory path. The unit header file is included in each generated C++ file, and by default the #include directive looks like this:

#include <unit-sub-dir/UnitName.h>

However, if this property is set the unit subdirectory path is omitted, and the #include directive will instead be:

#include <UnitName.h>

This is useful in case the preprocessor include path contains the unit subdirectory.

Comment style specifies what comment style to use for documentation comments in generated C++ code. A documentation comment is the text you can enter in the Documentation property tab when selecting an element in the model. By default C++ style comments (// …) will be used. The code generator also supports two comment styles that can be used with the Doxygen publishing tool: Doxygen_JavaDoc (/** … */) and Doxygen_QT
(/*! … */). Choose one of these if you plan to run Doxygen on generated code.

If documentation comments contain rich text (i.e. markup such as underlining, colors, etc.) they will be converted to plain text by the C++ code generator.

Common preface allows you to write some code that will be inserted verbatim into the header unit file (by default called "UnitName.h"). Since the header unit file is included by all files that are generated from the model, you can use the common preface to define or include definitions that should be available everywhere in generated code.

Capsule factory can be used for specifying a global capsule factory which will be used for creating and destroying capsule instances in case no more specific capsule factory is specified on a certain capsule part. You should specify a C++ expression here that evaluates to an RTActorInterface*. To learn more about capsule factories, see the article "Custom capsule constructors" in the Model RealTime documentation. You can find this document in the built-in Help under Model RealTime User's Guide – Articles – Modeling realtime applications.

C++ code standard specifies the C++ code standard which the generated code will comply with. By default the code standard is specified as a workspace preference (RealTime Development – Build/Transformations – C++ – C++ code standard) and you only need to set this TC property if you want to override the code standard for a particular build.

Copyright text may be used to insert a common comment block in the beginning of each generated file, for example a copyright text. Here is an example:

// Licensed materials - copyright ACME corp
// Copyright ACME Corp 2010, 2018. All rights reserved.

Target Configuration tab

This tab contains properties that control how to generate the makefile to be used for building generated C++ code. Note that if the “Target” properties on the Main tab specify an existing CDT project to use for building generated C++ files, then the properties in this tab are not applicable since the properties in the CDT project will be used instead. Also, if the “Artifact type” property on the Main Tab is set to “C++ External Library” then this tab will contain different properties as described in External Libraries.

Use absolute paths in generated makefile should normally be unset, but if set the generated makefile will use absolute rather than relative paths for some of its variables.

Target services library specifies the location of the RT services library to use. The default value of this setting is ${RSA_RT_HOME}/C++/TargetRTS which points at the location in the Model RealTime installation where the C++ implementation of the RT services library resides. If you have your own version of the RT services library, enter the path to it here.

If you have imported your TC from Rose RT, the RT services library in Rose RT will be used instead. If you prefer to use the implementation in Model RealTime instead, which is improved in many ways, you should therefore update this property after the import from Rose RT.

TargetRTS configuration specifies which target configuration to use. A target configuration is a specific version of the RT services library that is adapted to the specific target environment that is used. Read more about target configurations in the document “RT Services Library”. The target configurations that are shown in the drop down menu for this property are dynamically extracted from the specified “Target services library” directory. Hence, if you don't see any target configurations in the drop down menu, ensure that you have set-up “Target services library” to point to a valid directory that contains target configurations for the RT services library.

Make type specifies the dialect of the generated makefile. The following dialects are supported:

If this property is unset (or set to Default) the makefile dialect will be determined based on the OS that is used (“MS_nmake” for Windows, and “Unix_make” for Unix).

Compile arguments specifies additional arguments to use when compiling generated C++ code. For example, if you want to add debug information to compiled code you can specify the -g flag if using the GNU C++ compiler. Or use $(DEBUG_TAG) as a compile argument which will be expanded to the correct debug flag depending on compiler used.

Compile command is by default set to $(CC). This variable expands to the compiler to use, which follows from the property "TargetRTS configuration". If you want to use a different compiler than the one that is by default used for the selected TargetRTS configuration, then you can change this property.

Executable name specifies the name of the generated executable. This property is only available for executable TCs, and it is by default set to executable$(EXEC_EXT). The variable $(EXEC_EXT) expands to the file extension to be used for executable files on the target platform (which follows from the property "TargetRTS configuration").

Library name specifies the name of the generated library. This property is only available for library TCs, and it is by default set to library$(LIB_EXT). The variable $(LIB_EXT) expands to the file extension to be used for library files on the target platform (which follows from the property "TargetRTS configuration").

Inclusion paths allows you to specify additional include paths for the C++ compiler. Type each include path on a separate line. For example:

Note that you do not have to explicitly specify inclusion paths for the current target project or any of the prerequisite target projects, because these are added automatically by the makefile generator. For example, assuming that the above two inclusion paths were specified for a TC with a prerequisite TC "libTC", then the generated makefile would have the following inclusion paths:

    0_INCPATHS = \
    $(INCLUDE_TAG)../../libTC_target \
    $(INCLUDE_TAG).. \
    $(INCLUDE_TAG)C:/mylibs \
    $(INCLUDE_TAG)C:/path

The variable $(INCLUDE_TAG) expands to the compiler flag to use for specifying include paths (e.g. -I).

Link command specifies the link command to use. This property is only available for executable TCs, and is by default set to $(LD). This variable expands to the linker to use, which follows from the property "TargetRTS configuration". If you want to use a different linker than the one that is by default used for the selected TargetRTS configuration, then you can specify which linker to use through this property.

Link arguments specifies additional arguments for the linker.

Link order (custom) provides a way to control the link order for libraries when linking an executable. The default link order is specified in a workspace preference (RealTime Development – Build/Transformations – C++ – Link Order) and is by default:

$(USER_LDFLAGS) $(ALL_OBJS_LIST) $(USER_OBJS_LIST) $(UNIT_LIBS) $(USER_LIBS)

You may rearrange these variables if you need libraries to be linked in another order. Any value set for this TC property overrides the value of the workspace preference for that particular TC. Hence, if you want a particular link order to be used for all your TCs, you may instead change the value of the workspace preference.

Build library command specifies the command for building libraries. This property is only available for library TCs, and is by default set to $(AR_CMD). This variable expands to the command to use for creating a library, which follows from the property "TargetRTS configuration".

Build library arguments specifies arguments for the build library command. This property is only available for library TCs.

Make command and Make arguments specify which make command and arguments to use. The make command is by default $defaultMakeCommand which expands to the name of the make tool to use, which follows from the property “TargetRTS configuration”. By default the flag -s is used (silent make, without echoes). Separate the make arguments using a space.

Target configuration name maps to a folder in the target CDT project where all generated files that are not source code will be placed. This includes for example makefiles and the files that are produced by these makefiles (typically binaries). The property is by default set to “default”. If you target the same CDT project from multiple TCs you must ensure that all these TCs have different target configuration names to avoid file name clashes and accidentally overwriting files generated by one TC with files generated by another TC.

Top make command and Top make arguments specify the make command and arguments to use for the invocation of the top-level make file (called batch.mk). You may use these properties to execute some "pre-make" commands before the real build starts, for example by using a script as the top make command. It is only useful to set these properties if the workspace preference RealTime Development – Build/Transformations – Type of Generated Make Files is set to Recursive, because then the top-level make file will contain recursive calls to other make files. If these properties are empty, the properties “Make command” and “Make arguments” will be used instead. See Makefile Generation for more information about inclusive and recursive makefiles.

Compilation make insert can be used to insert custom contents into the generated makefile. The text that you enter in this field will be copied verbatim into the generated makefile, just before the make rules section. You can use this property to add user-defined rules, variables, directives etc. to the makefile. For more information about what variables that are available to use in the compilation make insert fragment refer to the generated makefile. Also see the file /rsa_rt/C++/TargetRTS/libset/default.mk.

User libraries allows you to specify custom libraries to pass to the linker. Type each user library file on a separate line.

User object files allows you to specify custom object files to pass to the linker. Type each object file on a separate line.

Threads tab

This tab contains properties that control which threads to use in the generated application, and how to map logical threads onto physical threads. See the document “RT Services Library” for more information about logical and physical threads.

By default there are two physical threads:

You may add and remove additional physical threads using the Add and Remove buttons.

For each physical thread you can set a few properties:

In the table “Logical threads” you can add logical threads with names that become available in the generated C++ code. These logical threads appear as a node under one of the physical threads in the “Physical threads” table. To map the logical thread to a different physical thread you can drag-and-drop it onto the desired physical thread. Alternatively you can use the drop-down menu in the "Logical threads" table:

Code tab

As already mentioned, this tab shows all properties that have been set in the TC. Each property with a value different from its default value is present. The properties are shown in JavaScript syntax and you can edit them as needed. Note, however, that the Code tab does not provide a full-fledged JavaScript editor. If you plan for extensive textual editing of TCs, you may prefer to install a dedicated JavaScript editor into Model RealTime, or edit them with an external JavaScript editor.

You can navigate from properties shown in the Code tab to the corresponding properties shown in the other tabs. Right-click on a property in the text and perform the command ”Navigate to property tab” shown in the context menu.

The Code tab includes a useful feature that automatically sorts properties upon saving a TC file. For this, the "Auto sort properties on save" setting in the workspace preferences at RealTime Development - Transformation Configuration Editor is always enabled by default. This guarantees that properties are sorted automatically when saving TC files in your UML application. Keep in mind that when this feature is active, comments at the top of a property will also be moved along with the property to its new position during sorting.

This functionality offers several benefits: