0
|
1 |
ImplML and plug-ins
|
|
2 |
===================
|
|
3 |
|
|
4 |
The `configuration project` concept contains an interface/implementation split
|
|
5 |
by using the Configuration Markup Language (ConfML) to specify the interface for
|
|
6 |
configurable entities in a project, and an arbitrary number of Implementation
|
|
7 |
Markup Languages (ImplML) to specify the output generated based on the interface.
|
|
8 |
|
|
9 |
ConE plug-ins supply the actual code-level implementations for the different
|
|
10 |
implementation languages. This page describes common ImplML concepts.
|
|
11 |
|
|
12 |
|
|
13 |
ImplML basics
|
|
14 |
-------------
|
|
15 |
|
|
16 |
All implementation languages are based on XML, and each separate
|
|
17 |
Implementation Mark-up Language (ImplML) resides within a single
|
|
18 |
XML namespace. The namespace of the ImplML must be defined in
|
|
19 |
the file, or the implementation won't be recognized. For example,
|
|
20 |
the following file is an example of CRML (Central Repository
|
|
21 |
Mark-up Language):
|
|
22 |
|
|
23 |
|
|
24 |
.. code-block:: xml
|
|
25 |
|
|
26 |
<?xml version="1.0" encoding="UTF-8"?>
|
|
27 |
<repository xmlns="http://www.s60.com/xml/cenrep/1" uidName="Feature1_1" uidValue="0x00000001" owner="0x12341000">
|
|
28 |
<access type="R" capabilities="AlwaysPass"/>
|
|
29 |
<access type="W" capabilities="AlwaysPass"/>
|
|
30 |
|
|
31 |
<key ref="Feature1/IntSetting" name="Int setting" int="0x00000001" type="int" readOnly="false" backup="true">
|
|
32 |
<access type="R" capabilities="AlwaysPass"/>
|
|
33 |
</key>
|
|
34 |
</repository>
|
|
35 |
|
|
36 |
Notice the use of the XML namespace ``xmlns="http://www.s60.com/xml/cenrep/1"``
|
|
37 |
in the root element. This is what tells ConE that a CRML implementation should
|
|
38 |
be read from this XML document's root element. Here there is only one implementation
|
|
39 |
language used, and the extension of the file can reflect this (the extension is
|
|
40 |
.crml in this case).
|
|
41 |
|
|
42 |
However, the use of XML namespaces to differentiate implementation languages
|
|
43 |
enables the mixing of multiple languages in a single implementation file.
|
|
44 |
For example, the following file uses two implementation languages under common container,
|
|
45 |
RuleML and ContentML:
|
|
46 |
|
|
47 |
.. code-block:: xml
|
|
48 |
|
|
49 |
<?xml version="1.0" encoding="UTF-8"?>
|
|
50 |
<container xmlns="http://www.symbianfoundation.org/xml/implml/1">
|
|
51 |
<ruleml xmlns="http://www.s60.com/xml/ruleml/2">
|
|
52 |
<rule>
|
|
53 |
CustomSettings.StartupSoundFile.localPath configures StartupSettings.StartupSoundPath
|
|
54 |
= Startup.StartupSoundPath filenamejoin CustomSettings.StartupSoundFile.localPath
|
|
55 |
</rule>
|
|
56 |
</ruleml>
|
|
57 |
|
|
58 |
<content xmlns="http://www.s60.com/xml/content/3">
|
|
59 |
<output file="${StartupSettings.StartupSoundPath}">
|
|
60 |
<input file="${CustomSettings.StartupSoundFile.localPath}"/>
|
|
61 |
</output>
|
|
62 |
</content>
|
|
63 |
</container>
|
|
64 |
|
|
65 |
The execution order of elements inside the container is the same as the order of definition.
|
|
66 |
|
|
67 |
In this example, the RuleML section first sets the value of a ConfML setting,
|
|
68 |
whose value is then used in the ContentML section to copy the file to the
|
|
69 |
correct place.
|
|
70 |
Notice how the XML namespaces are defined.
|
|
71 |
|
|
72 |
- The container is in http://www.symbianfoundation.org/xml/implml/1, the root element of implml namespace must always be container
|
|
73 |
- The ruleml is in http://www.s60.com/xml/ruleml/2
|
|
74 |
- The content is in xmlns="http://www.s60.com/xml/content/3"
|
|
75 |
|
|
76 |
When reading the implementation file, ConE checks the document root and its namespace
|
|
77 |
to find out from namespace to start parsing.
|
|
78 |
|
|
79 |
.. _implml-file-extensions:
|
|
80 |
|
|
81 |
File extensions
|
|
82 |
^^^^^^^^^^^^^^^
|
|
83 |
|
|
84 |
Implementations are read from files under layers' ``implml/`` directories
|
|
85 |
inside the configuration project. The extensions of these files matter
|
|
86 |
in whether implementations are attempted to be read from a file or
|
|
87 |
not. The generic implementation file extension is ``implml``, but plug-ins
|
|
88 |
may extend the list of supported file extensions. However, the extension
|
|
89 |
does nothing more than specify whether the file is attempted to be parsed or
|
|
90 |
not; no checking on the implementation types is done. This means that
|
|
91 |
it is possible to create e.g. a CRML file with the extension ``templateml``,
|
|
92 |
but of course this makes no sense and should be avoided.
|
|
93 |
|
|
94 |
The extension checking mechanism is there in order to differentiate
|
|
95 |
implementation files and any other related files, e.g. Python scripts
|
|
96 |
used by RuleML implementations. This way, if an implementation file
|
|
97 |
contains invalid XML data an error will be shown to the user, but a
|
|
98 |
Python script (the reading of which as XML would invariably fail and
|
|
99 |
produce an error) will simply be ignored.
|
|
100 |
|
|
101 |
If you want to see what file extensions are supported, run to following
|
|
102 |
command::
|
|
103 |
|
|
104 |
cone info --print-supported-impls
|
|
105 |
|
|
106 |
This will print something like the following::
|
|
107 |
|
|
108 |
Running action info
|
|
109 |
Supported ImplML namespaces:
|
|
110 |
http://www.symbianfoundation.org/xml/implml/1
|
|
111 |
http://www.s60.com/xml/cenrep/1
|
|
112 |
http://www.s60.com/xml/content/1
|
|
113 |
http://www.s60.com/xml/content/2
|
|
114 |
http://www.s60.com/xml/convertprojectml/1
|
|
115 |
http://www.s60.com/xml/genconfml/1
|
|
116 |
http://www.s60.com/xml/imageml/1
|
|
117 |
http://www.s60.com/xml/ruleml/1
|
|
118 |
http://www.s60.com/xml/ruleml/2
|
|
119 |
http://www.s60.com/xml/templateml/1
|
|
120 |
http://www.s60.com/xml/thememl/1
|
|
121 |
http://www.symbianfoundation.org/xml/hcrml/1
|
|
122 |
|
|
123 |
Supported ImplML file extensions:
|
|
124 |
implml
|
|
125 |
content
|
|
126 |
contentml
|
|
127 |
crml
|
|
128 |
gcfml
|
|
129 |
convertprojectml
|
|
130 |
ruleml
|
|
131 |
imageml
|
|
132 |
thememl
|
|
133 |
templateml
|
|
134 |
hcrml
|
|
135 |
|
|
136 |
Another way is to check the log file created when running ``cone generate``.
|
|
137 |
It should contain a line like the following::
|
|
138 |
|
|
139 |
Supported implementation file extensions: ['templateml', 'ruleml', 'thememl', 'imageml', 'crml', 'content', 'contentml', 'convertprojectml', 'hcrml', 'gcfml', 'implml']
|
|
140 |
|
|
141 |
**Guidelines for implementation file naming**
|
|
142 |
|
|
143 |
- Use the corresponding file extension if the file contains only a
|
|
144 |
single implementation instance (e.g. ``.crml`` for a CRML implementation)
|
|
145 |
- Otherwise use the generic ``implml`` extension with containers
|
|
146 |
|
|
147 |
Implementation container nesting
|
|
148 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
149 |
|
|
150 |
In example 1, implementations were defined under a single root container element. The container
|
|
151 |
elements can be nested to form sub containers under the single implementation file.
|
|
152 |
|
|
153 |
For example:
|
|
154 |
|
|
155 |
.. code-block:: xml
|
|
156 |
|
|
157 |
<?xml version="1.0" encoding="UTF-8"?>
|
|
158 |
<container xmlns="http://www.symbianfoundation.org/xml/implml/1">
|
|
159 |
<container>
|
|
160 |
<phase name="pre">
|
|
161 |
<ruleml xmlns="http://www.s60.com/xml/ruleml/2">
|
|
162 |
<rule>
|
|
163 |
CustomSettings.StartupSoundFile.localPath configures
|
|
164 |
StartupSettings.StartupSoundPath = Startup.StartupSoundPath + "/" + CustomSettings.StartupSoundFile.localPath
|
|
165 |
</rule>
|
|
166 |
</ruleml>
|
|
167 |
</container>
|
|
168 |
|
|
169 |
<container>
|
|
170 |
<phase name="normal">
|
|
171 |
<content xmlns="http://www.s60.com/xml/content/3">
|
|
172 |
<output file="${StartupSettings.StartupSoundPath}">
|
|
173 |
<input file="${CustomSettings.StartupSoundFile.localPath}"/>
|
|
174 |
</output>
|
|
175 |
</content>
|
|
176 |
|
|
177 |
<!-- Another ContentML section, copies the file to another directory -->
|
|
178 |
<content xmlns="http://www.s60.com/xml/content/3">
|
|
179 |
<output dir="some/dir">
|
|
180 |
<input file="${CustomSettings.StartupSoundFile.localPath}"/>
|
|
181 |
</output>
|
|
182 |
</content>
|
|
183 |
</container>
|
|
184 |
|
|
185 |
</container>
|
|
186 |
|
|
187 |
Here the root level container has two sub-containers, where the first sub-container
|
|
188 |
is executed in "pre" phase (<phase name="pre"> definition) and the second in "normal" phase.
|
|
189 |
|
|
190 |
.. _common-implml-namespace:
|
|
191 |
|
|
192 |
Common ImplML namespace
|
|
193 |
-----------------------
|
|
194 |
|
|
195 |
Because there are common elements that are relevant for most, if not all, implementations,
|
|
196 |
there is a common ImplML namespace (``http://www.symbianfoundation.org/xml/implml/1``)
|
|
197 |
that contains these. The common elements can be defined by default in the container elements.
|
|
198 |
The support for the plugin implementation support for common elements depends on the implementation
|
|
199 |
of the plugin. So refer to the plugin specific documentation to what each plugins supports.
|
|
200 |
|
|
201 |
.. _implml-common-elements:
|
|
202 |
|
|
203 |
Elements
|
|
204 |
^^^^^^^^
|
|
205 |
|
|
206 |
The common ImplML elements are illustrated with the following UML class diagram:
|
|
207 |
|
|
208 |
.. image:: implml.jpg
|
|
209 |
|
|
210 |
|
|
211 |
==================== ====================== ===============================================================================
|
|
212 |
Element Cardinality Description
|
|
213 |
==================== ====================== ===============================================================================
|
|
214 |
container 1 .. * Defines a container for sub elements. For details see
|
|
215 |
:ref:`implml-common-container` .
|
|
216 |
tempVariableSequence 0 .. * Defines a temporary sequence variable. For details see
|
|
217 |
:ref:`implml-common-temporary-variables`.
|
|
218 |
tempVariable 0 .. * Defines a temporary variable. For details see
|
|
219 |
:ref:`implml-common-temporary-variables`.
|
|
220 |
tag 0 .. * Defines an implementation tag. For details see
|
|
221 |
:ref:`implml-common-implementation-tags`.
|
|
222 |
phase 0 .. 1 Defines a execution phase. For details see
|
|
223 |
:ref:`implml-common-invocation-phase` .
|
|
224 |
==================== ====================== ===============================================================================
|
|
225 |
|
|
226 |
.. _implml-common-container:
|
|
227 |
|
|
228 |
Container element
|
|
229 |
^^^^^^^^^^^^^^^^^
|
|
230 |
|
|
231 |
The container element in the common namespace is like its name says a implementation
|
|
232 |
that can contain other implementations. So in other words containers can contain
|
|
233 |
other containers or actual implementations, like templateml, content, ruleml, etc.
|
|
234 |
|
|
235 |
The key purpose of the containers is to offer a mechanism where one configuration
|
|
236 |
implementation solution can be nicely wrapped to a single file. The whole solution might
|
|
237 |
require generation of one or more output files, rules, content copying, executing system
|
|
238 |
commands, etc. To resolve simple and more complex problems the containers offer a execution
|
|
239 |
flow control, with phases, tags and conditions.
|
|
240 |
|
|
241 |
Example with conditional container execution:
|
|
242 |
|
|
243 |
.. code-block:: xml
|
|
244 |
|
|
245 |
<?xml version="1.0" encoding="UTF-8"?>
|
|
246 |
<container xmlns="http://www.symbianfoundation.org/xml/implml/1"
|
|
247 |
condition="${Feature1.Setting1}"
|
|
248 |
value="true">
|
|
249 |
<!-- Affects to the root container and to the below implementation sections -->
|
|
250 |
|
|
251 |
<content xmlns="http://www.s60.com/xml/content/2">
|
|
252 |
<output dir="content" flatten="true">
|
|
253 |
<input file="test/file1.txt"/>
|
|
254 |
</output>
|
|
255 |
</content>
|
|
256 |
</container>
|
|
257 |
|
|
258 |
In the above example the generation phase will check if the condition is evaluated as true before entering the container.
|
|
259 |
The condition="${Feature1.Setting1}" refers to a Feature value inside the configuration, and value="true" requires
|
|
260 |
that the value of that feature is True. So content copying of test/file1.txt to content/file1.txt is executed only when Setting1
|
|
261 |
is set to True.
|
|
262 |
|
|
263 |
.. _implml-common-invocation-phase:
|
|
264 |
|
|
265 |
Invocation phase
|
|
266 |
^^^^^^^^^^^^^^^^
|
|
267 |
|
|
268 |
Containers and implementations may define the phase in which they are executed, which can be 'pre',
|
|
269 |
'normal' or 'post'. The default phase is determined by the code-level implementation
|
|
270 |
(usually the default phase is 'normal'), but this can be overridden for an
|
|
271 |
implementation by using the ``phase`` element. The element contains a single mandatory
|
|
272 |
attribute, ``name``, which defines the execution phase.
|
|
273 |
|
|
274 |
When using containers in common implml files the ``phase`` of the implementation is always ignored.
|
|
275 |
This enables overriding of the default ``phase`` of the implementations with the containers.
|
|
276 |
|
|
277 |
Example with two implementation in post phase:
|
|
278 |
|
|
279 |
.. code-block:: xml
|
|
280 |
|
|
281 |
<?xml version="1.0" encoding="UTF-8"?>
|
|
282 |
<container xmlns="http://www.symbianfoundation.org/xml/implml/1">
|
|
283 |
<!-- Affects to the root container and to the below implementation sections -->
|
|
284 |
<phase name='post'/>
|
|
285 |
|
|
286 |
<content xmlns="http://www.s60.com/xml/content/2">
|
|
287 |
<output dir="content">
|
|
288 |
<input>
|
|
289 |
<include files="test/file1.txt"/>
|
|
290 |
</input>
|
|
291 |
</output>
|
|
292 |
</content>
|
|
293 |
|
|
294 |
<ruleml xmlns="http://www.s60.com/xml/ruleml/1" xmlns:implml="http://www.symbianfoundation.org/xml/implml/1">
|
|
295 |
<rule>X.Y configures X.Z = X.Y</rule>
|
|
296 |
</ruleml>
|
|
297 |
</container>
|
|
298 |
|
|
299 |
|
|
300 |
Example with two containers in different phases:
|
|
301 |
|
|
302 |
To run implementation in different phases you must define two separate containers
|
|
303 |
that have a separate phase in them. In the below example the root level container
|
|
304 |
is entered and executed in pre,post phase but the first sub-container only in
|
|
305 |
pre phase and the second container in post phase.
|
|
306 |
|
|
307 |
.. code-block:: xml
|
|
308 |
|
|
309 |
<?xml version="1.0" encoding="UTF-8"?>
|
|
310 |
<container xmlns="http://www.symbianfoundation.org/xml/implml/1">
|
|
311 |
<container>
|
|
312 |
<phase name='pre'/>
|
|
313 |
<ruleml xmlns="http://www.s60.com/xml/ruleml/1" xmlns:implml="http://www.symbianfoundation.org/xml/implml/1">
|
|
314 |
<rule>X.Y configures X.Z = X.Y</rule>
|
|
315 |
</ruleml>
|
|
316 |
</container>
|
|
317 |
|
|
318 |
<container>
|
|
319 |
<phase name='post'/>
|
|
320 |
|
|
321 |
<content xmlns="http://www.s60.com/xml/content/2">
|
|
322 |
<output dir="content">
|
|
323 |
<input>
|
|
324 |
<include files="test/file1.txt"/>
|
|
325 |
</input>
|
|
326 |
</output>
|
|
327 |
</content>
|
|
328 |
</container>
|
|
329 |
|
|
330 |
</container>
|
|
331 |
|
|
332 |
.. _implml-common-implementation-tags:
|
|
333 |
|
|
334 |
Implementation tags
|
|
335 |
^^^^^^^^^^^^^^^^^^^
|
|
336 |
|
|
337 |
A concept common to all implementations are implementation tags. These are simple
|
|
338 |
name-value pairs that can be used as one way of filtering the implementations
|
|
339 |
when generating. For example the tag ``target : core``, could be used to tag
|
|
340 |
the particular implementation and, when generating, the same tag could be used to
|
|
341 |
generate only implementations for the target *core*.
|
|
342 |
|
|
343 |
Tags can be defined in implementations that support them or in containers that
|
|
344 |
hold implementations. The overall tags of a container is a sum of all tags defined
|
|
345 |
in its children (including sub-container and implementations)
|
|
346 |
|
|
347 |
To generate only the implementations for the *core* target the following generation command could be used::
|
|
348 |
|
|
349 |
cone generate --impl-tag=target:core
|
|
350 |
|
|
351 |
**Tag elements**
|
|
352 |
|
|
353 |
Tag elements are simple XML elements defining name-value pairs.
|
|
354 |
There can be multiple tags with the same name, in which case the resulting value
|
|
355 |
for that tag will be a list of all the specified values. Examples:
|
|
356 |
|
|
357 |
.. code-block:: xml
|
|
358 |
|
|
359 |
<tag name="target" value="core">
|
|
360 |
<tag name="target" value="rofs2">
|
|
361 |
<tag name="target" value="uda">
|
|
362 |
<tag name="content" value="music">
|
|
363 |
|
|
364 |
Tags can also get their values from ConfML settings, which can be referenced in the usual way:
|
|
365 |
|
|
366 |
.. code-block:: xml
|
|
367 |
|
|
368 |
<tag name="${Feature.TagName}" value="somevalue"/>
|
|
369 |
<tag name="target" value="${Feature.TargetValue}"/>
|
|
370 |
|
|
371 |
When tags are defined to the container it will basically affect on all its sub implementations.
|
|
372 |
|
|
373 |
.. code-block:: xml
|
|
374 |
|
|
375 |
<?xml version="1.0" encoding="UTF-8"?>
|
|
376 |
<container xmlns="http://www.symbianfoundation.org/xml/implml/1">
|
|
377 |
<tag name='target' value='core'/>
|
|
378 |
<tag name='target' value='rofs2'/>
|
|
379 |
|
|
380 |
<content xmlns="http://www.s60.com/xml/content/2">
|
|
381 |
<output dir="content">
|
|
382 |
<input>
|
|
383 |
<include files="test/file1.txt"/>
|
|
384 |
</input>
|
|
385 |
</output>
|
|
386 |
</content>
|
|
387 |
|
|
388 |
<ruleml xmlns="http://www.s60.com/xml/ruleml/1">
|
|
389 |
<rule>X.Y configures X.Z = X.Y</rule>
|
|
390 |
</ruleml>
|
|
391 |
</container>
|
|
392 |
|
|
393 |
In this case both the ContentML and RuleML sections would have the same tags.
|
|
394 |
|
|
395 |
The tag elements can be defined also in some implementation namespaces directly under the root element. E.g. the content in the following
|
|
396 |
content file would be copied to the output only for targets *core* and *rofs2*:
|
|
397 |
|
|
398 |
.. code-block:: xml
|
|
399 |
|
|
400 |
<?xml version="1.0" encoding="UTF-8"?>
|
|
401 |
<content xmlns="http://www.s60.com/xml/content/2" xmlns:implml="http://www.symbianfoundation.org/xml/implml/1">
|
|
402 |
|
|
403 |
<tag name='target' value='core'/>
|
|
404 |
<tag name='target' value='rofs2'/>
|
|
405 |
|
|
406 |
<output dir="content">
|
|
407 |
<input>
|
|
408 |
<include files="test/file1.txt"/>
|
|
409 |
</input>
|
|
410 |
</output>
|
|
411 |
</content>
|
|
412 |
|
|
413 |
|
|
414 |
Filtering Based on Implementation Tags
|
|
415 |
''''''''''''''''''''''''''''''''''''''
|
|
416 |
|
|
417 |
This chapter explains how to create implementation tag specific implementation files.
|
|
418 |
`cone_defaults.cfg` defines the default tags for plugins. If nothing is defined
|
|
419 |
for a certain plugin type then plugin_tags variable is empty. Basically empty
|
|
420 |
tag means that corresponding plugin participates only those generation where
|
|
421 |
generation is not filtered by any implementation tag. If generation defines
|
|
422 |
implementation tag filter then generation is done only for those plugins that
|
|
423 |
match with the filter. If filter is not given filtering is not done and all
|
|
424 |
plugins are participating in generation. In case of customization layer this
|
|
425 |
would mean that uda content could end up to rofs3 section. Filtering is done
|
|
426 |
only for normal and post phases, which means that you don't need to define
|
|
427 |
any tag for ruleml files since they are ran in pre phase. Default value
|
|
428 |
can be overridden in implementation file of the plugin like the following example
|
|
429 |
shows.
|
|
430 |
|
|
431 |
**Example 1:**
|
|
432 |
|
|
433 |
Content plugin default value in cone_defaults.cfg is target:rofs3, which means
|
|
434 |
that by default it participates in generations that doesn't define
|
|
435 |
implementation tags or defines rofs3. However we want create content files that
|
|
436 |
copies stuff to uda. It can be done by overriding tag in .content file by
|
|
437 |
adding the following line there:
|
|
438 |
|
|
439 |
::
|
|
440 |
|
|
441 |
<tag name='target' value='uda'/>
|
|
442 |
|
|
443 |
**Example 2:**
|
|
444 |
|
|
445 |
commsdat.content doesn't contain any tag information and cccccc00.cre should
|
|
446 |
go to rofs3 image. No actions needed because default value for content is rofs3.
|
|
447 |
|
|
448 |
Current default values for plugins:
|
|
449 |
|
|
450 |
::
|
|
451 |
|
|
452 |
CRML = 'core','rofs2','rofs3'
|
|
453 |
GCFML = 'core','rofs2','rofs3'
|
|
454 |
CONTENT = 'rofs3'
|
|
455 |
MAKEML = 'makefile'
|
|
456 |
RULEML = ''
|
|
457 |
IMAGEML = 'rofs3'
|
|
458 |
THEMEML = 'rofs3'
|
|
459 |
|
|
460 |
Workflow for creating new implementation file:
|
|
461 |
|
|
462 |
.. image:: tag-fil.jpg
|
|
463 |
|
|
464 |
|
|
465 |
|
|
466 |
.. _implml-common-temporary-variables:
|
|
467 |
|
|
468 |
Temporary variables (generation-scope temporary ConfML features)
|
|
469 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
470 |
|
|
471 |
The common ImplML namespace also makes it possible to define temporary variables
|
|
472 |
for e.g. passing information between implementations or specifying a constant in only
|
|
473 |
one place. Unlike implementation tags, the temporary variables are not
|
|
474 |
implementation-specific, but they are visible to all implementations, because they are
|
|
475 |
normal ConfML settings. However, overwriting existing features in the
|
|
476 |
configuration is prevented by raising an error when defining a feature that already exists.
|
|
477 |
Therefore the names of used temporary variables should be chosen with care.
|
|
478 |
|
|
479 |
Temporary variables can be defined as follows:
|
|
480 |
|
|
481 |
.. code-block:: xml
|
|
482 |
|
|
483 |
<container xmlns="http://www.symbianfoundation.org/xml/implml/1">
|
|
484 |
<tempVariable ref="TempFeature.IntSetting" type="int" value="123"/>
|
|
485 |
|
|
486 |
<!-- Default type is 'string' -->
|
|
487 |
<tempVariable ref="TempFeature.StringSetting" value="test"/>
|
|
488 |
|
|
489 |
<!-- Initial value from an existing ConfML setting -->
|
|
490 |
<tempVariable ref="TempFeature.StringSetting2" type="int" value="${ExistingFeature.Setting}"/>
|
|
491 |
|
|
492 |
<!-- TempFeature.IntSetting has already been defined, so this will always raise an error -->
|
|
493 |
<tempVariable ref="TempFeature.IntSetting" type="int" value="555"/>
|
|
494 |
|
|
495 |
<!-- Simple sequences can also be defined. -->
|
|
496 |
<tempVariableSequence ref="TempFeature.SequenceSetting">
|
|
497 |
<tempVariable ref="StringSubSetting" type="string"/>
|
|
498 |
<tempVariable ref="IntSubSetting" type="int"/>
|
|
499 |
</tempVariableSequence>
|
|
500 |
</container>
|
|
501 |
|
|
502 |
Temporary variables only support the simplest ConfML setting types:
|
|
503 |
|
|
504 |
- string
|
|
505 |
- int
|
|
506 |
- real
|
|
507 |
- boolean
|
|
508 |
|
|
509 |
**Usage example**
|
|
510 |
|
|
511 |
In this example, we have the need to copy files from a number of different
|
|
512 |
locations to the output directory based on arbitrary logic. To do this, we create
|
|
513 |
a temporary sequence, populate it in a rule, and finally copy the files to
|
|
514 |
the output. This way there is no need to define a custom ConfML setting in
|
|
515 |
a separate file and include it in the project, so all implementation-specific
|
|
516 |
concerns are on the implementation side and do not leak to the interface (ConfML).
|
|
517 |
|
|
518 |
.. code-block:: xml
|
|
519 |
|
|
520 |
<?xml version="1.0" encoding="UTF-8"?>
|
|
521 |
<container xmlns="http://www.symbianfoundation.org/xml/implml/1">
|
|
522 |
|
|
523 |
<!-- Temporary sequence setting for storing a generation-time created list of files to copy -->
|
|
524 |
<tempVariableSequence ref="FileCopyTemp.Files">
|
|
525 |
<tempVariable ref="Path" type="string"/>
|
|
526 |
</tempVariableSequence>
|
|
527 |
|
|
528 |
<!-- Rule for populating the temporary sequence -->
|
|
529 |
<ruleml xmlns="http://www.s60.com/xml/ruleml/2">
|
|
530 |
<rule>True configures FileCopyTemp.Files = {% get_file_list() %}</rule>
|
|
531 |
|
|
532 |
<!-- Python script containing the get_file_list() -->
|
|
533 |
<!-- function used above. It does whatever tricks -->
|
|
534 |
<!-- are necessary to obtain the list of files to -->
|
|
535 |
<!-- copy. -->
|
|
536 |
<eval_globals file="scripts/file_copy.py"/>
|
|
537 |
</ruleml>
|
|
538 |
|
|
539 |
<!-- ContentML implementation for copying the created file list to output -->
|
|
540 |
<content xmlns="http://www.s60.com/xml/content/3">
|
|
541 |
<output dir="some_dir/">
|
|
542 |
<input files="${FileCopyTemp.Files.Path}"/>
|
|
543 |
</output>
|
|
544 |
</content>
|
|
545 |
|
|
546 |
</container>
|
|
547 |
|
|
548 |
|
|
549 |
.. _implml-common-setting-refs-override:
|
|
550 |
|
|
551 |
Overriding setting references
|
|
552 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
553 |
|
|
554 |
During generation, implementation instance may be filtered based on the setting references
|
|
555 |
they use. Normally the set of references should be correctly determined by the implementation
|
|
556 |
instance itself, but if for some reason the references need to be overridden in the
|
|
557 |
ImplML file, it is possible by using the common ``settingRefsOverride`` element.
|
|
558 |
The element can be used in two ways:
|
|
559 |
|
|
560 |
- It may contain a set of ``settingRef`` sub-elements defining the setting
|
|
561 |
references
|
|
562 |
- It may contain a ``refsIrrelevant`` attribute that, if set to ``true``,
|
|
563 |
specifies that setting references are irrelevant for the implementation. In
|
|
564 |
this case the implementation will never be filtered out based on setting
|
|
565 |
references during generation.
|
|
566 |
|
|
567 |
**Examples**
|
|
568 |
|
|
569 |
.. code-block:: xml
|
|
570 |
|
|
571 |
<settingRefsOverride refsIrrelevant="true"/>
|
|
572 |
|
|
573 |
.. code-block:: xml
|
|
574 |
|
|
575 |
<settingRefsOverride>
|
|
576 |
<settingRef value="SomeFeature.SomeSetting"/>
|
|
577 |
<settingRef value="SomeFeature.SomeOtherSetting"/>
|
|
578 |
</settingRefsOverride>
|
|
579 |
|
|
580 |
|
|
581 |
.. _implml-common-setting-output-dir-override:
|
|
582 |
|
|
583 |
Overriding output directory parts
|
|
584 |
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
585 |
|
|
586 |
The final output directory for implementation output is consists of three parts:
|
|
587 |
|
|
588 |
- *Output root*, speficied from the command in the ``generate`` action
|
|
589 |
- *Output sub-dir*, specified in a setting file (e.g. ``content/`` for CRML in
|
|
590 |
iMaker variant content output settings file)
|
|
591 |
- *Plug-in output*, specified in a setting file (e.g. ``private/10202BE9`` for CRML)
|
|
592 |
- *Output file name*, specified in the implementation file in some way, may also
|
|
593 |
contain some intermediary directories before the actual file name
|
|
594 |
(e.g. ``12345678.txt`` for a CRML file with repository UID 0x12345678)
|
|
595 |
|
|
596 |
Of these, the two first may be overridden in the implementation file using
|
|
597 |
the common ImplML elements ``outputRootDir`` and ``outputSubDir``. These elements
|
|
598 |
may contain a single ``value`` attribute containing the directory name.
|
|
599 |
|
|
600 |
**Examples**
|
|
601 |
|
|
602 |
.. code-block:: xml
|
|
603 |
|
|
604 |
<outputRootDir value="\epoc32\data"/>
|
|
605 |
<outputSubDir value="widgets"/>
|
|
606 |
|
|
607 |
|
|
608 |
.. code-block:: xml
|
|
609 |
|
|
610 |
<?xml version="1.0" encoding="UTF-8"?>
|
|
611 |
<container xmlns="http://www.symbianfoundation.org/xml/implml/1">
|
|
612 |
|
|
613 |
<!-- Temporary sequence setting for storing a generation-time created list of files to copy -->
|
|
614 |
<outputRootDir value="\epoc32\data"/>
|
|
615 |
<outputSubDir value="widgets"/>
|
|
616 |
|
|
617 |
<!-- ContentML implementation for copying the created file list to output -->
|
|
618 |
<content xmlns="http://www.s60.com/xml/content/3">
|
|
619 |
<output dir="some_dir/">
|
|
620 |
<input file="test.wgz"/>
|
|
621 |
</output>
|
|
622 |
</content>
|
|
623 |
|
|
624 |
</container>
|
|
625 |
|
|
626 |
In the above example the content is copied to \epoc32\data\widgets\some_dir\text.wgz.
|
|
627 |
|
|
628 |
|
|
629 |
.. rubric:: Footnotes
|
|
630 |
|
|
631 |
.. [#multi-content-note] In this case the run-time behavior would still be same; ContentML
|
|
632 |
allows multiple ``output`` elements. However, this might not be the case for all
|
|
633 |
implementation languages.
|
|
634 |
|
|
635 |
.. [#legacy-implml-root-name-note] The specifications for the legacy implementation
|
|
636 |
languages CRML and GenConfML do give the root element names, and say that each
|
|
637 |
implementation must be in its own crml/gcfml file.
|
|
638 |
It is recommended to stick to this convention for these two implementation languages
|
|
639 |
also in the future. Indeed, using them in a multi-implementation file has not been
|
|
640 |
tested and may not even work correctly.
|