.clang-tidy: add some checks
[babeltrace.git] / README.adoc
1 // Render with Asciidoctor
2
3 = Babeltrace 2
4 4 March 2024
5 :btversion: 2.0
6 :bt2: Babeltrace{nbsp}2
7 ifdef::env-github[]
8 :toc: macro
9 endif::[]
10 ifndef::env-github[]
11 :toc: left
12 endif::[]
13
14 Babeltrace /ˈbæbəltreɪs/, an
15 https://efficios.com/[EfficiOS] project, is an open-source
16 https://en.wikipedia.org/wiki/Tracing_(software)[trace]
17 manipulation framework.
18
19 https://ci.lttng.org/job/babeltrace_master_linuxbuild[image:https://img.shields.io/jenkins/s/https/ci.lttng.org/babeltrace_master_linuxbuild.svg[]]
20 https://scan.coverity.com/projects/babeltrace[image:https://img.shields.io/coverity/scan/babeltrace.svg[]]
21
22 The **_{bt2}_** project offers a library with a
23 https://babeltrace.org/docs/v{btversion}/libbabeltrace2[C{nbsp}API],
24 https://babeltrace.org/docs/v{btversion}/python/bt2[Python{nbsp}3 bindings],
25 and a
26 https://babeltrace.org/docs/v{btversion}/man1/babeltrace2.1/[command-line tool]
27 (CLI) which makes it very easy for mere mortals to view, convert,
28 transform, and analyze traces.
29
30 image::doc/api/libbabeltrace2/images/basic-convert-graph.png[A basic {bt2} conversion graph]
31
32 {bt2} is also the reference parser implementation of the
33 https://diamon.org/ctf/[Common Trace Format] (CTF), a flexible
34 trace format which various tracers and tools such as
35 https://lttng.org/[LTTng] and
36 https://barectf.org/[barectf] produce natively.
37 The {bt2} library and its Python bindings can read and write CTF traces.
38
39 See the {bt2} https://babeltrace.org[official website], in
40 particular the
41 https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-intro.7[`**babeltrace2-intro**(7)`]
42 manual page, to learn more about the project.
43
44 [NOTE]
45 ifdef::env-github[]
46 .**Babeltrace{nbsp}1 vs. {bt2}**
47 endif::[]
48 ifndef::env-github[]
49 .Babeltrace{nbsp}1 vs. {bt2}
50 endif::[]
51 ====
52 The Babeltrace project exists since 2010.
53
54 In 2020, {bt2} was released. {bt2} is a complete rewrite of the library,
55 Python bindings, and CLI. It's plugin-based and offers much more
56 features and potential than Babeltrace{nbsp}1 while delivering
57 comparable performance.
58
59 Some Linux distributions still provide packages for the
60 Babeltrace{nbsp}1 project. Both projects can coexist on the same system
61 as there are no conflicting files.
62
63 This README documents the **{bt2}** project.
64 ====
65
66 ifdef::env-github[]
67 toc::[]
68 endif::[]
69
70 == Build Babeltrace{nbsp}{btversion} from source
71
72 === Build-time requirements
73
74 To build Babeltrace{nbsp}{btversion}, you need:
75
76 Compiler::
77 * Any https://gcc.gnu.org/[GCC]-like compiler with C99 and
78 https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html[GNU extension]
79 support.
80 +
81 https://clang.llvm.org/[Clang] is one of those.
82
83 * Any {cpp} compiler with {cpp}11 support (for example,
84 GCC{nbsp}≥{nbsp}4.8 and Clang{nbsp}≥{nbsp}3.3).
85
86 Tools::
87 * https://www.gnu.org/software/make/[GNU Make]
88 * **If you build from a Git clone**:
89 ** https://www.gnu.org/software/automake/[GNU Automake]{nbsp}≥{nbsp}1.13
90 ** https://www.gnu.org/software/autoconf/[GNU Autoconf]{nbsp}≥{nbsp}2.69
91 ** https://www.gnu.org/software/libtool/[GNU Libtool]{nbsp}≥{nbsp}2.2
92 ** https://github.com/westes/flex[flex]{nbsp}≥{nbsp}2.5.35
93 ** https://www.gnu.org/software/bison/bison.html[GNU Bison]{nbsp}≥{nbsp}2.5
94
95 Libraries::
96 * A C library (for example,
97 https://www.gnu.org/software/libc/[GNU{nbsp}C Library],
98 https://www.musl-libc.org/[musl libc])
99 * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28
100 (Debian/Ubuntu: `libglib2.0-dev`; Fedora: `glib2-devel`)
101
102 _**If you need the `bt2` Python bindings**_::
103 * https://www.python.org[Python]{nbsp}≥{nbsp}3.4 (development
104 libraries and `python3-config`)
105 (Debian/Ubuntu: `python3-dev`; Fedora: `python3-devel`)
106 * http://www.swig.org[SWIG]{nbsp}≥{nbsp}3.0
107
108 _**If you need the https://lttng.org/[LTTng] debug information filter component class (https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`])**_::
109 * https://sourceware.org/elfutils/[elfutils]{nbsp}≥{nbsp}0.154
110 (Debian/Ubuntu: `libelf-dev` and `libdw-dev`;
111 Fedora: `elfutils-devel` and `elfutils-libelf-devel`)
112
113 _**If you need the {bt2}{nbsp}C{nbsp}API HTML documentation**_::
114 * http://www.doxygen.nl/[Doxygen]{nbsp}≥{nbsp}1.8.6
115
116 _**If you need the {bt2} manual pages**_::
117 * https://www.methods.co.nz/asciidoc/[Asciidoc]{nbsp}≥{nbsp}8.6.8
118 * https://pagure.io/xmlto[xmlto]{nbsp}≥{nbsp}0.0.25
119
120 _**If you need the `bt2` Python bindings documentation**_::
121 * https://www.sphinx-doc.org/[Sphinx]{nbsp}≥{nbsp}1.3 for
122 Python{nbsp}3
123 (Debian/Ubuntu/Fedora: `python3-sphinx`)
124
125 [NOTE]
126 ifdef::env-github[]
127 .**Thanks for the code!**
128 endif::[]
129 ifndef::env-github[]
130 .Thanks for the code!
131 endif::[]
132 ====
133 We'd like to thank the authors of the following projects which are
134 embedded into the {bt2} source tree:
135
136 * https://github.com/fmtlib/fmt[\{fmt}]
137 * https://github.com/nlohmann/json[JSON for Modern {cpp}]
138 * https://github.com/martinmoene/optional-lite[optional lite]
139 * https://github.com/martinmoene/span-lite[span lite]
140 * https://github.com/martinmoene/string-view-lite[string_view lite]
141 * https://github.com/quicknir/wise_enum[wise_enum]
142 * https://github.com/wonder-mice/zf_log[zf_log]
143 ====
144
145 === Procedure
146
147 To build {bt2}:
148
149 . **If you build from a Git clone**, do:
150 +
151 [role="term"]
152 ----
153 $ ./bootstrap
154 ----
155 +
156 This generates the `configure` script and other important files.
157
158 . [[conf]]Configure the project:
159 +
160 [role="term"]
161 ----
162 $ ./configure
163 ----
164 +
165 --
166 The following options can modify the build:
167
168 `--enable-api-doc`::
169 Build the {bt2}{nbsp}C{nbsp}API HTML documentation.
170
171 `--enable-built-in-plugins`::
172 Statically link the official plugins into the
173 `babeltrace2` executable.
174
175 `--enable-built-in-python-plugin-support`::
176 Statically link the Python plugin provider into the
177 `babeltrace2` executable.
178
179 `--enable-debug-info`::
180 Build the https://lttng.org/[LTTng] debug information filter
181 component class
182 (https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`]).
183
184 `--enable-man-pages`::
185 Build the {bt2} manual pages.
186
187 `--enable-python-bindings`::
188 Build the `bt2` Python bindings.
189 +
190 You can set the path to custom `python3` and `python3-config` programs
191 with the `PYTHON` and `PYTHON_CONFIG` environment variable.
192
193 `--enable-python-bindings-doc`::
194 Build the `bt2` Python bindings documentation.
195
196 `--enable-python-plugins`::
197 Build support for {bt2} Python plugins.
198
199 The following environment variables can modify the build:
200
201 `BABELTRACE_DEBUG_MODE`::
202 Set to `1` to enable the debug mode.
203 +
204 The debug mode enables more run-time assertions to detect bugs while
205 developing the {bt2} project.
206
207 `BABELTRACE_DEV_MODE`::
208 Set to `1` to enable the <<dev-mode,developer mode>>.
209 +
210 The {bt2} developer mode enables more precondition and postcondition
211 assertions to detect C{nbsp}API usage errors.
212
213 `BABELTRACE_MINIMAL_LOG_LEVEL`::
214 Set the build-time, minimal logging level for all the modules
215 of the project.
216 +
217 Set to `TRACE`, `DEBUG`, or `INFO`.
218
219 `BABELTRACE_PLUGIN_PROVIDERS_DIR`::
220 Installation directory of {bt2} plugin providers.
221
222 `BABELTRACE_PLUGINS_DIR`::
223 Installation directory of {bt2} official plugins.
224
225 Run `./configure --help` to list all the available options and
226 environment variables.
227 --
228
229 . Build {bt2}:
230 +
231 [role="term"]
232 ----
233 $ make
234 ----
235
236 To install {bt2}:
237
238 * Run:
239 +
240 [role="term"]
241 ----
242 # make install
243 ----
244
245 [[dev-mode]]
246 === Build {bt2} for plugin or application development
247
248 If you're developing a {bt2} plugin or an application which uses
249 libbabeltrace2, we recommend to:
250
251 * Build {bt2} from source in _developer mode_.
252 +
253 The {bt2} developer mode enables more precondition and postcondition
254 assertions to detect C{nbsp}API usage errors.
255 +
256 The
257 https://babeltrace.org/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API documentation]
258 always lists the precondition and postconditions of
259 functions.
260 +
261 Set `BABELTRACE_DEV_MODE=1` when you <<conf,configure>> the {bt2} build.
262
263 * Use _TRACE_ as the minimal logging level at build time to have
264 access to more logging, should you need it to debug your plugin or
265 application.
266 +
267 Set `BABELTRACE_MINIMAL_LOG_LEVEL=TRACE` when you <<conf,configure>>
268 the {bt2} build.
269
270 {bt2} development build configuration command line example:
271
272 [role="term"]
273 ----
274 $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure
275 ----
276
277 {bt2} development build configuration with Python support example:
278
279 [role="term"]
280 ----
281 $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure \
282 --enable-python-bindings --enable-python-plugins
283 ----
284
285 See the
286 https://babeltrace.org/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API
287 documentation] for more information.
288
289 == Use Babeltrace{nbsp}{btversion}
290
291 See the https://babeltrace.org[{bt2} website] to learn how to use the
292 different parts of the project.
293
294 If you're new to {bt2}, make sure to read the
295 https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-intro.7[`**babeltrace2-intro**(7)`]
296 manual page to familiarize yourself with the project.
297
298 === Run-time requirements
299
300 Libraries:: {empty}
301 +
302 * A C library (for example,
303 https://www.gnu.org/software/libc/[GNU{nbsp}C Library] or
304 https://www.musl-libc.org/[musl libc])
305
306 * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28
307 (Debian/Ubuntu: `libglib2.0-0`; Fedora: `glib2`)
308
309 _**If you need the `bt2` Python bindings**_:: {empty}
310 +
311 * https://www.python.org[Python]{nbsp}≥{nbsp}3.4
312 (Debian/Ubuntu/Fedora: `python3`)
313
314 _**If you need the https://lttng.org/[LTTng] debug information filter component class (https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`])**_:: {empty}
315 +
316 * https://sourceware.org/elfutils/[elfutils]{nbsp}≥{nbsp}0.154
317 (Debian/Ubuntu: `libelf` and `libdw`; Fedora: `elfutils-libs` and
318 `elfutils-libelf`)
319
320 == Community
321
322 Babeltrace was born to parse CTF traces produced by LTTng{nbsp}2.0 and
323 to pretty-print their events.
324
325 Even though {bt2} is independent from the LTTng project today, their
326 communities remain very close, which is why they share some
327 communication channels and services:
328
329 Mailing list::
330 https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[lttng-dev]
331 (mailto:lttng-dev@lists.lttng.org[lttng-dev@lists.lttng.org])
332
333 IRC channel::
334 irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network
335
336 Bug tracker::
337 https://bugs.lttng.org/projects/babeltrace[{bt2} bug tracker]
338
339 GitHub project::
340 https://github.com/efficios/babeltrace/[efficios/babeltrace]
341
342 Continuous integration::
343 https://ci.lttng.org/view/Babeltrace/[{bt2} jobs]
344 on the LTTng CI
345
346 Code review::
347 https://review.lttng.org/q/project:babeltrace[{bt2} project]
348 on LTTng Review (Gerrit)
This page took 0.039563 seconds and 4 git commands to generate.