Prom - Project Management in KIELER

Topics

...

Overview

The KIELER Compiler (KiCo) can generate different code targets from models. For example it is possible to generate C and Java code from an SCT file. As a result KIELER has to integrate with existing development tools and practices for the C and Java world. In the context of embedded systems, the target device also varies heavily.

...

In the following it is explained in further detail how to use and extend these features.

...

Project Wizards

SCCharts can be compiled for example to C using the KIELER Compiler and there is existing tooling for the C language in Eclipse. Using the SCCharts project wizard, such existing tooling for a target language or platform can be re-used.

...

Which project wizard from existing tooling should be used and which files should be created afterwards can be configured in the Eclipse preferences. Pre-defined setups for various languages and target platforms can be created this way.

File Wizards

There are various file wizards for the DSL that come with KIELER. These create a file with some default content.

...

• SCCharts text files (sctx files)
• Build configurations (kibuild files)
• Simulation configurations (kisim files)
• Simulation visualization configurations (kivis files)
• Freemarker Templates (ftl files)
  
  

...

The Project Builder

The incremental project builder is run by Eclipse either in the background when resources changes (Project > Build automatically), or manually by the user (Project > Build Project). What and how files are built can be configured using a new DSL (kibuild files). Errors and warnings that occur during the build are added as markers to the resources where they occur, which is a known concept in the Eclipse IDE. For instance when working with Java, compiler errors are added as markers to files when they are saved. This is now also possible for SCCharts text files and provides faster compiler feedback to users, e.g. because a model can not be compiled, as long as the automatic build is active.

...

Note that if the Build automatically option is set, it is possible to (re-)start a simulation without the need to (re-)compile the corresponding model beforehand. This is because the simulation executable has been created in the background as part of the build and is updated if the model changes. This results in a faster code-test-workflow compared to the previous approach, in which a model was always re-compiled before its simulation was started.

Build Configuration via KiBuild

The new project builder is configured using a domain specific language, namely KiBuild. Corresponding to the actions that are performed during the build, its configuration consists of model compilers, simulation compilers and template processors. A template processor is either a simple template processor, wrapper code template processor or simulation template processor.

...

// Compile models to Java code
model compiler kico {
  outputFolder: kieler-gen
  outputFileExtension: java
  outputTemplate: assets/OutputTemplate.ftl
  compileChain: de.cau.cs.kieler.sccharts.netlist.simple
  whitelist: "ModelA|ModelB"    // Only compile models that match this regex

  // Generate C simulation for compiled models
  process simulation template {
    file: assets/JavaSimulation.ftl
  }
}

// Compile simulation code
simulation compiler java {
  libFolder: kieler-gen/org/json
  outputFolder: kieler-gen/sim/bin
  command: "javac -cp kieler-gen -d bin \"${file_path}\" "
  jarCommand: "jar cvfe \"./${outputFolder}/${executable_name}\" sim.code.${file_basename} -C bin . "
}

// Process a simple template
process template {
 file: Template.ftl
 target: Output.txt
}

// Process a template to generate a main file that can be deployed.
process wrapper template {
  file: Main.ftl
  target: kieler-gen/Main.c
  modelFile: MyModel.sctx
}

// Process a template to generate a simulation for a model that has been compiled with some other framework
process simulation template {
  file: assets/JavaSimulationForOtherModel.ftl
  target: kieler-gen/Sim_OtherModel.java
  variables: {    // These variables should be communicated to the outside
    input: a,b,c
    output: x,y,z
  }
  interfaceTypes: input, output  // Only communicate these interface types. In this case, internal variables are not communicated.
}

...

Project Drafts

Project drafts are used to provide default settings for project creation. They are configured in the preferences (Window > Preferences > KIELER SCCharts > Project Drafts).

...

The associated project wizard is run as part of the Prom project wizard and takes care of the actual project creation. Afterwards the model file is created and finally other folders and files are imported.

Placeholders

There are some placeholders that can be used in initial resources for projects, which are listed below.

Paths for imported resources

To import a resource (folder or file), its project relative path has to be specified. The resource will be created at this location in the project. Furthermore, it is possible to specify initial content for these resources. This is done in the field origin. Without an origin specifed, an empty resource will be created.

To specify intial content for a file, the origin has to be an absolute file path or an URI with the platform scheme of Eclipse. Such an URI has the form plaftorm:/plugin/a.plugin.name/folder/in/the/plugin/file.txt Specifying intial content for a folder is analog. Its origin has to be an absolute directory path or an URI in the form plaftorm:/plugin/a.plugin.name/folder/in/the/plugin

...

Wrapper Code Generation

When modeling a program for an embedded system, it is necessary to set inputs and outputs of physical components (sensors/actuators) to inputs and outputs of the model. This is typically done using wrapper code. However, wrapper code is often similar for a specific device and programming language.

...

To ease the modification of the template file, one can open it with the text editor the final code will be for. This will enable syntax highlighting and code completion for the langauge, but it will not show any errors. You can open the file for example with the Java Editor of Eclipse using Right Click > Open With > Other > Java Editor

Simulation templates

The task of the simulation code is to read the inputs from the KIELER user for the simulation, execute a tick, then send the outputs that have been produced back to KIELER. The communication with KIELER is done using a JSON format.

...

In conclusion, the simulation code generation is a special form of wrapper code generation. For a simulation template, the injected code snippets are not selected from annotations in the model. Instead code is injected in a specified form for all variables to communicate their states using a JSON format.

FreeMarker

The wrapper code injection is done using the open source template engine FreeMarker. A wrapper code snippet is basically a Macro definition of FreeMarker. The Macro is called when the corresponding annotation is found in the model file. The file extension of FreeMarker templates is .ftl.

...

Example for wrapper code generation from annotations:

Image Modified

...

Problem Solving

CDT Projects

When working with the CDT, the folder that contains the simulation code has to be excluded from the CDT build, because this code is compiled using the compiler specified in the kibuild file, and every simulation file has an additional main function, which is not the use-case that a CDT project is made for. These files are self contained and do not interact with other files in the CDT project, thus they should not be built.

...