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