docs/modules/cli/pages/index.adoc

   1 = Generate files from a YAML configuration file
   2
   3 barectf ships with the `barectf` command-line interface (CLI) tool.
   4
   5 The `barectf` CLI tool has a command interface, like
   6 https://git-scm.com/[Git].
   7
   8 This page focuses on the `barectf generate` command. See
   9 xref:usage.adoc[] for the complete CLI tool's documentation.
  10
  11 == Generate files from a YAML configuration
  12
  13 Use the xref:usage.adoc#generate-command[`barectf generate` command] to
  14 generate files from a barectf xref:yaml:index.adoc[YAML configuration
  15 file]:
  16
  17 [.cl]
  18 [verse]
  19 [.prompt]##$## barectf generate my-config.yaml
  20
  21 On success, this command writes the following files to the current
  22 working directory:
  23
  24 [%autowidth.stretch, cols="d,a"]
  25 |===
  26 |File name |Description
  27
  28 |[[metadata-file]]`metadata`
  29 |The CTF metadata stream file.
  30
  31 You'll need to place this file in a directory with the
  32 xref:how-barectf-works:ctf-primer.adoc#ds[data stream] files which your
  33 application will write through the generated tracer.
  34
  35 See xref:how-barectf-works:index.adoc[] to learn more.
  36
  37 |`barectf.h`
  38 |The generated tracer's public C{nbsp}header file.
  39
  40 This header contains the prototypes of the packet opening, packet
  41 closing, and xref:tracing-funcs:index.adoc[tracing functions].
  42
  43 barectf generates one packet opening/closing function per configured
  44 xref:yaml:dst-obj.adoc[data stream type] and one tracing function per
  45 configured xref:yaml:ert-obj.adoc[event record type].
  46
  47 Your application and xref:platform:index.adoc[platforms] need to
  48 include this file.
  49
  50 |`barectf-bitfield.h`
  51 |Internal macros for the generated tracer (included by `barectf.c`).
  52
  53 |[[barectf.c-file]]`barectf.c`
  54 |The generated tracer's C{nbsp}source code.
  55 |===
  56
  57 Those file names assume that `my-config.yaml` uses the default
  58 xref:yaml:cfg-obj.adoc#prefix-prop[prefixes].
  59
  60 === Use dedicated output directories
  61
  62 Because the <<metadata-file,`metadata` file>> which barectf generates is
  63 part of an eventual
  64 xref:how-barectf-works:ctf-primer.adoc#trace[CTF trace], you'll probably
  65 want to make barectf write it to its own directory.
  66
  67 Use the `barectf generate` command's
  68 xref:usage.adoc#generate-metadata-dir-option[`+--metadata-dir+` option]
  69 to specify the `metadata` file's output directory:
  70
  71 [.cl]
  72 [verse]
  73 [.prompt]##$## barectf generate my-config.yaml --metadata-dir=my-trace
  74
  75 `barectf generate` also offers the
  76 xref:usage.adoc#generate-code-dir-option[`+--code-dir+`] and
  77 xref:usage.adoc#generate-headers-dir-option[`+--headers-dir+`] options
  78 to select the output directories of the generated
  79 <<barectf.c-file,tracer source file>> and headers.
  80
  81 === Control inclusions
  82
  83 A barectf xref:yaml:index.adoc[YAML configuration file] can
  84 xref:yaml:include.adoc[include partial YAML files].
  85
  86 Set the most significant inclusion search directories with the `barectf
  87 generate` command's
  88 xref:usage.adoc#generate-include-dir-option[`+--include-dir+`] option.
  89 You can use the option more than once:
  90
  91 [.cl]
  92 [verse]
  93 [.prompt]##$## barectf generate my-config.yaml \
  94                    --include-dir=/path/to/project/barectf \
  95                    --include-dir=/path/to/base/barectf
  96
  97 By default, if `barectf generate` can't find an inclusion file, it
  98 prints an error and xref:usage.adoc#exit-status[exits] with a non-zero
  99 status.
 100
 101 However, it's possible that some YAML file **_A_** includes a file
 102 **_B_** which barectf can't find, but **_A_** doesn't need anything from
 103 **_B_**.
 104
 105 Force `barectf generate` to continue silently instead with its
 106 xref:usage.adoc#generate-ignore-include-not-found-option[`+--ignore-include-not-found+`]
 107 option:
 108
 109 [.cl]
 110 [verse]
 111 [.prompt]##$## barectf generate my-config.yaml --ignore-include-not-found \
 112                    --include-dir=/path/to/project/barectf \
 113                    --include-dir=/path/to/base/barectf \