Debian Codegraph @

docs/modules/ROOT/pages/index.adoc

raw
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].