How-to generate statechart code for continuous integration builds
UPDATE: Since YAKINDU Statechart Tools 2.9.0 a command line interface is provided to integrate SCT code generation into continuous integration builds. Please have a look at the SCT user guide.
In case you are following the discussions of the YAKINDU Statechart Tools (SCT) community you probably noticed that one of the features often asked for is running SCT's code generators outside the Eclipse IDE context.
This feature is essential for a proper integration of SCT into e.g. an automated build process. Besides the simple possibility to generate code via a command line call, there is a further need to integrate state machine code generation into well-known build tools like Make, ANT, Maven or Gradle.
In the past time there were two different approaches mainly discussed by the community:
- Headless Equinox Application (running an OSGi application without UI)
- Standalone Java Application (without OSGi context)
Using an Equinox application
The first approach means executing the generators from within an OSGi context and reuse Eclipse and SCT components without big changes. The main challenges to get this solution running are properly initializing the Eclipse File System (EFS), the EMF and Xtext infrastructure as well as loading and executing the SCT models in an appropriate order.
This approach has already been investigated by Gabor Szarnyas. His solution is uploaded on GitHub where you can find further instructions on how to create an Equinox App for standalone generator execution. Thanks a lot for this!
Towards a pure Java solution
The second approach with preferably as few dependencies as possible is a more challenging one. Providing a solution which does not depend on the Eclipse runtime is not that easy, since SCT was developed as a set of Eclipse plugins and therefore has some coupling to Eclipse’s core APIs. Cutting these dependencies means to decouple the code from using functionality provided by the Eclipse core API, like for example the Eclipse file system with its workspace-project metaphor. This might sound easier than it actually is and involves refactoring our code base.
However, we rolled up our sleeves and put some effort in reworking internal APIs and decoupling core functionality. This work is ongoing and not finished. In order to make the generator APIs applicable for you we decided to provide a code example that can be executed as a pure Java application. It consists of a few simple setup steps.
This code snippet from our example shows the top-level steps required to run the standalone code generator:
- Setting up EMF and XText infrastructure (initLanguages() and initResourceSet())
- Initialize SCT specific extensions like SGen libraries and code generator implementations
- Loading involved statechart (.sct) and generator (.sgen) models
- Finally invoking the generator
You will find the example that executes the Java code generator attached as zip or in the SCT GitHub repository. The sample can be simply imported into Ecplise from repository or zip file by using the import wizard. A proper target file is shipped with the project.
Running custom code generators
The source code can easily be customized to your needs. Within the Eclipse project you will find everything needed to run the sample on top of the latest release 2.6.0. Within the main class ‘SCTStandaloneGeneration’ of the example, you will find the methods
- and loadSCTModels
that you have to patch for customizations. When executing the example, the workspace /org.yakindu.sct.standalone/workspace will be used which is itself part of the sample project for reasons of simplicity. You will notice that the XMIs needed for the SGen-libraries are placed in a folder called libraries and therefore are currently copies of the originals to keep deployment after customizations as easy as possible for now.
YAKINDU SCT 2.6 lays out the foundation for standalone code generation. The work on this topic will continue for release 2.7. We aim to provide a stable API along with a command line interface. The main efforts will be on deployment issues and extensibility by custom code generators and SGen-libraries.
Since our solution is not carved in stone we are especially interested in your feedback, so we can navigate the ship of standalone generation into a direction that serves your requirements best.
Since YAKINDU Statechart Tools 2.9.0 a command line interface is provided to integrate SCT code generation into continuous integration builds. Please have a look at the SCT user guide.