Headless code generation

Headless code generation Copy link to clipboard

State machine code is fully derived from a statechart model, and section Generating state machine code explains how to interactively run a code generator. Since release 2.9.0, itemis CREATE additionally provides a headless code generator infrastructure. This allows for code generation without a user interface which in turn allows to integrate code generation into continuous integration (CI) build environments.

Best practice is to generate code on the fly during a continuous integration build instead of cluttering your version control system with generated artifacts.

The headless code generator can simply be called from a command line and thus can be integrated with different CI tools easily. No matter if you are using Gradle, Maven or make, all you need is a Java runtime on your build machine.

The headless code generator is not capable to generate images yet.

Installation Copy link to clipboard

The scc statechart compiler Copy link to clipboard

The SCT installation directory contains the file scc (Linux, macOS) resp. scc.bat (Windows): the statechart compiler. Technically, it is a script file launching the SCT executable, passing proper parameters for headless code generation.

Please include the SCT installation directory in your PATH environment variable, so the scc command can be executed anywhere from a command-line shell!

The following Linux example assumes itemis CREATE to be installed in /opt/software/yakindu-sct:

export PATH="/opt/software/yakindu-sct:${PATH}"

Calling scc with the -h option prints the the integrated help information. In a command-line shell, enter the following command:

scc -h

The output should be similar to the following:

--------------------------------------------------------------
SCC - itemis CREATE State Chart Compiler ((c) by itemis AG)

          Visit http://www.statecharts.org
--------------------------------------------------------------
usage: scc [-d <path>] [-h] [-m <path(s)>] [-v <arg>]
 -d,--baseDir <path>    Relative or absolute path to the working directory that contains your statechart projects. If
                        not set, the current directory is used.
 -h                     Shows help content.
 -m,--model <path(s)>   A list of comma-separated relative or absolute paths to model(s) used during execution. If not
                        set, the runtime value of baseDir is used.
 -v,--variables <arg>   A list of comma-separated key/value pairs to override variables in SGen models. Example: 
                       -v key1=value1,key2=value2

Generating code Copy link to clipboard

For the purpose of this documentation we are assuming the following directory structure. This includes SCT-related files like generator models and statechart models.

Within our sample directory structure the generator model project1/default.sgen contains the following:

GeneratorModel for create::java {
	statechart default {
		feature Outlet {
			targetProject = "project1"
			targetFolder = "src-gen"
		}
	}
}

Generating code for an Eclipse project Copy link to clipboard

The most simple way to invoke the code generator on the command line is to generate the code for a single Eclipse project. Using a commend-line shell, change to the project directory you want to generate code. Example:

cd [somepath]/basedir/project1

Then invoke the statechart compiler without any parameters:

scc

Please make sure scc is on your PATH environment variable. Alternatively specify the path to the scc executable in the command.

--------------------------------------------------------
SCC - itemis CREATE State Chart Compiler ((c) by itemis AG)
	  Visit http://www.statecharts.org
--------------------------------------------------------
1 gen model(s) and 1 statechart(s) loaded.
Generating 'default' to target project 'project1' ...
default done.
Generated (1 of 1) gen model(s).

The statechart compiler will invoke the code generator for all .sgen files contained in the project directory. It will look them up recursively. You’ll find the generated code at the location specified in the .sgen file:

[somepath]/basedir/[sgen.targetProject]/[sgen.targetFolder]

In this case the statechart compiler determines whether a .project file is available in the current directory and will automatically adjust the generation target to be the parent of the actual project directory to ensure the parameters defined in an .sgen file are interpreted correctly.

Using scc options Copy link to clipboard

Within the root folder of your itemis CREATE installation enter one of the following platform-specific commands. The string [pathToBasedir] must be replaced by the concrete path to the base directory, i.e., the common parent directory of the project directories.

Windows:

scc -d [pathToBasedir] -m project1\default.sgen,project2\default.sct

Linux:

./scc -d [pathToBasedir] -m project1/default.sgen,project2/default.sct

macOS:

cd SCT.app/Contents/Eclipse/
./scc -d [pathToBasedir] -m project1/default.sgen,project2/default.sct

Please see the following sample output as a result of the command:

--------------------------------------------------------
SCC - itemis CREATE State Chart Compiler ((c) by itemis AG)
	  Visit http://www.statecharts.org
--------------------------------------------------------
1 gen model(s) and 1 statechart(s) loaded.
Generating 'default' to target project 'project1' ...
default done.
Generated (1 of 1) gen model(s).

As you can see the headless code generation has properly executed. The generated code will be placed into a folder depending on the values configured within your generator model file.

For our example this means the generated code can be found in

basedir/project1/src-gen/

Available scc options Copy link to clipboard

All parameters are essentially optional. The reason is that for a directory structure adhering to Eclipse workspace standards like projects within a root folder, or no additional hierarchies, everything can be calculated automatically.

Specifying a base directory Copy link to clipboard

You can specify a base directory using the -d basedir option. It is used for two major tasks:

It is used to evaluate the absolute paths to model locations, provided they are given as relative paths.
It is used to evaluate the respective generation target folders, depending on the values given in the generator models.

Default: If the -d option is not specified, this is equivalent to -d ., i.e., the current working directory will be the base directory.

The target folder of generated artifacts will be evaluated as follows:

basedir/sgen.targetProject/sgen.targetFolder

Specifying statechart model files Copy link to clipboard

Use the -m models option to select certain models known by the statechart compiler. Usually these will be .sgen or .sct files. However, other model files that are supported by particular code generators, can be specified, too, e.g., C header files for itemis CREATE Professional’s Deep C Integration. The -m option’s value can be absolute or relative, can be a file or a folder and can be a single value or a comma-separated list of values.

If model is a comma-separated list of values, the statechart compiler will handle each value as described for model in the subsequent bullet points.
If model is relative, it is evaluated as basedir/model.
If model is a folder, the generator will search recursively for all model files known by the statechart compiler within basedir/statechart_model.

Default: If the -m option is not specified, this is equivalent to -m basedir, i.e., all model files in and beneath basedir are processed.

Specifying property values Copy link to clipboard

Use the -v name1=value1;name2=value2;nameN=valueN option to override properties name1, name2, nameN, specified in the generator models, by the given values value1, value2, and valueN, respectively. See section "Using properties and expressions in generator models" for details.

Troubleshooting Copy link to clipboard

If the scc command fails, here are some tips and fixes.

[ERROR] Neither ‘SCT’ nor ‘eclipse’ executable found! Copy link to clipboard

If you encounter this error message on Linux, this means the scc command was neither able to locate a SCT executable binary nor an eclipse executable. This happens if the scc executable, which is really only a launcher, is not in the same directory as the SCT or eclipse executables. In a itemis CREATE stand-alone installation, the executable binary is named SCT. However, its name is eclipse if you have installed itemis CREATE from an update site into an already existing Eclipse installation. The scc launcher tries to find one of SCT or eclipse and launches the correct one.

The Eclipse executable launcher was unable to locate its companion shared library Copy link to clipboard

This error message is usually issued if you have installed itemis CREATE from an update site into an already existing Eclipse installation and you installed the latter using the Eclipse Installer / Oomph.

Fixing this is easy: You have to change a single line in the headless.ini file in the Eclipse installation directory.

At first, open the eclipse.ini file in the same directory and search for the --launcher.library line. Copy the path that is on the next line. The two lines might look like this:

--launcher.library
/home/user/.p2/pool/plugins/org.eclipse.equinox.launcher.gtk.linux.x86_64_1.1.400.v20160518-1444

You’ll find a similar entry like in the headless.ini as well, probably looking like this:

--launcher.library
plugins/org.eclipse.equinox.launcher.gtk.linux.x86_64_1.1.400.v20160518-1444

Replace the path in the headless.ini file with the path from eclipse.ini. After saving headless.ini, scc should work.

[ERROR] Cannot find any .project files Copy link to clipboard

Upon execution scc searches for .project files which are used to properly interpret generation target locations as specified in the sgen files. These .project files are hidden files that contain some meta information about your projects in your itemis CREATE workspace. If scc does not find these files you might have copied your models to another folder and missed to also copy these
files.

[ERROR] Couldn’t resolve reference to EObject Copy link to clipboard

This error usually denotes a configuration problem when using scc in combination with the deep C integration feature. For example, if you are referring to imported C elements in your statechart models, and the corresponding header files can no more be resolved on your CI build server, the linker is unable to find the referenced C elements and produces this error message. To overcome this problem, you might want to check if your settings in C/C++ General -> Path and Symbols do not contain any paths that do not exist on your build environment. Also make sure that scc can access these settings which are stored in the .cproject file.
p.

Table of contents