Version 39.1 by aas2 on 2016/05/09 13:45
Show last authors
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 initialize and run the model. To do so, there are mainly three components: An Eclipse //Launch Configuration//, so called //Environments//, and //Project Wizards,// which will be introduced in the following.
16
17 ----
18
19 == The KiCo Launch Configuration ==
20
21 Prom provides a launch configuration (launch config) to
22
23 1. compile code from models via KiCo
24 1. at the same time, generate wrapper code for these model files
25 1. afterwards run an associated launch configuration (e.g. for a Java Application) and
26 1. execute arbitrary shell commands sequentially if the KiCo compilation and wrapper code generation finished successfully
27
28 KiCo launch configurations work per project basis so that every project has to create its own launch config. This is done automatically when performing //Right Click > Run As > KiCo Compilation //(% style="color: rgb(0,51,102);" %)on a model file.
29
30 The **Run As** command will search for a KiCo launch config for the project. If there is such a config, the selected file is only added to the list of model files that should be compiled. If there is none, a launch config is created by using the main file and environment the project has been created with. If the main file and environment information could not be found, dialogs will query it from the user.
31
32 [[image:attach:Screenshot_20160509_133139.png]]
33
34 [[image:attach:Screenshot_20160509_134127.png]]
35
36 [[image:attach:Screenshot_20160509_133254.png]]
37
38 (% style="text-align: left;" %)
39 The **main file** of the launch config is used to set several file path variables, which can be used in several fields of the configuration, notably the shell commands to be executed, and wrapper code input. To use a variable, the syntax is **${**//variable_name//**}**. The variables that are set are
40
41 * //main_name// : The file name, including its file extension (e.g. //MyModel.sct//)
42 * //main_path// : The project relative path (e.g. //src/MyModel.sct//)
43 * //main_loc// : The absolute file system path (e.g. ///home/me/workspace/MyProject/src/MyModel.sct//)
44 * //main_name_no_ext// : The file name without its file extension (e.g. //MyModel//)
45
46 Further, similar variables for the //compiled main file// are set, which is the main file in the directory of kieler generated files (see below)
47
48 * //compiled_main_name// : The file name, including its file extension (e.g. //MyModel.sct//)
49 * //compiled_//main_path : The project relative path (e.g. //kieler-gen/MyModel.sct//)
50 * //compiled_//main_loc : The absolute file system path (e.g. ///home/me/workspace/MyProject/kieler-gen/MyModel.sct//)
51 * //compiled_//main_name_no_ext : The file name without its file extension (e.g. //MyModel//)
52
53 [[image:attach:variable_selection_dialog.png]]
54
55 The values of the launch config can also be **(re)set to an environment**. This will revert the fields for the compilation target, wrapper code generation and command execution.
56
57 The **compilation via KiCo** is configured on the //Compilation// tab. Here you can add/remove files that should be compiled via KiCo and the target language as well as the file extension for the language (such as //.java// for Java). The files will be compiled sequentially in order of appearance in the list. Further, it is possible to add a file path to a template for the output. This is useful to add surrounding content to the KiCo output. The placeholder //${kico_code}// can be used in the template.
58
59 On the //Execute// tab, a list of **shell commands** can be added. They are typically used to further compile the KiCo and wrapper code output and afterwards deploy the result to the target platform. The commands are executed sequentially in order as they appear in the list, after the KiCo compilation and wrapper code generation finished successfully. If a command fails (returns a non-zero exit code), following commands will not be excuted. The name of commands have to be unique and must not contain a comma.
60
61
62
63 The standard streams of executed shell commands (stdin, stderr, stdout), as well as errors from the KiCo compilation and wrapper code generation, are printed to the **Console View**.
64
65 [[image:attach:console_view.png]]
66
67 === Launch Groups ===
68
69 The list of shell commands are a simple mechanism to further compile and deploy code via command line tools. However, there are cases in which command line tools are not available or reasonable to use, for example because a different Eclipse launch configuration does a better job.
70
71 In this case it is desirable that the KiCo launch config only compiles the model and another Eclipse launch config does the rest. This can be achieved via //launch groups//. They let you define a launch configuration, which starts other launch configurations sequentially. To illustrate this, another use-case for launch groups is that you have a Client-Server application and want to start the client right after the server for debugging. Then you can create a launch config for the server and a launch config for the client. Afterwards you create a launch group with aforesaid configurations.
72
73 [[image:attach:launch_group.png]]
74
75 Launch groups are a part of the C/C++ Development Tools (CDT), although they provide a general mechanism that could be a part of any Eclipse IDE. The CDT is available in the Eclipse Marketplace (//Help > Eclipse Marketplace//)
76
77 ----
78
79 == Prom Environments ==
80
81 Environments are used to provide default settings for project creation and launch. They are configured in the **preferences** (//Window //>// Preferences > KIELER > Environments//).
82
83 An environment consists of
84
85 1. a unique **name**, which may not contain a comma
86 1. an **associated** project wizard
87 1. information for a default **main file** for the project
88 1. information for a default **model file** for the project
89 1. information for a default **wrapper code snippet directory**
90 1. default values for the KiCo compilation
91
92 Besides the name, all of these are optional, but can improve the workflow.
93
94 The associated project wizard is run as part of the Prom project wizard and takes care of the actual project creation.
95
96 A main file typically contains the entry point of the program on the target environment. Its wrapper code initializes and runs the model and sets inputs and outputs to the physical components of the target device. To ease the project setup and because wrapper code for a specific target platform is often similar, it is possible to define default content for the main file. Therefore the field **main file origin** can contain an absolute file path to a file with the default contents of a newly created main file for this environment. Furthermore, predefined wrapper code snippets can be injected as part of a project launch, which is described below.
97
98 The **snippets origin** is used to initialize the wrapper code snippet directory of a newly created project.
99
100 The other fields are default settings for KiCo launch configurations.
101
102 [[image:attach:Screenshot_20160509_132406.png]]
103
104 === Paths for initial content ===
105
106 The path of the main file origin accept an **absolute** file **path** as well as an **URL** with the platform protocol of Eclipse. An URL for the field has the form //plaftorm:/plugin/a.plugin.name/folder/in/the/plugin/file.txt//
107
108 The snippets origin works analog. It accepts an absolute directory path as well as an URL with the platform protocol which points to a directory. An URL for the field has the form //plaftorm:/plugin/a.plugin.name/folder/in/the/plugin//
109
110 ----
111
112 == Project Wizards with Prom ==
113
114 Prom provides project wizards, which can **create and initialize a project** with a **model file**, a **main file** and wrapper code **snippets**. The wizards for different model file types (e.g. SCChart project vs Esterel project) differ only in the initial content for the model file. Other initial content is choosen from the environment, which is selected on the first page of a Prom wizard. The project creation itself is done by another wizard, that is started from within the Prom wizard.
115
116 If the //snippets directory// of an environment is a project relative path, the contents from the //snippets origin// will be copied to this location in the newly created project. If it is an absolute path, it is not copied to the project. Keeping snippets in a single, project indepentent folder, makes it easier to maintain them. For example it is possible to set an absolute path to a directory outside any project as directory for wrapper code snippets. This directory can then be easily maintained using a version control system. Furthermore, if an issue occurs, it has to be addressed only once, because the snippets are not copied to every new project.
117
118 For example to create a project to develop Minstorms running leJOS, one can choose the SCCharts project wizard. In this wizard, one can choose the Mindstorms NXJ environment and define what will be initialized in the project (model file, main file, snippets). Now when pressing the finish button, the related project wizard from the leJOS plugin will be started. When it finishes, the newly created project is initialized with an initial model file, main file and wrapper code snippets.
119
120 [[image:attach:project_wizard.png]]
121
122 ----
123
124 == Wrapper Code Generation ==
125
126 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.
127
128 Therefore one can write **wrapper code snippets** for a target device. These can then be injected to a **template file** as part of a KiCo launch. What snippets are injected is defined using **annotations on inputs and outputs** directly in the model file.
129
130 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.
131
132 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.
133
134 **//Note~://** Annotation **names** and parameters are **case sensitive**. That means that //Clock, clock, Floodlight, FloodLight// are all different annotations.
135
136 [[image:attach:wrapper_code_generation_scheme.png]]
137
138 In the **template file** one can use special **placeholders**.
139
140 **${file_name}** is replaced with the name withouth extension of the file that is generated (e.g. //Main.java// will be //Main//).
141
142 **${model_name}** is replaced with the name of the last compiled model.
143
144 **${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).
145
146 **${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.
147
148 **${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.
149
150 **${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.
151
152 [[image:attach:template_file_structure.png]]
153
154 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//
155
156 === FreeMarker ===
157
158 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**.
159
160 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.
161
162 [[image:attach:wrapper_code_generation_example.png]]
163
164 ----
165
166 == Automatically generated files ==
167
168 Files created by Prom are either saved in the directory **kieler-gen** or in the **same directory as the input files** they correspond to. This is configured in the KiCo launch configuration.
169
170 When choosing the kieler-gen folder, the directory structure of input files is retained. However a starting Java source folder will be skipped because //kieler-gen// itself is a Java source folder.
171
172 For example
173
174 * if //code// is not a Java source folder, the file //code/subfolder/MyModel.sct// will be save to //kieler-gen/code/subfolder/MyModel.sct.//
175 * if //src// is a Java source folder, the file //src/subfolder/MyModel.sct//, will be saved to //kieler-gen/subfolder/MyModel.sct.//

Navigation

Quick Links

KIELER on GitHub
RTSYS Homepage