Headless code generation

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, YAKINDU Statechart Tools 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.

Please note:

Headless code generation is a new feature the YAKINDU team wants to make available as quickly as possible. Since it is still at an early development stage it might still have some rough edges. If you encounter any problems, please consider section "Troubleshooting" for help, ask a question in the support forum, or file a bug report to the issue tracker.

Installation

The scc statechart compiler

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 YAKINDU Statechart Tools 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:

--------------------------------------------------------------
YAKINDU Statechart Tools Headless Generator ((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

Integrating custom code generators

YAKINDU Statechart Tools supports custom code generators as described in section "Custom code generators". These custom generators can also be executed by use of the headless code generator infrastructure. To do so, the custom code generator has to be installed as an Eclipse plugin within the distribution directory. The custom code generator will be used whenever a generator model ( .sgen file) is loaded by the headless generator infrastructure and references the custom code generator ID.

Generating code

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

Headless Directory Structure

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

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

Generating code for an Eclipse project

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.

--------------------------------------------------------
YAKINDU Statechart Tools Headless Generator ((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

Within the root folder of your YAKINDU Statechart Tools 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:

--------------------------------------------------------
YAKINDU Statechart Tools Headless Generator ((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

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

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

  1. It is used to evaluate the absolute paths to model locations, provided they are given as relative paths.
  2. 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

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 YAKINDU Statechart Tool PRO’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

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

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

[ERROR] Neither ‚SCT’ nor ‚eclipse’ executable found!

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 YAKINDU Statechart Tools stand-alone installation, the executable binary is named SCT. However, its name is eclipse if you have installed YAKINDU Statechart Tools 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

This error message is usually issued if you have installed YAKINDU Statechart Tools 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.