Debian Codegraph @

docs/modules/yaml/pages/cfg-obj.adoc

raw
1 = YAML configuration object
2
3 The _**configuration object**_ is the root of a barectf YAML
4 configuration document. It describes a complete barectf configuration.
5
6 The configuration object must have the YAML tag
7 `tag:barectf.org,2020/3/config`.
8
9 The configuration object has a mandatory xref:trace-obj.adoc[trace
10 object] and <<opts-obj,options>>.
11
12 == Properties
13
14 [%autowidth.stretch]
15 |===
16 |Name |Type |Description |{req-abbr} |Default
17
18 |`options`
19 |<<opts-obj>>
20 |Configuration options.
21 |No
22 |See <<opts-obj>> for default values.
23
24 |[[trace-prop]]`trace`
25 |xref:trace-obj.adoc[Trace object]
26 |Configuration's trace.
27 |Yes
28 |
29 |===
30
31 [[opts-obj]]
32 == Options object
33
34 The options of a configuration object.
35
36 === Properties
37
38 [%autowidth.stretch]
39 |===
40 |Name |Type |Description |Default
41
42 |`code-generation`
43 |<<code-gen-opts-obj>>
44 |Code generation options.
45 |See <<code-gen-opts-obj>> for default values.
46 |===
47
48 [[code-gen-opts-obj]]
49 == Code generation options object
50
51 The code generation options of a configuration object.
52
53 === Properties
54
55 All the properties are optional.
56
57 [%autowidth.stretch, cols="d,d,a,d"]
58 |===
59 |Name |Type |Description |Default
60
61 |[[prefix-prop]]`prefix`
62 |String or <<prefix-obj,prefix object>>
63 |Identifier and file name prefixes.
64
65 If the value is the string `__PREFIX__`, then the identifier prefix is
66 `__PREFIX___` and the file name prefix is `__PREFIX__`.
67 |The identifier prefix `barectf_` and the file name prefix `barectf`.
68
69 |`header`
70 |<<code-gen-header-opts-obj>>
71 |C{nbsp}header generation options.
72 |See <<code-gen-header-opts-obj>> default values.
73 |===
74
75 [[prefix-obj]]
76 == Prefix object
77
78 Identifier and file name prefixes.
79
80 === Properties
81
82 All the properties are required.
83
84 [%autowidth.stretch, cols="d,d,a"]
85 |===
86 |Name |Type |Description
87
88 |`file-name`
89 |String
90 |Prefix of any C{nbsp}file which barectf generates.
91
92 barectf adds `-` between this prefix and other file name parts if
93 needed.
94
95 This prefix must only contain valid characters for a file name.
96
97 |`identifier`
98 |String
99 |Prefix of any public C identifier which barectf generates.
100
101 barectf does _not_ add anything between this prefix and the rest of the
102 identifier.
103
104 For example, if this prefix is `acme_corp_`, then a tracing function
105 name could be `+acme_corp_trace_my_event()+`.
106
107 This prefix must be a valid C{nbsp}identifier.
108 |===
109
110 [[code-gen-header-opts-obj]]
111 == Code generation header options object
112
113 The C{nbsp}header generation options of a configuration object.
114
115 === Properties
116
117 All the properties are optional.
118
119 [%autowidth.stretch, cols="d,d,a,d", role="can-break"]
120 |===
121 |Name |Type |Description |Default
122
123 |[[iden-prefix-def-prop]]`identifier-prefix-definition`
124 |Boolean
125 |If this property is true, then barectf generates a public
126 C{nbsp}preprocessor definition named `_BARECTF_IDENTIFIER_PREFIX` which
127 is set to the configuration's <<prefix-prop,identifier prefix>>.
128 |False
129
130 |[[def-dst-name-def-prop]]`default-data-stream-type-name-definition`
131 |Boolean
132 |If this property is true, then barectf generates a public
133 C{nbsp}preprocessor definition named
134 `_BARECTF_DEFAULT_DATA_STREAM_TYPE_NAME` which is set to the name of the
135 trace type's
136 xref:dst-obj.adoc#is-def-prop[default data stream type].
137 |False
138 |===
139
140 == Examples
141
142 NOTE: The following examples omit the <<trace-prop,trace object>> for
143 clarity.
144
145 .Basic configuration object.
146 ====
147 [source,yaml]
148 ----
149 --- !<tag:barectf.org,2020/3/config>
150 trace:
151 # ...
152 ----
153 ====
154
155 .Configuration object with custom <<prefix-obj,prefixes>>.
156 ====
157 [source,yaml]
158 ----
159 --- !<tag:barectf.org,2020/3/config>
160 options:
161 code-generation:
162 prefix:
163 file-name: acme-corp
164 identifier: acme_corp_
165 trace:
166 # ...
167 ----
168 ====
169
170 .Configuration object with <<code-gen-header-opts-obj,identifier and default data stream type name C{nbsp}preprocessor definitions>>.
171 ====
172 [source,yaml]
173 ----
174 --- !<tag:barectf.org,2020/3/config>
175 options:
176 code-generation:
177 header:
178 identifier-prefix-definition: true
179 default-data-stream-type-name-definition: true
180 trace:
181 # ...
182 ----
183 ====
184
185 .Basic configuration object with a YAML directive.
186 ====
187 This https://yaml.org/spec/1.2/spec.html#id2781553[YAML directive]
188 indicates that the YAML document honours the YAML{nbsp}1.2
189 specification.
190
191 [source,yaml]
192 ----
193 %YAML 1.2
194 --- !<tag:barectf.org,2020/3/config>
195 trace:
196 # ...
197 ----
198 ====