docs/modules/cli/pages/usage.adoc

   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 has a Git-like user interface with the following
  28 available commands:
  29
  30 <<generate-command,`generate`>>::
  31     Generate the C source and CTF metadata stream files of a tracer
  32     from a xref:yaml:index.adoc[YAML configuration file].
  33
  34 <<show-effective-configuration-command,`show-effective-configuration`>>::
  35     Print the _effective_ YAML configuration file for a given YAML
  36     configuration file and inclusion directories.
  37
  38 <<show-configuration-version-command,`show-configuration-version`>>::
  39     Print 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 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 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 inclusion files before the
 136 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 standard inclusion files
 175   (like `stdint.yaml`).
 176
 177 [[generate-metadata-dir-option]]`-m __MDIR__`::
 178 `--metadata-dir=__MDIR__`::
 179     Write the CTF metadata stream file to the directory `__MDIR__`
 180     instead of the current working directory.
 181
 182 [[generate-prefix-option]]`-p __PREFIX__`::
 183 `--prefix=__PREFIX__`::
 184     Override the default or `__CONFIG-PATH__` file's file and
 185     identifier prefixes with:
 186 +
 187 File name prefix:::
 188     `__PREFIX__`, without trailing underscores.
 189 Identifier prefix:::
 190     `__PREFIX__`
 191
 192 +
 193 --
 194 The default file name prefix is `barectf`.
 195
 196 The default identifier prefix is `barectf_`.
 197 --
 198
 199 [[show-effective-configuration-command]]
 200 == `show-effective-configuration` command
 201
 202 === Synopses
 203
 204 Show effective configuration:
 205
 206 [.cl]
 207 [verse]
 208 *barectf show-effective-configuration* pass:[[]xref:#show-effective-configuration-include-dir-option[--include-dir]=__IDIR__]...
 209         pass:[[]xref:#show-effective-configuration-ignore-include-not-found-option[--ignore-include-not-found]pass:[\]] _CONFIG-PATH_
 210
 211 Print command's brief help:
 212
 213 [.cl]
 214 [verse]
 215 *barectf show-effective-configuration* xref:#show-effective-configuration-help-option[`--help`]
 216
 217 === Command name aliases
 218
 219 * `show-effective-config`
 220 * `show-effective-cfg`
 221
 222 === Description
 223
 224 The `barectf show-effective-configuration` command reads the
 225 xref:yaml:index.adoc[YAML configuration file] `__CONFIG-PATH__` and
 226 prints an equivalent, _effective_ YAML configuration.
 227
 228 See the xref:yaml:index.adoc#stages[processing stages] of a YAML
 229 configuration file to learn what an effective configuration is.
 230
 231 Moreover, the `show-effective-configuration` command validates the
 232 `__CONFIG-PATH__` file. In other words, if the command
 233 <<exit-status,exits>> with status{nbsp}0, the
 234 <<generate-command,`generate` command>> using the same options and
 235 `__CONFIG-PATH__` file would also succeed.
 236
 237 Add directories to be searched into for inclusion files before the
 238 default inclusion directories with the repeatable
 239 <<show-effective-configuration-include-dir-option,`--include-dir`>> option.
 240
 241 By default, if `barectf` can't find an inclusion file while processing
 242 the `__CONFIG-PATH__` file, the command prints an error and
 243 <<exit-status,exits>> with a non-zero status. Force
 244 `barectf show-effective-configuration` to continue silently instead
 245 with its
 246 <<show-effective-configuration-ignore-include-not-found-option,`--ignore-include-not-found`>>
 247 option.
 248
 249 === Options
 250
 251 [[show-effective-configuration-help-option]]`-h`::
 252 `--help`::
 253     Print the `show-effective-configuration` command's
 254     brief help and exit.
 255
 256 [[show-effective-configuration-ignore-include-not-found-option]]`--ignore-include-not-found`::
 257     Continue to process the `__CONFIG-PATH__` file when inclusion
 258     files are not found.
 259
 260 [[show-effective-configuration-include-dir-option]]`-I __IDIR__`::
 261 `--include-dir=__IDIR__`::
 262     Add `__IDIR__` to the list of directories to be searched into for
 263     inclusion files before the default inclusion directories.
 264 +
 265 The default inclusion directories are:
 266 +
 267 . The current working directory.
 268 . The directory containing the standard inclusion files
 269   (like `stdint.yaml`).
 270
 271 [[show-configuration-version-command]]
 272 == `show-configuration-version` command
 273
 274 === Synopses
 275
 276 Show configuration file's version:
 277
 278 [.cl]
 279 [verse]
 280 *barectf show-configuration-version* _CONFIG-PATH_
 281
 282 Print command's brief help:
 283
 284 [.cl]
 285 [verse]
 286 *barectf show-configuration-version* xref:#show-configuration-version-help-option[`--help`]
 287
 288 === Command name aliases
 289
 290 * `show-config-version`
 291 * `show-cfg-version`
 292
 293 === Description
 294
 295 The `barectf show-configuration-version` command reads the
 296 xref:yaml:index.adoc[YAML configuration file] `__CONFIG-PATH__` and
 297 prints its version, which is either 2 or 3.
 298
 299 The `show-configuration-version` does _not_ validate the
 300 `__CONFIG-PATH__` file.
 301
 302 === Options
 303
 304 [[show-configuration-version-help-option]]`-h`::
 305 `--help`::
 306     Print the `show-configuration-version` command's brief help
 307     and exit.
 308
 309 [[exit-status]]
 310 == Exit status
 311
 312 0::
 313     Success
 314
 315 Not 0::
 316     Error