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.
67 * Any {cpp} compiler with {cpp}11 support (for example,
68 GCC{nbsp}≥{nbsp}4.8 and Clang{nbsp}≥{nbsp}3.3).
71 * https://www.gnu.org/software/make/[GNU Make]
72 * **If you build from a Git clone**:
73 ** https://www.gnu.org/software/automake/[GNU Automake]{nbsp}≥{nbsp}1.12
74 ** https://www.gnu.org/software/autoconf/[GNU Autoconf]{nbsp}≥{nbsp}2.69
75 ** https://www.gnu.org/software/libtool/[GNU Libtool]{nbsp}≥{nbsp}2.2
76 ** https://github.com/westes/flex[flex]{nbsp}≥{nbsp}2.5.35
77 ** https://www.gnu.org/software/bison/bison.html[GNU Bison]{nbsp}≥{nbsp}2.5
80 * A C library (for example,
81 https://www.gnu.org/software/libc/[GNU{nbsp}C Library],
82 https://www.musl-libc.org/[musl libc])
83 * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28
84 (Debian/Ubuntu: `libglib2.0-dev`; Fedora: `glib2-devel`)
86 _**If you need the `bt2` Python bindings**_::
87 * https://www.python.org[Python]{nbsp}≥{nbsp}3.4 (development
88 libraries and `python3-config`)
89 (Debian/Ubuntu: `python3-dev`; Fedora: `python3-devel`)
90 * http://www.swig.org[SWIG]{nbsp}≥{nbsp}3.0
92 _**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`])**_::
93 * https://sourceware.org/elfutils/[elfutils]{nbsp}≥{nbsp}0.154
94 (Debian/Ubuntu: `libelf-dev` and `libdw-dev`;
95 Fedora: `elfutils-devel` and `elfutils-libelf-devel`)
97 _**If you need the {bt2}{nbsp}C{nbsp}API HTML documentation**_::
98 * http://www.doxygen.nl/[Doxygen]{nbsp}≥{nbsp}1.8.6
100 _**If you need the {bt2} manual pages**_::
101 * https://www.methods.co.nz/asciidoc/[Asciidoc]{nbsp}≥{nbsp}8.6.8
102 * https://pagure.io/xmlto[xmlto]{nbsp}≥{nbsp}0.0.25
104 _**If you need the `bt2` Python bindings documentation**_::
105 * https://www.sphinx-doc.org/[Sphinx]{nbsp}≥{nbsp}1.3 for
107 (Debian/Ubuntu/Fedora: `python3-sphinx`)
114 . **If you build from a Git clone**, do:
121 This generates the `configure` script and other important files.
123 . [[conf]]Configure the project:
131 The following options can modify the build:
134 Build the {bt2}{nbsp}C{nbsp}API HTML documentation.
136 `--enable-debug-info`::
137 Build the https://lttng.org/[LTTng] debug information filter
139 (https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`]).
141 `--enable-man-pages`::
142 Build the {bt2} manual pages.
144 `--enable-python-bindings`::
145 Build the `bt2` Python bindings.
147 You can set the path to custom `python3` and `python3-config` programs
148 with the `PYTHON` and `PYTHON_CONFIG` environment variable.
150 `--enable-python-bindings-doc`::
151 Build the `bt2` Python bindings documentation.
153 `--enable-python-plugins`::
154 Build support for {bt2} Python plugins.
156 The following environment variables can modify the build:
158 `BABELTRACE_DEBUG_MODE`::
159 Set to `1` to enable the debug mode.
161 The debug mode enables more run-time assertions to detect bugs in the
164 `BABELTRACE_DEV_MODE`::
165 Set to `1` to enable the <<dev-mode,developer mode>>.
167 The {bt2} developer mode enables more precondition and postcondition
168 assertions to detect programming errors.
170 `BABELTRACE_MINIMAL_LOG_LEVEL`::
171 Set the build-time, minimal logging level for all the project's
174 Set to `TRACE`, `DEBUG`, or `INFO`.
176 `BABELTRACE_PLUGIN_PROVIDERS_DIR`::
177 Installation directory of {bt2} plugin providers.
179 `BABELTRACE_PLUGINS_DIR`::
180 Installation directory of {bt2} project plugins.
182 See `./configure --help` to list all the available options and
183 environment variables.
204 === Build {bt2} for plugin or application development
206 If you are developing a {bt2} plugin or an application which uses
207 libbabeltrace2, we recommend that:
209 * You build {bt2} from source in _developer mode_.
211 The {bt2} developer mode enables more precondition and postcondition
212 assertions to detect programming errors.
214 Set `BABELTRACE_DEV_MODE=1` when you <<conf,configure>> the {bt2} build.
216 * You use _TRACE_ as the minimal logging level at build time to have
217 access to more logging, should you need it to debug your plugin or
220 Set `BABELTRACE_MINIMAL_LOG_LEVEL=TRACE` when you <<conf,configure>>
223 {bt2} development build configuration command line example:
227 $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure
230 {bt2} development build configuration with Python support example:
234 $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure \
235 --enable-python-bindings --enable-python-plugins
239 https://babeltrace.org/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API]
240 documentation for more information.
243 == Use Babeltrace{nbsp}{btversion}
245 See the https://babeltrace.org[Babeltrace website] to learn how
246 to use the different parts of the project.
249 === Run-time requirements
252 * A C library (for example,
253 https://www.gnu.org/software/libc/[GNU{nbsp}C Library],
254 https://www.musl-libc.org/[musl libc])
255 * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28
256 (Debian/Ubuntu: `libglib2.0-0`; Fedora: `glib2`)
258 _**If you need the `bt2` Python bindings**_::
259 * https://www.python.org[Python]{nbsp}≥{nbsp}3.4
260 (Debian/Ubuntu/Fedora: `python3`)
262 _**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`])**_::
263 * https://sourceware.org/elfutils/[elfutils]{nbsp}≥{nbsp}0.154
264 (Debian/Ubuntu: `libelf` and `libdw`; Fedora: `elfutils-libs` and
272 Babeltrace was born to parse CTF traces produced by LTTng{nbsp}2.0 and
273 pretty-print their events.
275 Even though Babeltrace is independent from the LTTng project today,
276 their communities remain very close, which is why they share some
277 communication channels and services.
281 https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[lttng-dev]
282 (mailto:lttng-dev@lists.lttng.org[lttng-dev@lists.lttng.org])
285 irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network
288 https://bugs.lttng.org/projects/babeltrace[Babeltrace bug tracker]
291 https://github.com/efficios/babeltrace/[efficios/babeltrace]
293 Continuous integration::
294 https://ci.lttng.org/job/babeltrace_master_build/[Babeltrace's master build]
298 https://review.lttng.org/q/project:babeltrace[_babeltrace_ project]