<commit_before>
p(edit-on-github). "Edit on GitHub":https://github.com/Yakindu/statecharts/edit/master/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 "&quot;Troubleshooting&quot;":#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

If you are working with the "Professional Edition":https://info.itemis.com/yakindu/statecharts/pro of YAKINDU Statechart Tools, the headless code generation feature is already included and no further installation procedure is required. You can skip this section and continue reading at "&quot;The scc statechart compiler&quot;":#hdls_the_scc_statechart_compiler.

As a user of the "Open Edition":https://info.itemis.com/download-yakindu-statechart-tools you can install the headless code generation feature from the YAKINDU Statechart Tools Professional update site.

bq.. *Please note:*

Don't worry! Even though the headless generation feature is coming to you from the YAKINDU Statechart Tools Professional update site, no license fees will be incurred. Headless generation is completely free to use, though not open source.

p. To install the headless generation feature into the open edition or another eclpse instance please follow the following steps.

* Open the "registration form":https://info.itemis.com/yakindu/statecharts/pro with your web browser. If you have never registered before, please fill in your name, profession, and e-mail address. Click on _Send_.
* You will receive an e-mail containing a download link. In that e-mail, click on _Download SCT Pro Edition_.
* Your personalized download page will open in your web browser, showing the following download options.

p(#hdls_fig_yakindu_statechart_tools_professional_edition_download_options). 

!(standard-image)images/docu_headless_downloadpage.png(YAKINDU Statechart Tools Professional Edition download options)!

p=. YAKINDU Statechart Tools Professional Edition download options

* Click on _Install from update site_. The browser will take to another page and display the URL of the YAKINDU Statechart Tools Pro update site. You will need it subsequently.
* In the Eclipse main menu, select _Help → Install New Software…_.
* The _Install_ wizard opens.
* Click on the _Add…_ button. The _Add Repository_ dialog opens.
* Paste the above-mentioned URL into the _Location_ text field. Enter a meaningful name into the _Name_ field, e.g. "YAKINDU Statechart Tools Professional".
* Click on _OK_.
* In the _Install_ wizard, open the _YAKINDU Statechart Tools Professional Edition_ entry.
* Select _YAKINDU Headless Code Generator_, see figure "&quot;Installing the headless code generation feature&quot;":#hdls_fig_installing_the_headless_code_generation_feature. Click on _Next >_.
* The _Install_ wizard displays all items to be installed, i.e. _YAKINDU Headless Code Generator_. Click on _Next >_.
* The license agreements for the software to be installed are displayed. Accept them and click on _Finish_.
* The headless generation feature is installed.

p(#hdls_fig_installing_the_headless_code_generation_feature). 

!(standard-image)images/docu_headless_updatesite.png(Installing the headless code generation feature)!

p=. Installing the headless code generation feature


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>{,<path>}…]
 -d,--baseDir <path>   Relative/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>{,<path>}…  A list of comma separated Relative/absolute paths
                              to model(s) used during execution. If not set
                              the runtime value of basedir is used.



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"
		}
	}
}

<commit_msg>#602 : add section 'Custom code generators' within headless docu (#1176)<commit_after>
p(edit-on-github). "Edit on GitHub":https://github.com/Yakindu/statecharts/edit/master/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 "&quot;Troubleshooting&quot;":#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

If you are working with the "Professional Edition":https://info.itemis.com/yakindu/statecharts/pro of YAKINDU Statechart Tools, the headless code generation feature is already included and no further installation procedure is required. You can skip this section and continue reading at "&quot;The scc statechart compiler&quot;":#hdls_the_scc_statechart_compiler.

As a user of the "Open Edition":https://info.itemis.com/download-yakindu-statechart-tools you can install the headless code generation feature from the YAKINDU Statechart Tools Professional update site.

bq.. *Please note:*

Don't worry! Even though the headless generation feature is coming to you from the YAKINDU Statechart Tools Professional update site, no license fees will be incurred. Headless generation is completely free to use, though not open source.

p. To install the headless generation feature into the open edition or another eclpse instance please follow the following steps.

* Open the "registration form":https://info.itemis.com/yakindu/statecharts/pro with your web browser. If you have never registered before, please fill in your name, profession, and e-mail address. Click on _Send_.
* You will receive an e-mail containing a download link. In that e-mail, click on _Download SCT Pro Edition_.
* Your personalized download page will open in your web browser, showing the following download options.

p(#hdls_fig_yakindu_statechart_tools_professional_edition_download_options). 

!(standard-image)images/docu_headless_downloadpage.png(YAKINDU Statechart Tools Professional Edition download options)!

p=. YAKINDU Statechart Tools Professional Edition download options

* Click on _Install from update site_. The browser will take to another page and display the URL of the YAKINDU Statechart Tools Pro update site. You will need it subsequently.
* In the Eclipse main menu, select _Help → Install New Software…_.
* The _Install_ wizard opens.
* Click on the _Add…_ button. The _Add Repository_ dialog opens.
* Paste the above-mentioned URL into the _Location_ text field. Enter a meaningful name into the _Name_ field, e.g. "YAKINDU Statechart Tools Professional".
* Click on _OK_.
* In the _Install_ wizard, open the _YAKINDU Statechart Tools Professional Edition_ entry.
* Select _YAKINDU Headless Code Generator_, see figure "&quot;Installing the headless code generation feature&quot;":#hdls_fig_installing_the_headless_code_generation_feature. Click on _Next >_.
* The _Install_ wizard displays all items to be installed, i.e. _YAKINDU Headless Code Generator_. Click on _Next >_.
* The license agreements for the software to be installed are displayed. Accept them and click on _Finish_.
* The headless generation feature is installed.

p(#hdls_fig_installing_the_headless_code_generation_feature). 

!(standard-image)images/docu_headless_updatesite.png(Installing the headless code generation feature)!

p=. Installing the headless code generation feature


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>{,<path>}…]
 -d,--baseDir <path>   Relative/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>{,<path>}…  A list of comma separated Relative/absolute paths
                              to model(s) used during execution. If not set
                              the runtime value of basedir is used.

h3(#hdls_custom_generator). Integrating custom code generators

YAKINDU Statechart Tools supports custom generators as described in "Custom code generators":../user-guide/generating_code.html#custom-code-generators. These custom code generators can be executed by use of the headless code generator infrastructure also. To do so the custom code generator has to be installed as an eclipse plug-in within the distribution where the headless code generator feature was installed as described in "Installation":#hdls_installation - thats it: the custom generator will be used whenever a generator model (*.sgen), loaded by the headless generator infrastructure, referencing 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"
		}
	}
}


{'fraction_non_alphanumeric': 0.07514974230394206, 'fraction_numerical': 0.001950132330408135, 'mean_word_length': 4.298523985239853, 'pattern_counts': {'":': 22, '<': 15, '<?xml version=': 0, '>': 19, 'https://': 12, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 22, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1894106', 'n_tokens_mistral': 3816, 'n_tokens_neox': 3642, 'n_words': 1699}