Configuring a generator

Configuring a generator Copy link to clipboard

As mentioned above, all generators can be set up and customized by a generator model. The following screenshot shows a sample configuration for the C code generator.

Sample generator model for the C code generator

The following sections describe core features, which are available for all code generators. Individual code generators usually support specific additional features; please see the respective code generator documentation for details.

Outlet feature Copy link to clipboard

The Outlet feature specifies target project and target folder for the generated artifacts. It is a required feature.

Example:

feature Outlet {
    targetProject = "SampleProject"
    targetFolder = "src-gen"
    libraryTargetFolder = "src"
    skipLibraryFiles = "false"
}

Target Project

targetProject (String, required): The project to write the generated artifacts to.

Target Folder

targetFolder (String, required): The folder within the target project to write the generated artifacts to. If a library target folder (see below) is specified, only the model-dependent artifacts are generated in the target folder. All artifacts in this folder will be overwritten during re-generation.

Library Target Folder

libraryTargetFolder (String, optional): The folder to write the model-independent artifacts to. If this parameter is not specified, these artifacts will be generated in the target folder (see above). All artifacts in this folder will be preserved during re-generation. Manual modifications of these artifacts will not be overwritten upon re-generation.

Skip Library Files

skipLibraryFiles (Boolean, optional): If you wish to exclude the static files from the code generation, i.e., those that are put into the libraryTargetFolder, you can set this value to true. If the value is false or not specified at all, the files are generated as usual. Currently supported for the Java, C and C++ generators.

OutEventAPI feature Copy link to clipboard

The OutEventAPI feature enables different generator features, which are used for out events.

Example:

feature OutEventAPI {
    observables = true
    getters = true
}

At least one of both options needs to be enabled.

Observables

observables (Boolean, optional): uses observables for out events. This allows to subscribe observers to out event observables. The observers will be notified whenever the out event is raised by the state machine. Additional infrastructure code is generated that implements the observer mechanism. Default true.

Getters

getters (Boolean, optional): uses getters for out events. Follows the API of SCT 3.x. Default false.

LicenseHeader feature Copy link to clipboard

The LicenseHeader feature specifies the license text to be added as a header to the generated artifacts. It is an optional feature.

Example:

feature LicenseHeader {
    licenseText = "Copyright (c) 2017 committers of itemis CREATE and others."
}

License Text

licenseText (String, required): License text to be added as a file header

FunctionInlining feature Copy link to clipboard

The FunctionInlining feature enables the inlining of expressions instead of generating separate functions or methods. This might reduce the readability of the generated code, but increases performance, because less operation calls are necessary. This is an optional feature and all parameters of the FunctionInlining feature are false by default, except the Inline Choices parameter which is true by default.

Example:

feature FunctionInlining {
    inlineChoices = false
    inlineEnterRegion = true
    inlineEntries = true
}

Inline Reactions

inlineReactions (Boolean, optional): inlines the expression for reactions

Inline Entry Actions

inlineEntryActions (Boolean, optional): inlines the expression for entry actions

Inline Exit Actions

inlineExitActions (Boolean, optional): inlines the expression for exit actions

Inline Enter Sequences

inlineEnterSequences (Boolean, optional): inlines the expression for state-entering sequences

Inline Exit Sequences

inlineExitSequences (Boolean, optional): inlines the expression for state-exiting sequences

Inline Choices

inlineChoices (Boolean, optional): inlines the expression for choices

Inline Enter Region

inlineEnterRegion (Boolean, optional): inlines the expression for region-entering sequences

Inline Exit Region

inlineExitRegion (Boolean, optional): inlines the expression for region-exiting sequences

Inline Entries

inlineEntries (Boolean, optional): inlines the expression for entries

Debug feature Copy link to clipboard

The Debug feature dumps the execution model to the target folder as an XMI model. It is an optional feature.

Example:

feature Debug {
    dumpSexec = true
}

Dump Sexec

dumpSexec (Boolean, required): dumps the execution model as XMI model (default: false)

Using properties and expressions in generator models Copy link to clipboard

An SGen generator model may assign values to properties and later use these properties in expressions. The following sample generator model uses the var keyword to declare the properties projectName, version, isBeta, and generateTimerService with their respective types and default values. The model then uses these values in feature clauses by referring to the properties:

GeneratorModel for create::java {

    var projectName : string = "light_switch"
    var version : string = "1.0"
    var isBeta : boolean = true
    var generateTimerService : boolean = true

    statechart myStateAutomaton {

        feature Outlet {
            targetProject = projectName
            targetFolder = "src-gen/" + version + (isBeta ? "beta" : "")
            libraryTargetFolder = "src"
        }

        feature GeneralFeatures {
            TimerService = generateTimerService
        }

    }
}

The syntax rules for expressions in generator models are the same as for statechart language expressions, see section "Expressions". However, expressions are constrained to a subset that semantically makes sense in the context of a generator model. That means that, for example, while you can use the + operator to concatenate strings, you cannot use statechart-related constructs like the after keyword or the active() built-in function.

In the properties definition section near the top of a generator model, a value assigned to a property must be given as a literal. More complex expressions are not supported there.

Built-in variables Copy link to clipboard

There are several built-in read-only variables which can be used in expressions in generator models:

SCTVERSION (String): the current version of itemis CREATE, for example, “3.4.0”.
TIMESTAMP (String): the current date and time as a localized string, for example “11.12.2017 17:08:14”.
USER (String): the name of the current user who started this instance of itemis CREATE (via System.getProperty("user.name")).
HOSTNAME (String): the host name of the machine on which itemis CREATE is running.
SHA256 (String): the hash of the referenced file (for example, the statechart file).
SCTFILE (String): path to the statechart file relative to the workspace.

Please note: Neither USER nor HOSTNAME should be used for any security-related tasks. Especially the username can be spoofed easily, if anyone wanted to.

Overriding variables in a headless build Copy link to clipboard

The values assigned to properties are default values only. That means, you can override them by different values when actually executing a generation model by way of running the headless code generator.

For example, the command to call the headless generator might look like this:

scc -m myGenmodel.sct -v version=2.0;isBeta=false

The name/value pairs specified by the -v option would override the corresponding default values of the properties in the generator model. In this case, the properties version and isBeta would be set to the values “2.0” and “false”, respectively. The variables projectName and generateTimerService would maintain their default values as specified in the SGen file.

Table of contents