Debian Codegraph @

docs/modules/cli/pages/usage.adoc

raw
1 = `barectf` CLI tool usage
2
3 barectf ships with the `barectf` command-line interface (CLI) tool.
4
5 == General synopses
6
7 Run a `barectf` command:
8
9 [.cl]
10 [verse]
11 *barectf* _COMMAND_ _COMMAND-ARGUMENTS_
12
13 Print the version of `barectf`:
14
15 [.cl]
16 [verse]
17 *barectf* pass:[[]xref:#version-option[--version]pass:[\]]
18
19 Print brief general help:
20
21 [.cl]
22 [verse]
23 *barectf* pass:[[]xref:#help-option[--help]pass:[\]]
24
25 == General description
26
27 The `barectf` tool offers a https://git-scm.com/[Git]-like
28 user interface with the following available commands:
29
30 <<generate-command,`generate`>>::
31 Generates the C{nbsp}source and CTF metadata stream files of a
32 tracer from a xref:yaml:index.adoc[YAML configuration file].
33
34 <<show-effective-configuration-command,`show-effective-configuration`>>::
35 Prints the xref:yaml:index.adoc#stages[_effective_] version of
36 a YAML configuration file.
37
38 <<show-configuration-version-command,`show-configuration-version`>>::
39 Prints the major version (2 or 3) of a YAML configuration file.
40
41 == General options
42
43 [[help-option]]`-h`::
44 `--help`::
45 Print brief general help and exit.
46
47 [[version-option]]`-V`::
48 `--version`::
49 Print the version of `barectf` and exit.
50
51 [[generate-command]]
52 == `generate` command
53
54 === Synopses
55
56 Generate files from a xref:yaml:index.adoc[YAML configuration file]:
57
58 [.cl]
59 [verse]
60 *barectf generate* pass:[[]xref:#generate-prefix-option[--prefix]=__PREFIX__] pass:[[]xref:#generate-metadata-dir-option[--metadata-dir]=__MDIR__]
61 pass:[[]xref:#generate-headers-dir-option[--headers-dir]=__HDIR__] pass:[[]xref:#generate-code-dir-option[--code-dir]=__CDIR__]
62 pass:[[]xref:#generate-include-dir-option[--include-dir]=__IDIR__]...
63 pass:[[]xref:#generate-ignore-include-not-found-option[--ignore-include-not-found]pass:[\]] _CONFIG-PATH_
64
65 Print command's brief help:
66
67 [.cl]
68 [verse]
69 *barectf generate* xref:#generate-help-option[--help]
70
71 === Command name aliases
72
73 * `gen`
74
75 === Description
76
77 The `barectf generate` command reads the xref:yaml:index.adoc[YAML
78 configuration file] `__CONFIG-PATH__` to produce:
79
80 [%autowidth.stretch, cols="d,a"]
81 |===
82 |File name |Description
83
84 |`__MDIR__/metadata`
85 |The CTF metadata stream file.
86
87 |`__HDIR__/__FPREFIX__.h`
88 |The generated tracer's public C{nbsp}header file.
89
90 |`__HDIR__/__FPREFIX__-bitfield.h`
91 |Internal macros for the generated tracer (included by `__FPREFIX__.c`).
92
93 |`__CDIR__/__FPREFIX__.c`
94 |The generated tracer's C{nbsp}source code.
95 |===
96
97 See xref:lel[Build the generated C{nbsp}source code] to learn how to
98 build the C{nbsp}source which the `generate` command produces.
99
100 In the list above, `__FPREFIX__` is:
101
102 Without the <<generate-prefix-option,`--prefix`>> option::
103 If the `__CONFIG-PATH__` file has a file name xref:yaml:cfg-obj.adoc#prefix-prop[prefix option]:::
104 The `__CONFIG-PATH__` file's file name prefix option.
105 Otherwise:::
106 `barectf`
107
108 With the <<generate-prefix-option,`--prefix`>> option::
109 `__PREFIX__`, without trailing underscores.
110 +
111 For example, if `__PREFIX__` is `my_tracer_`, then `__FPREFIX__` is
112 `my_tracer`.
113
114 By default, `__MDIR__`, `__HDIR__`, and `__CDIR__` are the current
115 working directory. Use the
116 <<generate-metadata-dir-option,`--metadata-dir`>>,
117 <<generate-headers-dir-option,`--headers-dir`>>, and
118 <<generate-code-dir-option,`--code-dir`>> to specify other output
119 directories.
120
121 Therefore, by default, the `generate` command writes the `metadata`,
122 `barectf.h`, `barectf-bitfield.h`, and `barectf.c` files to the current
123 working directory.
124
125 If you use the <<prefix-option,`--prefix`>> option, then all the
126 public C{nbsp}identifiers in `__FPREFIX__.h` and `__FPREFIX__.c` begin
127 with `__PREFIX__`. Otherwise, they begin with:
128
129 If the `__CONFIG-PATH__` file has an identifier xref:yaml:cfg-obj.adoc#prefix-prop[prefix option]::
130 The `__CONFIG-PATH__` file's identifier prefix option.
131
132 Otherwise::
133 `barectf_`
134
135 Add directories to be searched into for xref:yaml:include.adoc[inclusion
136 files] before the default inclusion directories with the repeatable
137 <<generate-include-dir-option,`--include-dir`>> option.
138
139 By default, if `barectf` can't find an inclusion file while processing
140 the `__CONFIG-PATH__` file, the command prints an error and
141 <<exit-status,exits>> with a non-zero status. Force
142 `barectf generate` to continue silently instead with its
143 <<generate-ignore-include-not-found-option,`--ignore-include-not-found`>>
144 option.
145
146 === Options
147
148 [[generate-code-dir-option]]`-c __CDIR__`::
149 `--code-dir=__CDIR__`::
150 Write the C{nbsp}source file to the directory `__CDIR__` instead of
151 the current working directory.
152
153 [[generate-headers-dir-option]]`-H __HDIR__`::
154 `--headers-dir=__HDIR__`::
155 Write C{nbsp}header files to the directory `__HDIR__` instead of
156 the current working directory.
157
158 [[generate-help-option]]`-h`::
159 `--help`::
160 Print the `generate` command's brief help and exit.
161
162 [[generate-ignore-include-not-found-option]]`--ignore-include-not-found`::
163 Continue to process the `__CONFIG-PATH__` file when inclusion
164 files are not found.
165
166 [[generate-include-dir-option]]`-I __IDIR__`::
167 `--include-dir=__IDIR__`::
168 Add `__IDIR__` to the list of directories to be searched into for
169 inclusion files before the default inclusion directories.
170 +
171 The default inclusion directories are:
172 +
173 . The current working directory.
174 . The directory containing the
175 xref:yaml:include.adoc#std[standard partial YAML files]
176 (like `stdint.yaml`).
177
178 [[generate-metadata-dir-option]]`-m __MDIR__`::
179 `--metadata-dir=__MDIR__`::
180 Write the CTF metadata stream file to the directory `__MDIR__`
181 instead of the current working directory.
182
183 [[generate-prefix-option]]`-p __PREFIX__`::
184 `--prefix=__PREFIX__`::
185 Override the default or `__CONFIG-PATH__` file's file and
186 identifier prefixes with:
187 +
188 File name prefix:::
189 `__PREFIX__`, without trailing underscores.
190 Identifier prefix:::
191 `__PREFIX__`
192
193 +
194 --
195 `__PREFIX__` must be a valid C{nbsp}identifier.
196
197 The default file name prefix is `barectf`.
198
199 The default identifier prefix is `barectf_`.
200 --
201
202 [[show-effective-configuration-command]]
203 == `show-effective-configuration` command
204
205 === Synopses
206
207 Show the xref:yaml:index.adoc#stages[effective] version of a
208 xref:yaml:index.adoc[YAML configuration file]:
209
210 [.cl]
211 [verse]
212 *barectf show-effective-configuration* pass:[[]xref:#show-effective-configuration-include-dir-option[--include-dir]=__IDIR__]...
213 pass:[[]xref:#show-effective-configuration-ignore-include-not-found-option[--ignore-include-not-found]pass:[\]] _CONFIG-PATH_
214
215 Print command's brief help:
216
217 [.cl]
218 [verse]
219 *barectf show-effective-configuration* xref:#show-effective-configuration-help-option[`--help`]
220
221 === Command name aliases
222
223 * `show-effective-config`
224 * `show-effective-cfg`
225
226 === Description
227
228 The `barectf show-effective-configuration` command reads the
229 xref:yaml:index.adoc[YAML configuration file] `__CONFIG-PATH__` and
230 prints an equivalent, _effective_ YAML configuration.
231
232 See the xref:yaml:index.adoc#stages[processing stages] of a YAML
233 configuration file to learn what an effective configuration is.
234
235 Moreover, the `show-effective-configuration` command validates the
236 `__CONFIG-PATH__` file. In other words, if the command
237 <<exit-status,exits>> with status{nbsp}0, the
238 <<generate-command,`generate` command>> using the same options and
239 `__CONFIG-PATH__` file would also succeed.
240
241 Add directories to be searched into for inclusion files before the
242 default inclusion directories with the repeatable
243 <<show-effective-configuration-include-dir-option,`--include-dir`>> option.
244
245 By default, if `barectf` can't find an inclusion file while processing
246 the `__CONFIG-PATH__` file, the command prints an error and
247 <<exit-status,exits>> with a non-zero status. Force
248 `barectf show-effective-configuration` to continue silently instead
249 with its
250 <<show-effective-configuration-ignore-include-not-found-option,`--ignore-include-not-found`>>
251 option.
252
253 === Options
254
255 [[show-effective-configuration-help-option]]`-h`::
256 `--help`::
257 Print the `show-effective-configuration` command's
258 brief help and exit.
259
260 [[show-effective-configuration-ignore-include-not-found-option]]`--ignore-include-not-found`::
261 Continue to process the `__CONFIG-PATH__` file when inclusion
262 files are not found.
263
264 [[show-effective-configuration-include-dir-option]]`-I __IDIR__`::
265 `--include-dir=__IDIR__`::
266 Add `__IDIR__` to the list of directories to be searched into for
267 inclusion files before the default inclusion directories.
268 +
269 The default inclusion directories are:
270 +
271 . The current working directory.
272 . The directory containing the
273 xref:yaml:include.adoc#std[standard partial YAML files]
274 (like `stdint.yaml`).
275
276 [[show-configuration-version-command]]
277 == `show-configuration-version` command
278
279 === Synopses
280
281 Show a xref:yaml:index.adoc[YAML configuration file]'s version:
282
283 [.cl]
284 [verse]
285 *barectf show-configuration-version* _CONFIG-PATH_
286
287 Print command's brief help:
288
289 [.cl]
290 [verse]
291 *barectf show-configuration-version* xref:#show-configuration-version-help-option[`--help`]
292
293 === Command name aliases
294
295 * `show-config-version`
296 * `show-cfg-version`
297
298 === Description
299
300 The `barectf show-configuration-version` command reads the
301 xref:yaml:index.adoc[YAML configuration file] `__CONFIG-PATH__` and
302 prints its version, which is either 2 or 3.
303
304 The `show-configuration-version` does _not_ validate the
305 `__CONFIG-PATH__` file like the
306 <<show-effective-configuration-command,`show-effective-configuration`
307 command>> does.
308
309 === Options
310
311 [[show-configuration-version-help-option]]`-h`::
312 `--help`::
313 Print the `show-configuration-version` command's brief help
314 and exit.
315
316 [[exit-status]]
317 == Exit status
318
319 0::
320 Success
321
322 Not 0::
323 Error