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