yakindu/plugins/org.yakindu.sct.doc.user/help/02_Getting_Started/getting_started.textile

h1. Getting started

h2. Installation

h3. Prerequisites

The *Yakindu Statechart Tools 2* are built upon Java and Xtext. So you need to have installed a "Java Runtime Environment":http://www.oracle.com/technetwork/java/index.html and Xtext installed. The easier way to get this is to install the "pre configured Xtext contribution":http://xtext.itemis.com.

The *Yakindu Statechart Tools 2* need *Eclipse Indigo 3.7* or higher and *Xtext 2.0.1* exactly (no higher) to work correctly.

h3. Installing the YAKINDU-Plug-Ins

You install the Yakindu Plug-Ins from the update site: http://updates.yakindu.com/indigo/milestones. 

* Click *Help* > *Install new software...* and *Add..* the update site _Yakindu SCT2 milestones_ - http://updates.yakindu.com/indigo/milestones/
* On this update site you find two main items:
** Xtext integration utilities
*** Xtext GMF integration (XGI)
*** Xtext JFace integration (XJI)
*** Yakindu Base
** Yakindu SCT 2
*** Generator C
*** Generator Java
*** Yakindu SCT 2
*** Yakindu SCT 2 SDK

!images/updatesite_4.jpg!

The Xtext integration utilities provide Xtext functionality for Yakindu. Additionally to the base integration it also provides GMF and JFace integration. For more details check the documentation "XGI":#XGI and "XJI":#XJI.

You can select what code generators you need (Yakindu SCT 2) and if you need the Yakindu SCT2 SDK (for developers). For users only the Yakindu SCT 2 is sufficient.

h2. Yakindu SC Modeling perspective

For state machine modeling purposes open the Yakindu *SC Modeling* perspective by clicking *Window* > *Open Perspective* > *SC Modeling*. This perspective is optimized for statechart modeling. It consists of 
* "Project Explorer":PLUGIN_ROOT/org.eclipse.platform.doc.user/concepts/cnav.htm on the left
* "Outline":PLUGIN_ROOT/org.eclipse.platform.doc.user/concepts/coutline.htm View on the right
* YAKINDU Statechart Editor at the top
* "Problems":PLUGIN_ROOT/org.eclipse.platform.doc.user/concepts/cprbview.htm and "Properties View":PLUGIN_ROOT/org.eclipse.platform.doc.user/concepts/cpropview.htm at the bottom

!images/sc_modeling_perspective.jpg!


h2. Yakindu SC Simulation perspective

To simulate a state machine use the Yakindu *SC Simulation* perspective by clicking *Window* > *Open Perspective* > *SC Simulation*. This perspective is optimized for simulation purposes and consists of:

* "Project Explorer":PLUGIN_ROOT/org.eclipse.platform.doc.user/concepts/cnav.htm on the left
* "Outline":PLUGIN_ROOT/org.eclipse.platform.doc.user/concepts/coutline.htm view on the right top
* Simulation View on the right bottom
* Debug view at the top
* "YAKINDU Statechart Editor":PLUGIN_ROOT/org.yakindu.sct.doc.user/help/02_Getting_Started/getting_started.html?path=0_1_5#YAKINDUStatechartEditor at the bottom

!images/sc_simulation_perspective.jpg!

h2. Yakindu Xpand Generator Project

In the context of model driven software development generators play an important role. The generator transforms the model to either another model or text like code. Yakindu generators support multiple transform languages. One is Xpand. By clicking *File* > *New* > *Other...* > *YAKINDU Xpand Generator Project* you create a project optimized for writing a generator in Xpand. For more details regarding Xpand see: "Xpand documentation":"PLUGINS_ROOT/org.eclipse.xpand.doc/help/index.html.

!images/new_xpand_project_simple.jpg!

All you need to do is to give it a speaking name and click *Finish*. The setting *Configure for Plugin Export* is an option for plugin developers.

The newly created project has a package with an Xpand starting point: the _Main.xpt_. This file the includes the needed metamodels. It has the entrance Xpand statement that iterates all states in the model and prints the names in a text file.

h2. Yakindu Xtend2/Java Generator Project

The generator that transforms the state machine model into code or documentation can be written in Xtend2 and Java. Find a detailed description on Xtend2 in the "Xtend2 documentation":PLUGIN_ROOT/org.eclipse.xtext.doc/contents/01-Xtend_Introduction.html. Yakindu comes with a predefined project setting for such projects. To create such a project click *File* > *New* > *Other...* > *YAKINDU Xtend2/Java Generator Project*. 

!images/new_java_xtend_project.jpg!

Give the project a speaking full qualified name and name also the generator java class with a full qualified name. If you also want to use Xtend select *Use Xtend*. The result is a new project with an initial Xtend file and java class.

h2. YAKINDU Statechart Editor

With the YAKINDU Statechart editor you create or modify state models. The editor automatically opens on .sct files. To create a new YAKINDU statechart model click *File* > *New* > *Other...* > *YAKINDU Statechart model*. Give it a speaking name and click *Finish*. The newly created model opens in the statechart editor. Also the SC Modeling perspective opens.

!images/sc_editor_01.jpg!


The editor consists of three parts: 
* the graphic canvas to design the state machine
* the palette on the right that owns the elements to design the state machine 
* a textual modeling field on the left

You can use the textual modeling field to define internal behavior of states and declare events or variables. The language used here is called SText. The "SText reference":PLUGINS_ROOT/org.yakindu.sct.doc.user/help/concepts.html#SText explains this language.

Elements that cause problems get warning and error markers attached. For more details about the problems open the *Problems View*.

h2. Simulation View

The simulation view is an interactive view to watch and control the state machine simulation. To get it open the simulation perspective. 

Start a simulation by clicking *Run* > *Run*. 

!images/simulation_view_active.jpg!

During the simulation in the statechart editor the active state gets a red color. The previous transition is green. The simulation view shows the events that trigger the states. You can change values here to trigger events. Beneath the table there are two clocks. One for the _virtual time_ and one for the _real time_ and a slider to change virtual time.

You can also select an _event driven_ or _cycle based_ run configuration.

h2. YAKINDU SCT Nature

YAKINDU model projects are associated with the *YAKINDU SCT nature*. For general information regarding natures read the "project nature documentation":PLUGIN_ROOT/org.eclipse.platform.doc.isv/reference/extension-points/org_eclipse_core_resources_natures.html. On projects with *YAKINDU SCT nature* _.sct_ and _.sgen_ files are automatically build and checked for problems. So you get fast feedback during editing. You can toggle the SCT nature by right clicking *Configure* > *Add* or *Remove YAKINDU SCT Nature* on the project.


h2. XGI

XGI is an Xtext integration for GMF (=Xtext GMF integration). Technically the statechart editor builds on the Graphical Modeling Framework (GMF). Xtext is an eclipse framework for textual modeling languages. Xtext provides comfortable functionality like _syntax highlighting_, _code completion_, _live validation_ and more. XGI adds these features to SCT editor fields. The result is the following:

!images/sc_editor_code_completion.jpg! 

h2. XJI

XJI is an Xtext integration for JFace e.g. fields in the Properties View. It adds Xtext editor functionality like _syntax highlighting_, _code completion_, _live validation_ and others to these fields. This can be a great help especially for new users to YAKINDU SCT.