= Include partial YAML files You can include a partial YAML file from specific objects within the xref:cfg-obj.adoc[configuration object]: * xref:trace-obj.adoc[Trace object] * xref:trace-type-obj.adoc[Trace type object] * xref:clk-type-obj.adoc[Clock type object] * xref:dst-obj.adoc[Data stream type object] * xref:ert-obj.adoc[Event record type object] Each of the objects above can have an `$include` property which is a sequence of names of files to include. By choosing where to include partial YAML files strategically, you can split a configuration object into multiple reusable parts for different systems or projects. == Inclusion file search barectf tries to find each file of an `$include` property sequence in specific directories. When using the `barectf` CLI tool's xref:cli:usage.adoc#generate-command[`generate`] or xref:cli:usage.adoc#show-effective-configuration-command[`show-effective-configuration`] commands, the inclusion directory search order is: . The value of each xref:cli:usage.adoc#generate-include-dir-option[`+--include-dir+`] option, in order. . The current working directory. . The directory containing the <> (like `stdint.yaml` and `stdmisc.yaml`). By default, if `barectf` can't find an inclusion file, the command prints an error and xref:cli:usage.adoc#exit-status[exits] with a non-zero status. Force `barectf` to continue silently instead with its xref:cli:usage.adoc#generate-ignore-include-not-found-option[`+--ignore-include-not-found+`] option. == Inclusion rules With the `$include` property, an object _includes_ the properties of one or more YAML documents. barectf processes the items of the `$include` property sequence in order. When an object __**A**__ includes a YAML document __**B**__, the _effective_ object is __**A**__ "`patching`" __**B**__. include::partial$patching-rules-table.adoc[] === Examples .Override scalar property (xref:ert-obj.adoc[event record type object]). ==== .`base.yaml` [source,yaml] ---- log-level: WARN payload-field-type: class: structure members: - msg: string - msg_id: uint16 ---- .Overlay event record type object [source,yaml] ---- $include: [base.yaml] log-level: ERROR ---- .Effective event record type object [source,yaml] ---- log-level: ERROR payload-field-type: class: structure members: - msg: string - msg_id: uint16 ---- ==== .Add and override scalar properties (xref:clk-type-obj.adoc[clock type object]). ==== .`base.yaml` [source,yaml] ---- frequency: 1000000 offset: seconds: 1992839 ---- .Overlay clock type object [source,yaml] ---- $include: [base.yaml] frequency: 8000000 origin-is-unix-epoch: false ---- .Effective clock type object [source,yaml] ---- frequency: 8000000 offset: seconds: 1992839 origin-is-unix-epoch: false ---- ==== .Append to sequence property (xref:trace-type-obj.adoc[trace type object]). ==== .`base.yaml` [source,yaml] ---- $field-type-aliases: my-enum: class: signed-enumeration mappings: COMPOSE: - 56 - [100, 299] DIRTY: [0] ---- .Overlay trace type object [source,yaml] ---- $include: [base.yaml] $field-type-aliases: my-enum: size: 16 mappings: COMPOSE: - -22 # ... ---- .Effective trace type object [source,yaml] ---- $field-type-aliases: my-enum: class: signed-enumeration size: 16 mappings: COMPOSE: - 56 - [100, 299] - -22 DIRTY: [0] # ... ---- ==== .Add to nested mapping property (event record type object). ==== .`base.yaml` [source,yaml] ---- specific-context-field-type: class: structure members: - msg: string - user_id: uint16 ---- .Overlay event record type object [source,yaml] ---- $include: [base.yaml] specific-context-field-type: class: structure members: - src_ip_addr: field-type: class: static-array length: 4 element-field-type: uint8 - user_id: int8 ---- .Effective event record type object [source,yaml] ---- specific-context-field-type: class: structure members: - msg: string - user_id: int8 - src_ip_addr: field-type: class: static-array length: 4 element-field-type: uint8 ---- ==== [[std]] == Standard partial YAML files The barectf project ships with a few "`standard`" partial YAML files to be included from a xref:trace-type-obj.adoc[trace type object]: https://github.com/efficios/barectf/blob/stable-{page-component-version}/barectf/include/3/stdint.yaml[`stdint.yaml`]:: Standard xref:int-ft-obj.adoc[integer] xref:trace-type-obj.adoc#ft-aliases-prop[field type aliases], like `uint8`, `byte-packed-sint16`, and `bit-packed-uint64`. https://github.com/efficios/barectf/blob/stable-{page-component-version}/barectf/include/3/stdreal.yaml[`stdreal.yaml`]:: Standard xref:real-ft-obj.adoc[real] field type aliases, like `float` and `double`. https://github.com/efficios/barectf/blob/stable-{page-component-version}/barectf/include/3/stdmisc.yaml[`stdmisc.yaml`]:: The `string` and `str` xref:str-ft-obj.adoc[string] field type aliases. https://github.com/efficios/barectf/blob/stable-{page-component-version}/barectf/include/3/lttng-ust-log-levels.yaml[`lttng-ust-log-levels.yaml`]:: xref:trace-type-obj.adoc#ll-aliases-prop[Log level aliases] which correspond to the https://lttng.org/[LTTng-UST] log levels.