Including external YAML files

It is possible to include other YAML files in the following objects:

• Metadata object
• Clock object
• Trace object
• Stream object
• Event object

When including an external YAML file into a given object, the object properties contained in the included file become the base properties of the given object. Then, the properties of the given object (in the file including the external file) "patch", or extend the base properties in the following way:

• Booleans, numbers, and strings:
  • Property exists in base object: base property is replaced by included property
  • Property does not exist in base object: included property is appended to base object
• Arrays:
  • Property exists in base object:
    • Base property is an array: new elements are appended to base array
    • Base property is not an array: base property is replaced by included property
  • Property does not exist in base object: included property is appended to base object
• Associative arrays:
  • Property exists in base object:
    • Base property is an associative array: apply those three rules to each property, in order, where the base object is this associative array
    • Base property is not an associative array: base property is replaced by included property
  • Property does not exist in base object: included property is appended to base object

You can consider an external YAML file inclusion as a smart inheritance from the object in that file. Note that the rules are slightly different from type inheritance here, where associative arrays are not processed recursively (first-level associative array properties are replaced rather than extended).

Including one or more external YAML files is done with the special $include property of one of the objects above. The value of this property can be:

• A string: name of the YAML file to include
• An array of strings: names of the YAML files to include, processed in order

When multiple files are given, the second object inherits from the first one, the third object inherits from the second one, and so on, until finally the object with this $include property inherits from the last one. This allows you to use inclusions as mixins.

Include paths

Included YAML files can include other YAML files themselves, as long as the include graph stays acyclic.

An included YAML file name is absolute if it starts with /.

Relative included YAML files are searched for relative to the current working directory by default, and relative to the provided include directory if not found. Other directories can be searched into before searching the default search directories by using the -I option of the barectf tool one or more times.

By default, the barectf tool stops and prints an error when an included file is not found. You can instruct the tool to ignore such errors with the --ignore-include-not-found option.

Provided includes

The barectf package ships with a few provided includable configuration files. This directory is part of the default search directories, so the file names can be included without specifying an absolute path. As of this version, the provided files are:

• stdint.yaml: standard integer type aliases
• stdfloat.yaml: standard floating point number type aliases
• stdmisc.yaml: miscellaneous type aliases, like a UUID array
• lttng-ust-log-levels.yaml: LTTng-UST/syslog log level names and values
• trace-basic.yaml: basic trace object properties, suitable for most situations

Example

TODO

An included property only extends a base property if they are both associative arrays; the included property replaces the base property otherwise. The some-type type alias in the example above demonstrates this.

Note that the deeper $include properties are processed first. For example, consider the following metadata object:

$include: metadata.yaml
type-aliases:
  uint16:
    class: int
    size: 16
clocks:
  my_clock:
    $include: clock.yaml
trace:
  $include: trace.yaml
  byte-order: le
streams:
  my_stream:
    $include: stream.yaml
    packet-context-type:
      class: struct
      fields:
        packet_size: uint16
        content_size: uint16
    events:
      my_event:
        $include: event.yaml
        payload-type:
          class: struct
          fields:
            my_field:
              class: int
              size: 8

In this example, the inclusions are processed in this order:

1. event.yaml
2. clock.yaml, stream.yaml, and trace.yaml (order is not important here, because none of the objects including those is the parent of another)
3. metadata.yaml