[.lead]
https://barectf.org/[**_barectf_**] (from _bare_ metal and _CTF_)
is a generator of
-https://en.wikipedia.org/wiki/Tracing_(software)[tracer] which produces
+https://en.wikipedia.org/wiki/Tracing_(software)[tracers] that produce
https://diamon.org/ctf/[CTF] data streams.
[NOTE]
[.width-50]
image::ctf-trace.svg[]
-The metadata stream describes the trace's data streams with the TSDL
-language. On the file system, its file name must be `metadata`.
+The metadata stream describes the trace's data streams with TSDL
+(Trace Stream Description Language). On the file system, its file name
+must be `metadata`.
The metadata stream describes things such as:
xref:yaml:trace-type-obj.adoc#magic-ft-prop[`magic-field-type`
property].
-** [.opt]##Optional##A trace type UUID.
+** [.opt]##Optional##A trace type
+https://en.wikipedia.org/wiki/Universally_unique_identifier[UUID].
+
See the trace type object's
xref:yaml:trace-type-obj.adoc#uuid-prop[`uuid` property] and the
xref:yaml:dst-obj.adoc[data stream types], xref:yaml:ert-obj.adoc[event
record types], and other options to generate the files.
-With the `barectf` Python package, you build the barectf configuration
-programatically by assembling configuration objects. This documentation
-is _not_ about the Python package.
+With the `barectf` https://pypi.org/project/barectf/[Python package],
+you build the barectf configuration programatically by assembling
+configuration objects. This documentation is _not_ about the Python
+package.
The xref:cli:index.adoc[`barectf` CLI tool] can read a
xref:yaml:index.adoc[YAML configuration file] and generate files out of
. barectf also generates the tracer's C{nbsp}files.
-. You pass your application's C{nbsp}source file(s),
+. After adding calls to the generated tracing functions in your
+application code, you pass your application's C{nbsp}source file(s),
xref:platform:index.adoc[platform]
C{nbsp}source files, and the generated tracer's C{nbsp}source file to
a xref:build:index.adoc[C{nbsp}compiler to create your final
== TSDL identifier
Many barectf YAML objects require that a given string key or value
-be a valid TSDL identifier.
+be a valid TSDL (Trace Stream Description Language) identifier.
As per https://diamon.org/ctf/v1.8.3/[CTF{nbsp}1.8.3], a valid TSDL
identifier is any valid C{nbsp}identifier which is __not__ one of:
`true`, `True`, `TRUE`, `false`, `False`, or `FALSE`.
Integer::
- Anything matching:
+ Anything matching these regular expressions:
+
** `+[-+]?[0-9]++` (decimal)
** `+0o[0-7]++` (octal)