|
1 User guide for Command Plugin |
|
2 ----------------------------- |
|
3 |
|
4 Introduction |
|
5 ''''''''''''' |
|
6 This page describes how to use ConE command plugin. Command plugin is a ConE plugin, |
|
7 which purpose is to run external tools and scripts to generate files to target image. |
|
8 Command plugin is configured in CommandML files that describes tools that are run |
|
9 and options that are used. |
|
10 |
|
11 CommandML files are executed by default in **normal** :ref:`invocation phase <implml-common-invocation-phase>`. |
|
12 |
|
13 CommandML |
|
14 ''''''''' |
|
15 |
|
16 The CommandML syntax is a extension of Configuration markup language (confml). The term in confml for this extension |
|
17 is implementation method language (implml), which in CommandML case is a xml file. |
|
18 |
|
19 All input values can be given as ConfML refs or as plain text. Also mixing text and ConfML ref information |
|
20 is supported. |
|
21 |
|
22 * Namespace: ``http://www.s60.com/xml/commandml/1`` |
|
23 * File extension: ``commandml`` |
|
24 |
|
25 .. note:: |
|
26 |
|
27 More information about :ref:`file extensions <implml-file-extensions>`. |
|
28 |
|
29 CommandML Elements |
|
30 .................. |
|
31 |
|
32 The CommandML model is drawn out as a uml model in below picture. |
|
33 |
|
34 .. image:: commandml.jpg |
|
35 |
|
36 .. note:: |
|
37 |
|
38 CommandML supports also common ImplML elements. More information about :ref:`ImplML elements <implml-common-elements>`. |
|
39 |
|
40 <commandml> Element |
|
41 ************************** |
|
42 |
|
43 The ``commandml`` element is the root element of the configuration, and acts as a container to the rest of the elements. |
|
44 |
|
45 Child Elements |
|
46 ++++++++++++++++++++++++++ |
|
47 |
|
48 ==================== ====================== =============================================================================== |
|
49 Element Cardinality Description |
|
50 ==================== ====================== =============================================================================== |
|
51 condition 0 .. * Defines a group of commands that are run only if command is evaluated as True. |
|
52 command 0 .. * Defines properties for one executable. |
|
53 ==================== ====================== =============================================================================== |
|
54 |
|
55 Example |
|
56 ++++++++++++++++++++++++++ |
|
57 |
|
58 .. code-block:: xml |
|
59 |
|
60 <commandml xmlns="http://www.s60.com/xml/commandml/1"> |
|
61 |
|
62 <condition> Element |
|
63 ************************** |
|
64 |
|
65 ``Condition`` element defines a group of commands that are run only if command is evaluated as True. |
|
66 |
|
67 |
|
68 Child Elements |
|
69 ++++++++++++++++++++++++++ |
|
70 |
|
71 Condition can contain arbitrary number of commands and they are run in definition order so that next command is executed |
|
72 only after the previous has ended. |
|
73 |
|
74 ==================== ====================== =============================================================================== |
|
75 Element Cardinality Description |
|
76 ==================== ====================== =============================================================================== |
|
77 command 0 .. * Defines properties for one executable. |
|
78 ==================== ====================== =============================================================================== |
|
79 |
|
80 Attributes |
|
81 ++++++++++++++++++++++++++ |
|
82 |
|
83 Condition has only one attribute ``value`` which can contains any Python code and ConfML refs. Refs are first expanded |
|
84 and then the value is evaluated using Python eval function. |
|
85 |
|
86 ==================== ====================== =============================================================================== |
|
87 Attribute Required Description |
|
88 ==================== ====================== =============================================================================== |
|
89 value Yes Defines a condition value that can contain any Python code and ConfML refs. |
|
90 ==================== ====================== =============================================================================== |
|
91 |
|
92 Example |
|
93 ++++++++++++++++++++++++++ |
|
94 |
|
95 .. code-block:: xml |
|
96 |
|
97 <condition value="${runconfig.notepad} != ''"> |
|
98 <command executable="notepad.exe"/> |
|
99 </condition> |
|
100 |
|
101 This will run notepad.exe only if value in ConfML ref ``runconfig.notepad`` is not empty. |
|
102 |
|
103 <command> Element |
|
104 ************************** |
|
105 |
|
106 ``Command`` element defines properties for one executable. Basically it provides same features that Python subprocess |
|
107 module. Commands can be defined either inside condition elements and directly under ``commandml``. Running order of |
|
108 commands is the same that is defined in commandml file. Definition of those can be found from |
|
109 `Python subprocess documentation <http://docs.python.org/library/subprocess.html>`_. |
|
110 |
|
111 Child Elements |
|
112 ++++++++++++++++++++++++++ |
|
113 |
|
114 Command element can have arguments, pipes and filters as sub-elements. |
|
115 |
|
116 ==================== ====================== =============================================================================== |
|
117 Element Cardinality Description |
|
118 ==================== ====================== =============================================================================== |
|
119 argument 0 .. * Defines argument for executable. |
|
120 pipe 0 .. * Defines pipe for executable. |
|
121 filter 0 .. * Defines filter for executable. |
|
122 ==================== ====================== =============================================================================== |
|
123 |
|
124 |
|
125 Attributes |
|
126 ++++++++++++++++++++++++++ |
|
127 |
|
128 Command element has one mandatory argument ``executable`` and four optional attributes: ``shell``, ``env``, ``cwd``, ``bufsize``. |
|
129 |
|
130 ==================== ====================== =============================================================================== |
|
131 Attribute Required Description |
|
132 ==================== ====================== =============================================================================== |
|
133 executable Yes Defines a program to execute. Value can contain any Python code and ConfML refs. |
|
134 shell No Defines is the specified command executed through the shell. |
|
135 env No Defines the environment variables for the new process. |
|
136 cwd No Defines the current directory that will be changed to cwd before command is |
|
137 executed. Note that this directory is not considered when searching the |
|
138 executable, so you can't specify the program's path relative to cwd. |
|
139 bufsize No Defines the pipe buffering: 0 means unbuffered, 1 means line buffered, |
|
140 any other positive value means use a buffer of (approximately) that size. |
|
141 A negative bufsize means to use the system default, which usually means |
|
142 fully buffered. The default value for bufsize is 0 (unbuffered). |
|
143 ==================== ====================== =============================================================================== |
|
144 |
|
145 Example |
|
146 ++++++++++++++++++++++++++ |
|
147 |
|
148 .. code-block:: xml |
|
149 |
|
150 <command executable="\Preinstallation\preinstallation.exe" cwd="x:\" shell="true" env="{'MYVAR':'123'}"> |
|
151 |
|
152 |
|
153 |
|
154 <argument> Element |
|
155 ************************** |
|
156 |
|
157 ``Argument`` element defines one command line argument for it's parent command. |
|
158 |
|
159 |
|
160 Attributes |
|
161 ++++++++++++++++++++++++++ |
|
162 |
|
163 Value is given in attribute ``value`` and can contain any string value. When executing the command all attributes are |
|
164 combined to be a single string that is passed as a parameter to executable. |
|
165 |
|
166 ==================== ====================== =============================================================================== |
|
167 Attribute Required Description |
|
168 ==================== ====================== =============================================================================== |
|
169 value Yes Defines a one command line argument for it's parent command. |
|
170 ==================== ====================== =============================================================================== |
|
171 |
|
172 Example |
|
173 ++++++++++++++++++++++++++ |
|
174 |
|
175 .. code-block:: xml |
|
176 |
|
177 <argument value="-o output/content" /> |
|
178 <argument value="--add-setting-file=c:\temp.txt" /> |
|
179 <argument value="${preinstallmeta.product}"/> |
|
180 |
|
181 <pipe> Element |
|
182 ************************** |
|
183 |
|
184 Pipes are used to specify executed program's standard input, output and error file handles. |
|
185 |
|
186 Attributes |
|
187 ++++++++++++++++++++++++++ |
|
188 |
|
189 ``Pipe`` has two mandatory arguments ``name`` and ``value``. |
|
190 |
|
191 ==================== ====================== =============================================================================== |
|
192 Attribute Required Description |
|
193 ==================== ====================== =============================================================================== |
|
194 name Yes Defines the name of the pipe. Possible values are: "stdin", "stdout" and |
|
195 "stderr". That are executed programs' standard input, standard output and |
|
196 standard error file handles, respectively. |
|
197 value Yes Value can be either PIPE to indicate that new should be defined or then |
|
198 filename. Stderr additionally can have also value STDOUT, which indicates that |
|
199 the stderr data from the applications should be captured into the same file |
|
200 handle as for stdout. |
|
201 ==================== ====================== =============================================================================== |
|
202 |
|
203 Example |
|
204 ++++++++++++++++++++++++++ |
|
205 |
|
206 .. code-block:: xml |
|
207 |
|
208 <pipe name="stdout" value="x:\\logia.txt"/> |
|
209 <pipe name="stderr" value="STDOUT"/> |
|
210 |
|
211 <filter> Element |
|
212 ************************** |
|
213 |
|
214 Filters are used to analyse output of executed command and report the findings to ConE log file. This enables that |
|
215 executed program's errors are easily available for users. |
|
216 |
|
217 Attributes |
|
218 ++++++++++++++++++++++++++ |
|
219 |
|
220 ``Filter`` element has four attributes: ``severity``, ``condition``, ``input`` and ``formatter``. |
|
221 |
|
222 ==================== ====================== =============================================================================== |
|
223 Attribute Required Description |
|
224 ==================== ====================== =============================================================================== |
|
225 severity Yes Defines logging level e.g. "info" means that possible findings are reported as |
|
226 info elements. Other options for severity are "warning", "debug", "exception", |
|
227 "error" and "critical". Default value is "info". |
|
228 condition Yes Defines a Python regexp pattern that is used to match lines from the |
|
229 defined input pipe. Notice that you can use named groups to get some relevant |
|
230 information stored for formatter use. |
|
231 input Yes Input can be either "stdout" or "stderr". |
|
232 formatter No Formatter defines how the findings are reported in ConE output. It is |
|
233 sprintf-style string which can contain named groups from condition. If |
|
234 formatter is empty found line is printed as such. See examples below. |
|
235 ==================== ====================== =============================================================================== |
|
236 |
|
237 Example |
|
238 ++++++++++++++++++++++++++ |
|
239 |
|
240 .. code-block:: xml |
|
241 |
|
242 <filter severity="info" condition="\s*\'(?P<name>.*)\' => \'(?P<uid>.*)\'" input="stdout" formatter="Installed %(name)s using UID: %(uid)s"/> |
|
243 <filter severity="debug" condition=".*successfully.*" input="stdout"/> |
|
244 <filter severity="error" condition="Installation of \'(?P<name>.*)\' failed! See the log for details and contact Delevopment team." input="stdout" formatter="Install manually %(name)s!"/> |
|
245 |
|
246 The first one defines that findings are reported as info elements. Condition element defines two named groups "name" and |
|
247 "uid" which are also used in formatter when printing information to ConE's log file. |
|
248 The second one tries to find any line containing word "successfully" and prints the whole line as debug element. |
|
249 The last one print all failed cases as errors and uses again named groups to extract data from input stream. |
|
250 |
|
251 |
|
252 Full example files |
|
253 '''''''''''''''''' |
|
254 |
|
255 .. literalinclude:: preinstall.commandml |
|
256 :language: xml |
|
257 |
|
258 |
|
259 XSD |
|
260 ''' |
|
261 |
|
262 .. note:: |
|
263 |
|
264 This will be added later. |
|
265 |
|
266 |
|
267 FAQ |
|
268 ''''''''''''' |
|
269 |
|
270 This will be updated based on the questions. |