This Guide Article has been written for Version 2.1 of the DATAFLOW Software. For Previous Releases use the version selection in the navigation bar at the top of this page.

The Generator is usually called directly from DATAFLOW Designer. If it is used from the command line, then it is recommended to create a batch file. This file calls the Generator and passes one or more DSL files and the configuration directory to be used.

@ECHO OFF
Dataflow.Generator.App.exe -configdir ./config –SourceFile MyAp.dff –user test
pause

This batch file can then be configured as a pre-build process in your favorite IDE.

CLI Arguments

The code generator is controlled using a command line interface (CLI). The following table shows all supported arguments. The arguments are case insensitive.

CLI Arguments

Example output with no arguments

$ ./DffStudio.App.Generator.exe
DffStudio.App.Generator - Version 2.1.1.0

Usage: DffStudio.App.Generator[arguments]

Arguments:

-Help                               Displays this message and exits.
-Version                            Displays the version and exits.
-SourceFile [path]                  Defines the input file (mandatory).
-ConfigDir  [path]                  Defines the config directory (optional, defaults
                                    to working directory).
-CmdFormat  [dataflow|standalone]   Defines the output format (optional, 
                                    defaults to standalone).
-OverwriteHandlers                  Overwrites APHandler files.
-OverwriteTests                     Overwrites UnitTest files.
-Verbose                            Enables additional output
-SignIn [Email] [Password] [Server] Signs in to execute DATAFLOW Generator.
-SignOut                            Signs out the current user from all dataflow applications.
-User                               The username that is used to overwrite the 
                                    logged-in user’s e-mail address.

Configuration

The configuration is read from the given configuration folder or from the working directory, if not specified. The following configuration files are supported:

• Generator configuration
• Parser configuration
• Style configuration
• File header templates

Generator Configuration

The generator configuration controls the code generation. Changes to those parameters will lead to a change of functionality in the generated code. For all omitted parameters, the default value given below is used.

File:               generator.json

Version:        4

Generator Configuration Parameters

Example of a Generator Configuration

{
"GeneratorOptions": {
   "Version": 4,
   "Data": {
     "Language": "CPP98",
     "Platform": "STM32_F103_HD",
     "Runtime": "ARM_CORTEX_M3",
     "RuntimeVersion": "2.5",
     "RootNamespace": "dataflow.example",
     "ComponentNamespace": "components",
     "TypeNamespace": "protocols",
     "GenerateTests": true,
     "RootPathSrc": "src/MyApp/App",
     "RootPathTests": "src/MyApp/Unittest",
     "CppFolderForRootNamespace": true,
     "CustomCtorMaxArgs": 3
   }
}
}

Language

The following values are supported for the Language parameter:

This parameter can also be printed in the file header. See ‘File Header Templates’.

Additional languages may be added for future versions.

Platform

The following values are supported for the Platform parameter:

1) Startup controller is adapted to platform.

2) This feature has not been validated for the current release. Use it at your own risk.

This parameter can also be printed in the file header, see ‘File Header Templates’.

Additional platforms may be added for future versions.

Runtime

The following values are supported for the Runtime parameter:

1) Startup controller is adapted to runtime type.

2) This feature has not been validated for the current release. Use it at your own risk.

This parameter can also be printed in the file header. See ‘File Header Templates’.

Additional runtime types may be added for future versions.

RuntimeVersion

The RuntimeVersion parameter must define the major version of the supported runtime in the format ‘X.Y’. This will affect the generation of the startup controller. This parameter can also be printed in the file header. See ‘File Header Templates’.

Namespaces

The generator configuration allows you to define the namespace for all generated types and components. Each component can also add a sub namespace in its DSL description.

The final namespace of a component is defined as follows:

RootNamespace + ComponentNamespace + DSL Namespace

The final namespace of a type is defined as follows:

RootNamespace + TypeNamespace + DSL Namespace

Generate Flags

The generator only generates source files (for both types and components) when the GenerateSrc parameter is set to true.

The generator only generates unit test files (for both types and components) when the GenerateTests parameter is set to true.

File Paths

The generator will place each generated file at the configured location. The path can be configured individually for source, test and meta files.

The path for a source file is defined as follows:

RootPathSrc + Full Namespace (see above)

The path for a test file is defined as follows:

RootPathTests + Full Namespace (see above)

The path for a meta file is defined as follows:

RootPathMeta

C++ Test Framework

Defines the unit test framework for all generated C++ unit tests.

The following values are supported for the CppTestFramework parameter:

   1) All C++ unit tests are generated for the given unit test framework.

Test Categories

If supported by the configured test framework (see above), each generated unit test will be added to the given category using an attribute or similar mechanic of the test framework. The category can be specified for each generated artifact independently using the parameters TestCategoryProtocol, TestCategoryAP, TestCategoryAPC and TestCategoryAPIrq.

C++ Specific configuration

When the Language is set to C++11 or newer, the Cpp11TrailingReturnType parameter will enable the generation of trailing return types in the form:

auto method(int8_t arg) -> int32_t;

If set to false, the C++98 style is used:

int32_t method(int8_t arg);

Functions with the return type void are not affected.

Parser Configuration

The parser configuration controls the DSL parser. For all omitted parameters, the default value given below is used.

File:               parser.json

Version:        1

Parser Configuration Parameters

Example Parser Configuration

{
  "ParserOptions": {
    "Version": 1,
    "Data": {
      "FrameworkDirectories": ["../Imt.Base","C:\\src\\imt\\Imt.Base"]
    }
  }
}

Style Configuration

The generator configuration controls the generated coding style. Changes of those parameters will not change the functionality in the generated code. For all omitted parameters, the default value given below is used.

File:               style.json

Version:        3

Style Configuration Parameters

Example Style Configuration

{
  "StyleOptions": {
    "Version": 3,
    "Data": {
      "BraceStyle": "IMT",
      "IndentWithTabs": true,
      "IndentCount": 2,
      "HeaderFileHeaderTemplate": "./header.tmpl",
      "SourceFileHeaderTemplate": "./header.tmpl",
      "TestFileHeaderTemplate": "./header.tmpl",
      "CppDocStyle": "JAVADOC"
    }
  }
}

Brace Style

The following values are supported for the BraceStyle parameter:

Example ALLMAN

boid method(int a)
{
  if (a == 1)
  {
    doA();
  }
  else
  {
    doB();
  }
}

Example KR

boid method(int a) {
  if (a == 1) {
    doA();
  } else {
    doB();
  }
}

Example IMT

boid method(int a) {
  if (a == 1) {
    doA();
  }
  else {
    doB();
  }
}

When CppForceNewlineAfterInitializerList is set to true, the opening brace after a constructor initializer list is placed on a new line while ignoring the BraceStyle parameter.

Example

BraceStyle KR, CppForceNewlineAfterInitializerList False

DeviceCommandProtocol::DeviceCommandProtocol(void) :
    m_boolean(false),
    m_character(0U) {
    // Nothing to do.
}

BraceStyle KR, CppForceNewlineAfterInitializerList True

DeviceCommandProtocol::DeviceCommandProtocol(void) :
    m_boolean(false),
    m_character(0U)
{
    // Nothing to do.
}

Line Endings

The following values are supported for the LineEnding parameter:

Indentations

The code generator will write IndentCount number of spaces (ASCII 0x20) for each indention level. If IndentWithTabs is set to true, the same number of tabs (ASCII 0x0x11) will be used instead.

The number of indent levels can be configured independently for several cases:

IndentAccessSpecifiers will indent all access specifiers in C++ classes.

IndentBraces will indent braces x (x can be set by the user) times. This will not affect the contents of a block formed by the braces.

IndentBlockContents will indent the content of blocks x times. This will not affect the contents of namespaces or classes because there is a specific parameter for that.

IndentClassContents will indent the content of classes x times.

IndentCaseContents will indent the content of a case in a switch case statement x times. Note that a block inside a case is also indented with IndentBlockContents.

IndentCaseLabels will indent the case label in a switch case statement x times.

IndentNamespaceContents will indent the content of a namespace x times.

IndentInitializerLists will indent the constructor initializer list x times.

Examples

IndentCount                                          1

IndentWithTabs                                    True

IndentBraceContents                          0

IndentBraces:                                        0

IndentNamespaceContents               1

IndentCaseContents                           1

IndentCaseLabels                                0¨

namespace {
<tab>void Unit01AP::execute(const uint16_t protocolIdentifier, Deserializer& deserializer) {
<tab>switch(protocolIdentifier) {
<tab>case RuntimeProtocolIdentifiers::TIMER: {
<tab><tab>RuntimeTimerEvent timerEventArgs(deserializer);
<tab><tab>handleTimer(timerEventArgs);
<tab><tab>}
<tab>break;
<tab>default:
<tab><tab>// Ignores all other protocols
<tab><tab>ASSERT_DEBUG1(false, "Unknown protocol in Unit01AP.");
<tab><tab>break;
<tab>}
<tab>}
}

IndentCount                                          2

IndentWithTabs                                    False

IndentBraceContents                          1

IndentBraces:                                        0

IndentNamespaceContents               0

IndentCaseContents                           0

IndentCaseLabels                                0

namespace {
void Unit01AP::execute(const uint16_t protocolIdentifier, Deserializer& deserializer) {
˽˽switch(protocolIdentifier) {
˽˽case RuntimeProtocolIdentifiers::TIMER: {
˽˽˽˽RuntimeTimerEvent timerEventArgs(deserializer);
˽˽˽˽handleTimer(timerEventArgs);
˽˽}
˽˽break;
˽˽default:
˽˽// Ignores all other protocols
˽˽ASSERT_DEBUG1(false, "Unknown protocol in Unit01AP.");
˽˽break;
˽˽}
}
}

IndentCount                                          2

IndentWithTabs                                    False

IndentBraceContents                          2

IndentCaseContents                           0

IndentCaseLabels                                1

void Unit01AP::execute(const uint16_t protocolIdentifier, Deserializer& deserializer) {
˽˽˽˽switch(protocolIdentifier) {
˽˽˽˽˽˽case RuntimeProtocolIdentifiers::TIMER: {
˽˽˽˽˽˽˽˽˽˽RuntimeTimerEvent timerEventArgs(deserializer);
˽˽˽˽˽˽˽˽˽˽handleTimer(timerEventArgs);
˽˽˽˽˽˽}
˽˽˽˽˽˽break;
˽˽˽˽˽˽default:
˽˽˽˽˽˽// Ignores all other protocols
˽˽˽˽˽˽ASSERT_DEBUG1(false, "Unknown protocol in Unit01AP.");
˽˽˽˽˽˽break;
˽˽˽˽}
}

IndentCount                                          2

IndentWithTabs                                    False

IndentBraceContents                          1

IndentCaseContents                           1

IndentCaseLabels                                1

void Unit01AP::execute(const uint16_t protocolIdentifier, Deserializer& deserializer) {
˽˽switch(protocolIdentifier) {
˽˽˽˽case RuntimeProtocolIdentifiers::TIMER: {
˽˽˽˽˽˽RuntimeTimerEvent timerEventArgs(deserializer);
˽˽˽˽˽˽handleTimer(timerEventArgs);
˽˽˽˽}
˽˽˽˽break;
˽˽˽˽default:
˽˽˽˽˽˽// Ignores all other protocols
˽˽˽˽˽˽ASSERT_DEBUG1(false, "Unknown protocol in Unit01AP.");
˽˽˽˽˽˽break;
˽˽}
}

Padding Flags

The number and placement of spaces inside of braces, brackets and parentheses is controlled using the padding flags BracePadding, PracketPadding and ParenthesePadding.

The following flags are supported:

void method(int a,int b){

void method˽(int a,int b){

void method(˽int a,int b){

void method(int a,int b˽){

void method(int a,int b)˽{

void method(int a, ˽int b){

void method(int a˽,int b){

• The example is given for parentheses, but it will work the same way for the other paddings.

For operators and keywords, only the INSIDE_BEFORE and INSIDE_AFTER has an effect.

The flags can be combined, and there will be no more than one space at one of the possible locations.

Example

ParenthesePadding AFTER_OPEN,INSIDE_BEFORE,INSIDE_AFTER

void method(˽int a˽,˽int b˽,˽int c){

Documentation Style

The following values are supported for the CppDocStyle parameter:

Example JAVADOC

/**
* Concise description up to the first point.
* Description of detail, e.g., description of algorithm
* on several lines.
* @param inParam1 Description of the respective parameter.
* @param inParam2 Description of the respective parameter.
* @param inParamn Description of the respective parameter.
* @return (description of the return value)
* @exception (description of the exception) * @see (optional reference to other 
* functions or documents)
*/

Example QT

//! A normal member taking two arguments and returning an integer value.
/*!
\param a an integer argument.
\param s a constant character pointer.
\return The test results
\sa QTstyle_Test(), ~QTstyle_Test(), testMeToo() and publicVar()
*/

Static Check Excludes

The following values are supported for the CppStaticCheckExcludes parameter:

File Header Templates

The generator allows the definition of header templates (see Style Configuration). These are ASCII files with placeholders that are replaced by the values from the generator.

For all C++ Header files, the file from HeaderFileHeaderTemplate is used.

For all C++ Source files, the file from SourceFileHeaderTemplate is used.

For all C++ Unit Test files, the file from TestFileHeaderTemplate is used.

The following placeholders are supported:

Example of a File Header Template

(c) IMT - Information Management Technology AG, CH-9470 Buchs, www.imt.ch.
SW guideline: Tech Note for Coding Guidelines Version. 1.6

Generated by DffGenerator
Generated from $INPUT_FILE$ by $BUILDER_USER$

DSL Files

The generator uses version 2 of the DATAFLOW DSL. The complete syntax is specified in [3] and will not be duplicated in this document. This document can be provided by IMT AG if required.

Meta File

The generator writes a meta file for each generated artifact parsed from DSL. This file contains details on the generated files and the full path. This is used for integration in DATAFLOW Designer or other tools.

Glossary

[1] Types is a short form for Protocol and Enumeration

[2] Components is a short form for Active Part, Active Container and Active Interrupt

[3] Domain-specific-Language

Required Module: DATAFLOW Code

This Article has been written based on V2.1.1 of the DATAFLOW software. 
Latest update 2023-05-31 by WUM.