Changes for page Project Management

Last modified by Richard Kreissig on 2023/09/14 10:56
<
From version < 2.1 >
edited by ssm
on 2017/07/26 15:35
To version < 3.1 >
edited by aas2
on 2017/08/02 21:12
>
Change comment: There is no comment for this version

Summary

Details

Page properties
Author
... ... @@ -1,1 +1,1 @@
1 -XWiki.ssm
1 +XWiki.aas2
Content
... ... @@ -1,1 +1,228 @@
1 += Prom - Project Management in KIELER =
2 +
3 +**Topics**
4 +
5 +
6 +
7 +{{toc minLevel="2"/}}
8 +
9 +----
10 +
11 +== Overview ==
12 +
13 +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.
14 +
15 +Therefore the KIELER Project Management (Prom) has been developed. It eases the creation, compilation and deployment of projects, when using models that can be compiled via KiCo (e.g. SCCharts, Esterel). Furthermore it eases the creation of wrapper code, which is used to deploy, run, or simulate the model.
16 +
17 +The features provided by prom include:
18 +
19 +* Project and file creation **wizards**
20 +* An incremental **project builder** that performs several tasks, namely\\
21 +** Compilation of model files using KiCo
22 +** Template processing to generate code for deployment or simulation
23 +** Compilation of simulation code to an executable
24 +* A **DSL** **for configuration** of the project build
25 +
26 +In the following it is explained in further detail how to use and extend these features.
27 +
1 1  \\
29 +
30 +----
31 +
32 +== Project Wizards ==
33 +
34 +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.
35 +
36 +Therefore the actual project creation is delegated to another project wizard. Afterwards additional files are created within this newly created project by the SCCharts project wizard. For instance a model file and files for configuration of the build or templates for wrapper code might be added to the project. Further the created project properties are extended with information specific to SCCharts projects, e.g., that the Prom project builder should be used. This approach makes it possible to re-use project wizards from the CDT or JDT and get a working setup with a model file that can be compiled, simulated and deployed with low configuration effort.
37 +
38 +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.
39 +
40 +== File Wizards ==
41 +
42 +There are various file wizards for the DSL that come with KIELER. These create a file with some default content.
43 +
44 +File wizards exist for
45 +
46 +* SCCharts text files (**sctx** files)
47 +* Build configurations (**kibuild** files)
48 +* Simulation configurations (**kisim** files)
49 +* Simulation visualization configurations (**kivis** files)
50 +* Freemarker Templates (**ftl** files)
51 +\\
52 +
53 +----
54 +
55 +== The Project Builder ==
56 +
57 +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.
58 +
59 +Several actions are performed when a project is built:
60 +
61 +* Model files are compiled
62 +** Optionally a template is processed for each model to generate the simulation code for the model.
63 +* Simulation code is compiled to an executable, which can be started using the new simulation
64 +* Freemarker templates are processed to generate code.
65 +Depending of the type of the template, additional variables are injected into the template\\
66 +** //Wrapper code templates// are used to create the wrapper code for a specific model.
67 +Annotations on inputs and outputs in the model can be used to define which code snippets are injected as part of the build. These code snippets typically contain code to read or write the corresponding inputs and outputs.
68 +** //Simulation code templates// are used to create wrapper code for simulation of models.
69 +Thus it is a special form of wrapper code template. Instead of user defined annotations, the injected code snippets are determined by the variables in the model.
70 +This kind of template can be configured as part of a model compiler to automatically generate the simulation for all compiled models.
71 +** //Simple templates// are self contained and no additional variables are injected.
72 +
73 +If all of these are defined, an incremental project build could consist for example of the following steps:
74 +
75 +* Build a model file //A.sctx//\\
76 +** Afterwards process a simulation template to generate its simulation code //Sim_A.c//
77 +* Compile the simulation code //Sim_A.c// to an executable using gcc
78 +* Create wrapper code for the model, that is ready to be deployed
79 +
80 +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.
81 +
82 +=== Build Configuration via KiBuild ===
83 +
84 +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//.
85 +
86 +{{code title="Simple KiBuild Example" linenumbers="true"}}
87 +// Compile models to C code
88 +model compiler kico {
89 + outputFolder: kieler-gen // The folder, in which the compilation output is saved
90 + outputFileExtension: c // The file extension for compiled files
91 + compilationSystem: de.cau.cs.kieler.sccharts.netlist.simple // The system that determines the compile chain within the KIELER compiler
92 +
93 + // Generate C simulation for compiled models
94 + process simulation template {
95 + file: assets/CSimulation.ftl // A template for simulation code
96 + }
97 +}
98 +
99 +// Compile C simulation via gcc
100 +simulation compiler c {
101 + libFolder: kieler-gen/sim/lib // Create additional libraries required for compilation in this folder
102 + outputFolder: kieler-gen/sim/bin // Create the executables in this folder
103 + command: "gcc -std=c99 -o ./${outputFolder}/${executable_name}" // Use gcc to compile the code
104 +}
105 +
106 +
107 +
108 +{{/code}}
109 +
110 +{{code title="Complex KiBuild Example"}}
111 +// Compile models to Java code
112 +model compiler kico {
113 + outputFolder: kieler-gen
114 + outputFileExtension: java
115 + outputTemplate: assets/OutputTemplate.ftl
116 + compilationSystem: de.cau.cs.kieler.sccharts.netlist.simple
117 + whitelist: "ModelA|ModelB" // Only compile models that match this regex
118 +
119 + // Generate C simulation for compiled models
120 + process simulation template {
121 + file: assets/JavaSimulation.ftl
122 + }
123 +}
124 +
125 +// Compile C simulation via gcc
126 +simulation compiler java {
127 + libFolder: kieler-gen/org/json
128 + outputFolder: kieler-gen/sim/bin
129 + command: "jar cvfe ../${outputFolder}/${executable_name}"
130 +}
131 +
132 +// Process a simple template
133 +process template {
134 + file: Template.ftl
135 + target: Output.txt
136 +}
137 +
138 +// Process a template to generate a main file that can be deployed.
139 +process wrapper template {
140 + file: Main.ftl
141 + target: kieler-gen/Main.c
142 + modelFile: MyModel.sctx
143 +}
144 +{{/code}}
145 +
146 +\\
147 +
148 +----
149 +
150 +== Prom Environments ==
151 +
152 +Environments are used to provide default settings for project creation. They are configured in the **preferences** (//Window //>// Preferences > KIELER SCCharts > Execution Environments//).
153 +
154 +An environment consists of
155 +
156 +1. a unique **name**, which may not contain a comma
157 +1. an **associated** project wizard
158 +1. the path of the default **model file** for the project
159 +1. the path of the default **main file** for the project
160 +1. information about **folders and files** that should be imported at project setup
161 +
162 +Besides the name, all of these are optional, but can improve the workflow.
163 +
164 +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.
165 +
166 +=== Paths for imported resources ===
167 +
168 +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.
169 +
170 +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>>url:http://plaftorm/plugin/a.plugin.name/folder/in/the/plugin/file.txt||shape="rect"]]// 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>>url:http://plaftorm/plugin/a.plugin.name/folder/in/the/plugin||shape="rect"]]//
171 +
172 +----
173 +
174 +== Wrapper Code Generation ==
175 +
176 +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.
177 +
178 +Therefore one can write **wrapper code snippets** for a target device. These can then be injected to a **template file**. What snippets are injected is defined using **annotations on inputs and outputs** directly in the model file.
179 +
180 +In SCT files, annotations are added as in java, with an at-sign e.g. //@Wrapper Clock, "500"//. You can write implicit and explicit wrapper code annotations.
181 +
182 +Explicit annotations have the form **{{code language="none"}}@Wrapper SnippetName, arg1, arg2, ..., argN{{/code}}**. An explicit wrapper annotation raises an error if the snippet does not exist, thus it is **recommened** to use the explicit **@Wrapper** annotation. Every other annotation is tried as wrapper code annotation as well, but will be ignored, if no such snippet could be found. Thus you can write the above explicit annotation as **@SnippetName arg1, arg2, ..., argN**{{code language="none"}}{{/code}}, but there will be no error if the snippet with this name does not exist or could not be found, for example because of a typo.
183 +
184 +**//Note~://** Annotation **names** and parameters are **case sensitive**. That means that //Clock, clock, Floodlight, FloodLight// are all different annotations.
185 +
186 +[[image:attach:wrapper_code_generation_scheme.png]]
187 +
188 +In the **template file** one can use special **placeholders**.
189 +
190 +**${file_name}** is replaced with the name withouth extension of the file that is generated (e.g. //Main.java// will be //Main//).
191 +
192 +**${model_name}** is replaced with the name of the last compiled model.
193 +
194 +**${declarations}** and** ${decls}** will be replaced with additional declarations of variables and functions (<@decl>...</@decl> of a snippet definition). Declarations should occur before the tick loop of the model file. In general they are not required for Java code but may be useful in C applications (e.g. for //extern// calls).
195 +
196 +**${initializations}** and **${inits}** will be replaced with initialization code for components (<@init>...</@init> of a snippet definition). Initialization should occur before the tick loop of the model file.
197 +
198 +**${inputs}** will be replaced with code to set inputs for the model (<@input>...</@input> of a snippet definition). Setting model inputs should occur in the tick loop, before the tick function call.
199 +
200 +**${outputs}** will be replaced with code to read outputs of the model. (<@output>...</@output> of a snippet definition). Reading outputs of the model should occur in the tick loop, after the tick function call.
201 +
202 +**${releases}** will be replaced with code to free allocated resources. (<@release>...</@release> of a snippet definition). Releasing resources should occur after the tick loop at the end of the program.
203 +
204 +[[image:attach:template_file_structure.png]]
205 +
206 +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//
207 +
208 +=== Simulation templates ===
209 +
210 +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.
211 +
212 +To create the simulation code, a template is used in which code is injected for each variable in the model to fill the JSON object with the current variable values. This way, the state of the model is communicated to the outside. Before the tick, inputs can be set in the model. Thus there is also code injected for each variable in the model to change its value using a JSON input.
213 +
214 +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.
215 +
216 +=== FreeMarker ===
217 +
218 +The wrapper code injection is done using the open source **template engine [[FreeMarker>>url:http://freemarker.org/||shape="rect"]]**. A wrapper code snippet is basically a [[Macro>>url:http://freemarker.org/docs/ref_directive_macro.html||shape="rect"]] 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**.
219 +
220 +There is an [[Eclipse plugin>>url:http://freemarker.org/editors.html||shape="rect"]] for FreeMarker as part of the JBoss Tools Project. It can be installed using the Eclipse Marketplace.
221 +
222 +\\
223 +
224 +Example for wrapper code generation from annotations:
225 +
226 +=== [[image:attach:wrapper_code_generation_example.png]] ===
227 +
228 +----
Confluence.Code.ConfluencePageClass[0]
Id
... ... @@ -1,1 +1,1 @@
1 -31162486
1 +31162488
URL
... ... @@ -1,1 +1,1 @@
1 -https://rtsys.informatik.uni-kiel.de/confluence//wiki/spaces/KIELER/pages/31162486/V2 Project Management
1 +https://rtsys.informatik.uni-kiel.de/confluence//wiki/spaces/KIELER/pages/31162488/V2 Project Management

Navigation

Quick Links

KIELER on GitHub
RTSYS Homepage