docs/modules/ROOT/pages/whats-new.adoc

   1 = What's new in barectf{nbsp}3?
   2
   3 barectf{nbsp}3 is a major update of the project.
   4
   5 The main, user-visible changes are:
   6
   7 * Support for user-defined
   8   xref:yaml:static-array-ft-obj.adoc[static] and
   9   xref:yaml:dyn-array-ft-obj.adoc[dynamic array field types].
  10
  11 * Reworked `barectf` Python API to match the recent CTF terminology and
  12   model (like https://babeltrace.org/[Babeltrace{nbsp}2] and the
  13   upcoming CTF{nbsp}2).
  14
  15 * Reworked xref:yaml:index.adoc[YAML configuration] format to match the
  16   new Python API.
  17 +
  18 barectf{nbsp}3 can still read and use barectf{nbsp}2 YAML
  19 configurations.
  20 +
  21 The main changes are:
  22 +
  23 ** Updated terminology for property names and values.
  24 ** The xref:yaml:cfg-obj.adoc[configuration object] mapping (the YAML
  25    document) must be tagged with `tag:barectf.org,2020/3/config`.
  26 ** The configuration object contains a xref:yaml:trace-obj.adoc[trace
  27    object] which contains a xref:yaml:trace-type-obj.adoc[trace type
  28    object].
  29 +
  30 A trace can have an environment while a trace type can have a UUID.
  31
  32 ** You can specify two
  33    xref:yaml:cfg-obj.adoc#prefix-obj[prefixes] instead of a
  34    single one: a file name prefix and an identifier prefix.
  35 +
  36 With barectf{nbsp}2, the single prefix `my_app_` becomes the file name
  37 prefix `my_app` and the identifier prefix `my_app_`.
  38
  39 ** You don't need to specify special CTF structure field type members,
  40    like `magic`, `stream_id`, and `timestamp`.
  41 +
  42 Instead, you specify
  43 xref:yaml:trace-type-obj.adoc#features-obj[trace type] and
  44 xref:yaml:dst-obj.adoc#features-obj[data stream type
  45 features]. You can still control the exact field type of a feature.
  46
  47 ** A data stream type can have zero or one
  48    xref:yaml:dst-obj.adoc#def-clk-type-name-prop[default clock type].
  49 +
  50 When a data stream type has a default clock type, its timestamp integer
  51 field types (packet beginning, packet end, and event record)
  52 automatically refer to this specific clock type, effectively removing
  53 the integer field type's `property-mappings` property.
  54
  55 ** The only way to make a data stream type the default one is with its
  56    xref:yaml:dst-obj.adoc#is-def-prop[`$is-default`
  57    boolean property].
  58
  59 ** You cannot specify custom
  60    xref:how-barectf-works:ctf-primer.adoc#pkt[packet] header and
  61    xref:how-barectf-works:ctf-primer.adoc#er[event record]
  62    header field type members anymore.
  63 +
  64 The header field types only exist for the trace format itself.
  65 +
  66 Instead,
  67 xref:yaml:dst-obj.adoc#pkt-ctx-ft-extra-members-prop[append user-defined
  68 members to the packet context field type]
  69 and use the
  70 xref:yaml:dst-obj.adoc#er-common-ctx-ft-prop[event record common context
  71 field type].
  72
  73 ** xref:yaml:trace-type-obj.adoc#ft-aliases-prop[Field type aliases]
  74    do not need to be defined in any specific order.
  75 ** An xref:yaml:int-ft-obj.adoc[integer field type] _is_ a bit array
  76    field type.
  77 +
  78 A bit array field type has size and alignment properties. It doesn't
  79 have a byte order property: as of barectf{nbsp}3.0, the generated tracer
  80 always uses the native byte order.
  81
  82 ** An integer field type doesn't have a `signed` property: unsigned
  83    and signed integer field types are two different classes.
  84 ** An xref:yaml:enum-ft-obj.adoc[enumeration field type] _is_ an integer
  85    field type.
  86 ** The xref:yaml:enum-ft-obj.adoc#mappings-prop[mappings] of an
  87    enumeration field type are a YAML mapping of labels to sequences of
  88    integer ranges.
  89 ** A xref:yaml:real-ft-obj.adoc[real field type] _is_ a bit array field
  90    type.
  91 ** The xref:yaml:struct-ft-obj.adoc#members-prop[members] of a structure
  92    field type are a sequence instead of a mapping (YAML mappings are
  93    _not_ ordered).
  94 +
  95 This sequence is considered to be an _ordered mapping_, similar to
  96 YAML's https://yaml.org/type/omap.html[`+!!omap+`] type.
  97
  98 * Updated xref:yaml:include.adoc#std[standard partial YAML files] for
  99   the new YAML configuration format.
 100
 101 * The xref:cli:usage.adoc[`barectf` CLI tool] now has a Git-like user
 102   interface with a few commands.
 103 +
 104 The `barectf` CLI tool remains backward compatible with barectf{nbsp}2's
 105 CLI: the default command is
 106 xref:cli:usage.adoc#generate-command[`generate`].
 107
 108 * The generated C{nbsp}code is ``const``-correct.