README.md
1# XML Generator
2
3This set of tools is used to transform files written in the pseudo language
4(referred to as "Extended Domain Description") into XML parameter-framework
5Settings files. The extension of such files are usually `.edd` or `.pfw`.
6
7## EDD Syntax
8
9### Introduction
10
11The Extended Domain Description (EDD) has been designed to help describing
12multiple and complex PFW settings. It is a recursive structured language with
13tabulation indentation (inspired from python).
14
15It has several advantages :
16
17- Easy to write
18- Easy to read
19- Nearly twice as compact as it's equivalent in XML
20- Less merge conflicts and easy solving
21- Can be split in multiple files
22- Intuitive syntax and comprehension when you know the PFW concepts
23
24But has a couple of drawbacks:
25
26- it is not supported natively by the PFW. It needs to be compiled into XML.
27- it supports only tabulation indentation
28
29### Concepts
30
31The EDD adds a couple of concepts over the PFW ones in order to extend the
32concepts used in the Settings files.
33
34#### DomainGroup
35A domain group can contain other domain groups and domains. Those inner domains
36will be prefixed with the name of the domain group.
37
38*The tag for domain groups is `domainGroup`.*
39
40*Example*
41
42```
43domainGroup: Codec
44
45 domain: Flow
46 conf: Unmute
47 /Audio/codec/playback/master_mute = 0
48 conf: Mute
49 /Audio/codec/playback/master_mute = 1
50
51 domainGroup: Configure
52 RoutageState Includes Configure
53
54 domain: IHF
55 [...]
56```
57
58will create the domains :
59
60- Codec.Flow (containing the Unmute and Mute configurations)
61- Codec.Configure.IHF (The `RoutageState Includes Configure` rule will apply to
62 all configurations inside the `Codec.Configure.*` domains)
63
64#### ConfigurationGroup
65A configuration group can contain other configuration groups and
66configurations. Those inner configurations will be prefixed with the name of
67the configuration group.
68
69*The tag for configuration groups is `confGroup`.*
70
71*Example*
72
73```
74domain: ExternalDSP
75
76 conf: TTY
77 [...]
78
79 confGroup: CsvCall
80 Mode Is InCsvCall
81
82 confGroup: Output
83 conf: IHF
84 [...]
85 conf: Earpiece
86 [...]
87```
88
89will create the following configurations in the `ExternalDSP` domain:
90
91- TTY
92- CsvCall.Output.IHF
93- CsvCall.Outout.Earpiece
94
95As with domainGroup, the `Mode Is InCsvCall` rule applies to all
96`CsvCall.Output.*` configurations in the `ExternalDSP` domain.
97
98#### ConfigurationType
99A configuration type is the specialization concept. When defining a
100configuration type, any configuration in the containing domain (or domain
101group) with the same name will inherit the configuration type rule.
102
103*The tag for configuration types is `confType`.*
104
105*Example*
106
107```
108domain: ExternalDSP
109 confType: Bind
110 Mode Is InCsvCall
111
112 confGroup: Modem
113
114 conf: Bind
115 BandRinging is Modem
116 [...]
117 conf: Unbind
118 [...]
119```
120
121will create the following configurations in the `ExternalDSP` domain:
122
123- Modem.Bind (applicable if `Mode Is InCsvCall` and `BandRinging is Modem`)
124- Modem.Unbind (no rule, i.e. applicable by default)
125
126#### Component
127A component can be used to factorize parameter names in configurations.
128
129*The tag for components is `component`.*
130
131```
132domain: Foo
133 conf: Bar
134 component: /System/some_element
135 parameter1 = "egg"
136 parameter2 = "spam"
137 /System/another_element/parameter3 = 42
138```
139
140will create a domain Foo containing a configuration Bar (no rule, i.e.
141applicable by default) that will set these 3 parameters:
142
143- `/System/some_element/parameter1` to "egg"
144- `/System/some_element/parameter2` to "spam"
145- `/System/another_element/parameter3` to 42
146
147## Preprocessor
148
149The xmlGenerator uses m4 to preprocess the files before parsing them. You may
150use any macro implemented by m4, such as `define` and `include`. This is
151deprecated and we do not recommend using it.
152
153## Style
154
155Here are a few recommendations to follow when writing Settings using EDD:
156
157### Rules
158
159- if you need to modify a rule, do not hesitate to rework it globally.
160- keep rule depth under 3-4.
161- factorize the rules, taking 3 minute to write a Karnaugh map is worth it.
162- comment, comment, comment !
163
164### Enum Parameters
165
166When setting an enum parameter value, use its lexical space, not its numerical
167space. E.g. don't write
168
169 /Subsystem/frequency = 5
170
171Write instead:
172
173 /Subsystem/frequency = f48kHz
174
175### String Parameters
176
177In an EDD file, string parameters may not contain newlines. Apart from that,
178all characters are supported. Also, leading spaces are ignored. Do *not*
179surround a string parameter's value with quotes. Don't write:
180
181 /Subsystem/string_parameter = "some string value"
182
183Write instead:
184
185 /Subsystem/string_parameter = some string value
186
187## XML Generation
188
189Once a `.edd` file is ready to be tested, it is possible to generate the
190corresponding XML file.
191
192### domainGenerator.py
193
194This python tool is self-documented: you may run `domainGenerator.py -h` to get
195its full usage.
196
197It prints the resulting XML on the standard output. Its syntax is:
198
199 domainGenerator.py [-h] --toplevel-config TOPLEVEL_CONFIG_FILE
200 --criteria CRITERIA_FILE
201 [--initial-settings XML_SETTINGS_FILE]
202 [--add-domains XML_DOMAIN_FILE [XML_DOMAIN_FILE ...]]
203 [--add-edds EDD_FILE [EDD_FILE ...]]
204 [--schemas-dir SCHEMAS_DIR]
205 [--target-schemas-dir TARGET_SCHEMAS_DIR]
206 [--validate] [--verbose]
207
208*Explanation:*
209
210- The "top-level configuration file" is the same as the one provided by the
211 parameter-framework client to instantiate it. The plugins referenced in that
212 file are not used.
213- The "criteria file" lists all criteria and possible values used in the EDD
214 files.
215- The initial settings file is an XML file containing a single
216 `<ConfigurableDomains>` (plural) tag; it may not overlap with the other
217 sources below. It will be imported into the settings.
218- Domain files are XML files, each containing a single `<ConfigurableDomain>`
219 (singular) tag. They all will be imported in the order of the command line
220 into the settings.
221- EDD files are all the files in EDD syntax you want to add to your Settings.
222- The optional `--schemas-dir` argument lets you change the directory
223 containing the XML Schemas in the context of the XML generation only (see the
224 `--validate` option).
225- The optional `--target-schemas-dir` argument lets you change the directory
226 containing the XML Schemas on the target device (the one the
227 parameter-framework will run on) if it is using Schema validation and if
228 different than the default.
229- The optional `--validate` option check the validity of all XML files involved
230 in the process.
231
232*Regarding XML Domain files and EDD files:*
233
234In theory, the order doesn't matter but since files are parsed in the order of
235the command line, you'll get different (although equivalent) files if you
236change the order, which makes it more difficult to compare versions.
237
238
239*The "criteria file" must look something like this:*
240
241```
242ExclusiveCriterion Criterion1Name : Criterion1Value1 Criterion1Value2
243InclusiveCriterion Criterion2Name : Criterion2Value1 Criterion2Value2
244```
245
246I.e. One criterion by line, starting by its kind, then its name, followed by a
247semicolon and then all possible values separated by spaces.
248
249### hostDomainGenerator.sh
250
251**This script is now deprecated and replaced by domainGenerator.py
252(see above).**
253
254It prints the resulting XML on the standard output. Its syntax is:
255
256 hostDomainGenerator.sh [--validate] <top-level configuration file> <criteria file> <EDD files...>
257
258See domainGenerator.py above for the explanation of the arguments.
259
260
261#### How it works
262TODO
263