= Getting started This introductory guide makes you create a very simple barectf YAML configuration, generate a tracer out of it, and then use it. You need Linux for this user guide. The steps are: . <>. . <>. . <>. . <>. . <> to produce xref:how-barectf-works:ctf-primer.adoc#ds[CTF data streams]. . <>. IMPORTANT: Make sure that barectf xref:install.adoc[is installed] before you follow this guide. [[yaml]] == Write the YAML configuration file . Create an empty directory and `cd` into it, for example: + [.cl] [verse] [.prompt]##$## cd $(mktemp --directory) . Write the following xref:yaml:index.adoc[YAML configuration file]: + [[config.yaml]] .`config.yaml` [source,yaml] ---- # Needed YAML tag for the configuration object --- ! # Configuration's trace trace: # Type of the trace type: # Add standard field type aliases $include: - stdint.yaml - stdmisc.yaml # Native byte order is little-endian native-byte-order: little-endian # One clock type clock-types: # The Linux FS platform requires a clock type named `default` # which has a 1-GHz frequency and the `uint64_t` C type. default: frequency: 1000000000 $c-type: uint64_t # One data stream type data-stream-types: # Stream type named `default` default: # Default data stream type $is-default: true # Default clock type: `default` $default-clock-type-name: default # Two event record types event-record-types: # Event record type named `one_integer` one_integer: payload-field-type: class: structure members: # One payload member: a 32-bit signed integer field type # (`int32_t` C type) - the_integer: int32 # Event record type named `one_string` one_string: payload-field-type: class: structure members: # One payload member: a string field type # (`const char *` C type) - the_string: string ---- + barectf will <> two xref:tracing-funcs:index.adoc[tracing functions] named `+barectf_trace_one_integer()+` and `+barectf_trace_one_string()+` from this configuration. [[cli]] == Generate the files with the `barectf` CLI tool . Create a directory which will contain the CTF trace: + -- [.cl] [verse] [.prompt]##$## mkdir trace -- + A CTF trace always contains a file named `metadata` and one or more data stream files. barectf always generates the `metadata` file while the user application writes the data stream files through the generated tracer. . Generate the CTF metadata stream and C{nbsp}source files with the xref:cli:index.adoc[`barectf` CLI tool]: + [.cl] [verse] -- [.prompt]##$## barectf generate --metadata-dir=trace config.yaml -- + `barectf generate` creates: + [%autowidth.stretch, cols="d,a"] |=== |File name |Description |`trace/metadata` |The CTF metadata stream file. It's in the `trace` directory because we used the xref:cli:usage.adoc#generate-metadata-dir-option[`+--metadata-dir+`] option. |`barectf.h` |The generated tracer's public C{nbsp}header file. |`barectf-bitfield.h` |Internal macros for the generated tracer (included by `barectf.c`). |`barectf.c` |The generated tracer's C{nbsp}source code. |=== [[app]] == Write the application source file Write a simple application which uses the generated tracer: .`app.c` [source,c] ---- /* Include the Linux FS platform header */ #include "barectf-platform-linux-fs.h" /* Include the barectf public header */ #include "barectf.h" int main(const int argc, const char * const argv[]) { /* Platform context */ struct barectf_platform_linux_fs_ctx *platform_ctx; /* barectf context */ struct barectf_default_ctx *ctx; int i; /* * Obtain a platform context. * * The platform is configured to write 512-byte packets to a data * stream file within the `trace` directory. */ platform_ctx = barectf_platform_linux_fs_init(512, "trace/stream", 0, 0, 0); /* Obtain the barectf context from the platform context */ ctx = barectf_platform_linux_fs_get_barectf_ctx(platform_ctx); /* * Write a `one_integer` event record which contains the number of * command arguments. */ barectf_trace_one_integer(ctx, argc); /* For each command argument */ for (i = 0; i < argc; ++i) { /* * Write a `one_integer` event record which contains the * argument's index. */ barectf_trace_one_integer(ctx, i); /* * Write a `one_string` event record which contains the * argument. */ barectf_trace_one_string(ctx, argv[i]); } /* Finalize (free) the platform context */ barectf_platform_linux_fs_fini(platform_ctx); return 0; } ---- This application calls the `+barectf_trace_one_integer()+` and `+barectf_trace_one_string()+` functions which correspond to the `one_integer` and `one_string` event record types in <>. [[build]] == Download platform source files and build the application To build the final application, you need the Linux FS platform source files. The Linux FS platform only exists to demonstrate barectf; a barectf user almost always xref:platform:index.adoc[writes its own platform] because of the bare-metal/embedded nature of the target systems. . Download the Linux FS platform source files: + [.cl] [verse] [.prompt]##$## wget https://raw.githubusercontent.com/efficios/barectf/stable-{page-component-version}/platforms/linux-fs/barectf-platform-linux-fs.h [.prompt]##$## wget https://raw.githubusercontent.com/efficios/barectf/stable-{page-component-version}/platforms/linux-fs/barectf-platform-linux-fs.c . Build the application: + [.cl] [verse] [.prompt]##$## gcc -o app app.c barectf.c barectf-platform-linux-fs.c [[trace]] == Execute the application Run the <> application, passing a few command-line arguments: [.cl] [verse] [.prompt]##$## ./app lorem ipsum nulla dolore consequat This writes the xref:how-barectf-works:ctf-primer.adoc#ds[CTF data stream] file `trace/stream`. The `trace` directory is now a complete xref:how-barectf-works:ctf-primer.adoc#trace[CTF trace]. [[read]] == Read the CTF trace Use https://babeltrace.org/[Babeltrace{nbsp}2] to read the resulting CTF trace: [.cl] [verse] [.prompt]##$## babeltrace2 trace ---- [15:52:24.202028327] (+?.?????????) one_integer: { the_integer = 6 } [15:52:24.202029477] (+0.000001150) one_integer: { the_integer = 0 } [15:52:24.202029988] (+0.000000511) one_string: { the_string = "./app" } [15:52:24.202033362] (+0.000003374) one_integer: { the_integer = 1 } [15:52:24.202033716] (+0.000000354) one_string: { the_string = "lorem" } [15:52:24.202034147] (+0.000000431) one_integer: { the_integer = 2 } [15:52:24.202034465] (+0.000000318) one_string: { the_string = "ipsum" } [15:52:24.202034812] (+0.000000347) one_integer: { the_integer = 3 } [15:52:24.202035147] (+0.000000335) one_string: { the_string = "nulla" } [15:52:24.202035527] (+0.000000380) one_integer: { the_integer = 4 } [15:52:24.202035848] (+0.000000321) one_string: { the_string = "dolore" } [15:52:24.202036175] (+0.000000327) one_integer: { the_integer = 5 } [15:52:24.202036553] (+0.000000378) one_string: { the_string = "consequat" } ---- You can also open the trace with https://www.eclipse.org/tracecompass/[Trace{nbsp}Compass]: .Trace Compass 5.3.0's event list view image::getting-started-trace-compass.png[]