1 // Render with Asciidoctor
6 :bt2: Babeltrace{nbsp}2
9 Babeltrace /ˈbæbəltreɪs/, an
10 https://efficios.com/[EfficiOS] project, is an open-source
11 https://en.wikipedia.org/wiki/Tracing_(software)[trace]
12 manipulation framework.
14 https://ci.lttng.org/job/babeltrace_master_build[image:https://img.shields.io/jenkins/s/https/ci.lttng.org/babeltrace_master_build.svg[]]
15 https://scan.coverity.com/projects/babeltrace[image:https://img.shields.io/coverity/scan/babeltrace.svg[]]
17 The **_{bt2}_** project offers a library with a
18 https://babeltrace.org/docs/v{btversion}/libbabeltrace2[C{nbsp}API],
19 https://babeltrace.org/docs/v{btversion}/python/bt2[Python{nbsp}3 bindings],
21 https://babeltrace.org/docs/v{btversion}/man1/babeltrace2.1/[command-line tool]
22 (CLI) which makes it very easy for mere mortals to view, convert,
23 transform, and analyze traces.
25 {bt2} is also the reference parser implementation of the
26 https://diamon.org/ctf/[Common Trace Format] (CTF), a versatile
27 trace format produced by various tracers and tools such as
28 https://lttng.org/[LTTng] and
29 https://barectf.org/[barectf]. The {bt2} library and its Python bindings
30 can read and write CTF traces.
32 See Babeltrace's https://babeltrace.org[official website], in
34 https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-intro.7[`**babeltrace2-intro**(7)`]
35 manual page, to learn more about the project.
38 .Babeltrace{nbsp}1 vs. {bt2}
40 The Babeltrace project exists since 2010. In 2020, {bt2} was
41 released. {bt2} is a complete rewrite of the library, Python
42 bindings, and CLI. It is plugin-based and offers much more features and
43 potential than Babeltrace{nbsp}1 while showing comparable performance.
45 Because {bt2} is still a young major release, some
46 distributions still provide packages for the Babeltrace{nbsp}1 project.
47 Both projects can coexist on the same system as there are no common
50 This file documents the **{bt2}** project.
54 == Build Babeltrace{nbsp}{btversion} from source
56 === Build-time requirements
58 To build Babeltrace{nbsp}{btversion}, you need:
61 * Any https://gcc.gnu.org/[GCC]-like compiler with C99 and
62 https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html[GNU extension]
65 https://clang.llvm.org/[Clang] is one of those.
68 * https://www.gnu.org/software/make/[GNU Make]
69 * **If you build from a Git clone**:
70 ** https://www.gnu.org/software/automake/[GNU Automake]{nbsp}≥{nbsp}1.10
71 ** https://www.gnu.org/software/autoconf/[GNU Autoconf]{nbsp}≥{nbsp}2.64
72 ** https://www.gnu.org/software/libtool/[GNU Libtool]{nbsp}≥{nbsp}2.2
73 ** https://github.com/westes/flex[flex]{nbsp}≥{nbsp}2.5.35
74 ** https://www.gnu.org/software/bison/bison.html[GNU Bison]{nbsp}≥{nbsp}2.5
77 * A C library (for example,
78 https://www.gnu.org/software/libc/[GNU{nbsp}C Library],
79 https://www.musl-libc.org/[musl libc])
80 * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28
81 (Debian/Ubuntu: `libglib2.0-dev`; Fedora: `glib2-devel`)
83 _**If you need the `bt2` Python bindings**_::
84 * https://www.python.org[Python]{nbsp}≥{nbsp}3.4 (development
85 libraries and `python3-config`)
86 (Debian/Ubuntu: `python3-dev`; Fedora: `python3-devel`)
87 * http://www.swig.org[SWIG]{nbsp}≥{nbsp}3.0
89 _**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`])**_::
90 * https://sourceware.org/elfutils/[elfutils]{nbsp}≥{nbsp}0.154
91 (Debian/Ubuntu: `libelf-dev` and `libdw-dev`;
92 Fedora: `elfutils-devel` and `elfutils-libelf-devel`)
94 _**If you need the {bt2}{nbsp}C{nbsp}API HTML documentation**_::
95 * http://www.doxygen.nl/[Doxygen]{nbsp}≥{nbsp}1.8.6
97 _**If you need the {bt2} manual pages**_::
98 * https://www.methods.co.nz/asciidoc/[Asciidoc]{nbsp}≥{nbsp}8.6.8
99 * https://pagure.io/xmlto[xmlto]{nbsp}≥{nbsp}0.0.25
101 _**If you need the `bt2` Python bindings documentation**_::
102 * https://www.sphinx-doc.org/[Sphinx]{nbsp}≥{nbsp}1.3 for
104 (Debian/Ubuntu/Fedora: `python3-sphinx`)
111 . **If you build from a Git clone**, do:
118 This generates the `configure` script and other important files.
120 . [[conf]]Configure the project:
128 The following options can modify the build:
131 Build the {bt2}{nbsp}C{nbsp}API HTML documentation.
133 `--enable-debug-info`::
134 Build the https://lttng.org/[LTTng] debug information filter
136 (https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`]).
138 `--enable-man-pages`::
139 Build the {bt2} manual pages.
141 `--enable-python-bindings`::
142 Build the `bt2` Python bindings.
144 You can set the path to custom `python3` and `python3-config` programs
145 with the `PYTHON` and `PYTHON_CONFIG` environment variable.
147 `--enable-python-bindings-doc`::
148 Build the `bt2` Python bindings documentation.
150 `--enable-python-plugins`::
151 Build support for {bt2} Python plugins.
153 The following environment variables can modify the build:
155 `BABELTRACE_DEBUG_MODE`::
156 Set to `1` to enable the debug mode.
158 The debug mode enables more run-time assertions to detect bugs in the
161 `BABELTRACE_DEV_MODE`::
162 Set to `1` to enable the <<dev-mode,developer mode>>.
164 The {bt2} developer mode enables more precondition and postcondition
165 assertions to detect programming errors.
167 `BABELTRACE_MINIMAL_LOG_LEVEL`::
168 Set the build-time, minimal logging level for all the project's
171 Set to `TRACE`, `DEBUG`, or `INFO`.
173 `BABELTRACE_PLUGIN_PROVIDERS_DIR`::
174 Installation directory of {bt2} plugin providers.
176 `BABELTRACE_PLUGINS_DIR`::
177 Installation directory of {bt2} project plugins.
179 See `./configure --help` to list all the available options and
180 environment variables.
201 === Build {bt2} for plugin or application development
203 If you are developing a {bt2} plugin or an application which uses
204 libbabeltrace2, we recommend that:
206 * You build {bt2} from source in _developer mode_.
208 The {bt2} developer mode enables more precondition and postcondition
209 assertions to detect programming errors.
211 Set `BABELTRACE_DEV_MODE=1` when you <<conf,configure>> the {bt2} build.
213 * You use _TRACE_ as the minimal logging level at build time to have
214 access to more logging, should you need it to debug your plugin or
217 Set `BABELTRACE_MINIMAL_LOG_LEVEL=TRACE` when you <<conf,configure>>
220 {bt2} development build configuration command line example:
224 $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure
227 {bt2} development build configuration with Python support example:
231 $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure \
232 --enable-python-bindings --enable-python-plugins
236 https://babeltrace.org/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API]
237 documentation for more information.
240 == Use Babeltrace{nbsp}{btversion}
242 See the https://babeltrace.org[Babeltrace website] to learn how
243 to use the different parts of the project.
246 === Run-time requirements
249 * A C library (for example,
250 https://www.gnu.org/software/libc/[GNU{nbsp}C Library],
251 https://www.musl-libc.org/[musl libc])
252 * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28
253 (Debian/Ubuntu: `libglib2.0-0`; Fedora: `glib2`)
255 _**If you need the `bt2` Python bindings**_::
256 * https://www.python.org[Python]{nbsp}≥{nbsp}3.4
257 (Debian/Ubuntu/Fedora: `python3`)
259 _**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`])**_::
260 * https://sourceware.org/elfutils/[elfutils]{nbsp}≥{nbsp}0.154
261 (Debian/Ubuntu: `libelf` and `libdw`; Fedora: `elfutils-libs` and
269 Babeltrace was born to parse CTF traces produced by LTTng{nbsp}2.0 and
270 pretty-print their events.
272 Even though Babeltrace is independent from the LTTng project today,
273 their communities remain very close, which is why they share some
274 communication channels and services.
278 https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[lttng-dev]
279 (mailto:lttng-dev@lists.lttng.org[lttng-dev@lists.lttng.org])
282 irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network
285 https://bugs.lttng.org/projects/babeltrace[Babeltrace bug tracker]
288 https://github.com/efficios/babeltrace/[efficios/babeltrace]
290 Continuous integration::
291 https://ci.lttng.org/job/babeltrace_master_build/[Babeltrace's master build]
295 https://review.lttng.org/q/project:babeltrace[_babeltrace_ project]