yakindu/plugins/org.yakindu.sct.doc.user/src/user-guide/generating_code_headless.textile

h1(#hdls_headless_code_generation). Headless code generation

State machine code is fully derived from a statechart model, and section "Generating state machine code":../user-guide/generating_code.html 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.

bq.. *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"":#hdls_troubleshooting for help, ask a question in the "support forum":https://groups.google.com/forum/embed/?place=forum%2Fyakindu-user, or file a bug report to the "issue tracker":https://github.com/Yakindu/statecharts/issues.

###. CHECK: Does headless code generation still have some rough edges?




h2(#hdls_installation). Installation


h3(#hdls_the_scc_statechart_compiler). 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_:

bc. 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:

bc. scc -h

The output should be similar to the following:

bc.. 
--------------------------------------------------------------
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
p. 



h3(#hdls_integrating_custom_code_generators). Integrating custom code generators

YAKINDU Statechart Tools supports custom code generators as described in section "&quot;Custom code generators&quot;":../user-guide/generating_code#codegen_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.




h2(#hdls_generating_code). 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.

!images/docu_headless_directory_structure.png(Headless Directory Structure)!

Within our sample directory structure the generator model _project1/default.sgen_ contains the following:

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



h3(#hdls_generating_code_for_an_eclipse_project). 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:

bc. 
cd [somepath]/basedir/project1

Then invoke the statechart compiler without any parameters:

bc. 
scc

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

bc. 
--------------------------------------------------------
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: 

bc. 
[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.



h3(#hdls_using_scc_options). 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:

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

Linux:

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

macOS:

bc. 
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:

bc. 
--------------------------------------------------------
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

<code>_basedir_/project1/src-gen/</code>



h3(#hdls_available_scc_options). 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.


h4(#hdls_specifying_a_base_directory). Specifying a base directory

You can specify a base directory using the <code>-d _basedir_</code> 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:

<code><em>basedir</em>/<em>sgen.targetProject</em>/<em>sgen.targetFolder</em></code>


h4(#hdls_specifying_statechart_model_files). Specifying statechart model files

Use the <code>-m <em>models</em></code> 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 <code><em>basedir</em>/<em>model</em></code>.
* If _model_ is a folder, the generator will search recursively for all model files known by the statechart compiler within <code><em>basedir</em>/<em>statechart_model</em></code>.

*Default:* If the @-m@ option is not specified, this is equivalent to <code>-m <em>basedir</em></code>, i.e. all model files in and beneath _basedir_ are processed.


h4(#hdls_specifying_property_values). Specifying property values

Use the <code>-v <em>name1=value1;name2=value2;nameN=valueN</em></code> option to override properties _name1_, _name2_, _nameN_, specified in the generator models, by the given values _value1_, _value2_, and _valueN_, respectively. See section "&quot;Using properties and expressions in generator models&quot;":../user-guide/generating_code#codegen_using_properties_and_expressions_in_generator_models for details.




h2(#hdls_troubleshooting). Troubleshooting

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



h3(#hdls_troubleshooting_error_neither_sct_nor_eclipse_executable_found). [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.



h3(#hdls_troubleshooting_the_eclipse_executable_launcher_was_unable_to_locate_its_companion_shared_library). 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:

bc. 
--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:

bc. 
--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.