0
|
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.
|