| 1 |
= Welcome! |
| 2 |
:ansi-c: ANSI{nbsp}C |
| 3 |
|
| 4 |
[.welcome-logo] |
| 5 |
image::barectf-logo.svg[] |
| 6 |
|
| 7 |
Welcome to the _**barectf**_{nbsp}{page-component-version} |
| 8 |
documentation! |
| 9 |
|
| 10 |
== What's barectf? |
| 11 |
|
| 12 |
barectf (from _bare_ metal and _CTF_) is a generator of |
| 13 |
https://en.wikipedia.org/wiki/Tracing_(software)[tracer] which produces |
| 14 |
xref:how-barectf-works:ctf-primer.adoc#ds[CTF data streams]. |
| 15 |
|
| 16 |
CTF is a binary trace format designed to be very fast to write without |
| 17 |
compromising great flexibility. |
| 18 |
|
| 19 |
barectf reads a xref:yaml:index.adoc[configuration] and produces: |
| 20 |
|
| 21 |
* A CTF xref:how-barectf-works:ctf-primer.adoc#trace[metadata stream] |
| 22 |
file. |
| 23 |
|
| 24 |
* {ansi-c} source code files which, once xref:build:index.adoc[compiled], |
| 25 |
constitute a tracer which writes CTF data streams. |
| 26 |
+ |
| 27 |
The generated C{nbsp}source code has no other dependencies than a few |
| 28 |
C{nbsp}standard library headers. |
| 29 |
|
| 30 |
Your C/{cpp} program can include the generated `barectf.h` header and |
| 31 |
call its xref:tracing-funcs:index.adoc[`+barectf_trace_*()+` functions] |
| 32 |
from source locations of your choice to write |
| 33 |
xref:how-barectf-works:ctf-primer.adoc#er[event records] to |
| 34 |
xref:how-barectf-works:ctf-primer.adoc#pkt[CTF packets]. You can then |
| 35 |
read and analyze the CTF traces with tools such as |
| 36 |
https://babeltrace.org/[Babeltrace{nbsp}2] and |
| 37 |
https://www.eclipse.org/tracecompass/[Trace{nbsp}Compass]. |
| 38 |
|
| 39 |
xref:getting-started.adoc[Get started] now with a simple barectf |
| 40 |
configuration. |
| 41 |
|
| 42 |
Read xref:how-barectf-works:index.adoc[] to understand the mechanics and |
| 43 |
terminology of barectf. |
| 44 |
|
| 45 |
== Do I need barectf? |
| 46 |
|
| 47 |
You may need barectf if you need to add CTF tracing capabilities to your |
| 48 |
bare metal or embedded application/system. |
| 49 |
|
| 50 |
Because barectf generates portable {ansi-c} code, you can compile it and |
| 51 |
use it for virtually any system. |
| 52 |
|
| 53 |
If you need to add CTF instrumentation to Linux applications or to the |
| 54 |
Linux kernel, have a look at https://lttng.org/[LTTng] which offers a |
| 55 |
comprehensive tracing solution for Linux. |
| 56 |
|
| 57 |
== Components of barectf |
| 58 |
|
| 59 |
The barectf project contains: |
| 60 |
|
| 61 |
* A Python{nbsp}3 package, named `barectf`, which offers an API to |
| 62 |
programatically create a barectf configuration and generate files out |
| 63 |
of it. |
| 64 |
+ |
| 65 |
The documentation of the `barectf` Python{nbsp}3 package isn't available |
| 66 |
yet. |
| 67 |
|
| 68 |
* A xref:cli:index.adoc[command-line interface] (CLI), named `barectf`, |
| 69 |
which can process a xref:yaml:index.adoc[barectf YAML configuration |
| 70 |
file] to generate files out of it. |
| 71 |
|
| 72 |
* Installed xref:yaml:include.adoc#std[standard partial YAML files] |
| 73 |
which you can include in your barectf YAML configuration. |
| 74 |
|
| 75 |
== What's in this documentation? |
| 76 |
|
| 77 |
This documentation shows: |
| 78 |
|
| 79 |
* xref:install.adoc[How to install barectf]. |
| 80 |
|
| 81 |
* xref:how-barectf-works:index.adoc[How barectf works]. |
| 82 |
|
| 83 |
* xref:yaml:index.adoc[How to write a barectf YAML configuration]. |
| 84 |
|
| 85 |
* xref:cli:index.adoc[How to generate files from a YAML configuration |
| 86 |
file] with the `barectf` CLI tool. |
| 87 |
|
| 88 |
* xref:build:index.adoc[How to use and build your application with |
| 89 |
a generated tracer]. |
| 90 |
|
| 91 |
* xref:platform:index.adoc[How to write a barectf platform]. |
| 92 |
|
| 93 |
== It's "`barectf`"! |
| 94 |
|
| 95 |
The name of the project is "`**barectf**`"; not "`BareCTF`", nor |
| 96 |
"`__bareCTF__`", nor "`__Barectf__`". |
| 97 |
|
| 98 |
== License |
| 99 |
|
| 100 |
The barectf project, including this documentation, is licensed under the |
| 101 |
https://github.com/efficios/barectf/blob/stable-{page-component-version}/LICENSE[MIT license]. |