| 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 \ |