// SPDX-FileCopyrightText: 2019-2024 Philippe Proulx pproulx@efficios.com // // SPDX-License-Identifier: CC-BY-SA-4.0

// Render with Asciidoctor

= Babeltrace 2 10 February 2026 :btversion: 2.1 :bt2: Babeltrace{nbsp}2 ifdef::env-github[] :toc: macro endif::[] ifndef::env-github[] :toc: left endif::[]

Babeltrace /ˈbæbəltreɪs/, an https://efficios.com/[EfficiOS] project, is an open-source https://en.wikipedia.org/wiki/Tracing_(software)[trace] manipulation framework.

https://ci.lttng.org/job/babeltrace_master_linuxbuild[image:https://img.shields.io/jenkins/s/https/ci.lttng.org/babeltrace_master_linuxbuild.svg[]] https://scan.coverity.com/projects/babeltrace[image:https://img.shields.io/coverity/scan/babeltrace.svg[]]

The {bt2} project offers a library with a https://babeltrace.org/docs/v{btversion}/libbabeltrace2[C{nbsp}API], https://babeltrace.org/docs/v{btversion}/python/bt2[Python{nbsp}3 bindings], and a https://babeltrace.org/docs/v{btversion}/man1/babeltrace2.1/[command-line tool] (CLI) which makes it very easy for mere mortals to view, convert, transform, and analyze traces.

image::doc/api/libbabeltrace2/images/basic-convert-graph.png[A basic {bt2} conversion graph]

{bt2} is also the reference parser implementation of the https://diamon.org/ctf/[Common Trace Format] (CTF), a flexible trace format which various tracers and tools such as https://lttng.org/[LTTng] and https://barectf.org/[barectf] produce natively. The {bt2} library and its Python bindings can read and write CTF traces.

See the {bt2} https://babeltrace.org[official website], in particular the https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-intro.7[**babeltrace2-intro**(7)] manual page, to learn more about the project.

[NOTE] ifdef::env-github[] .Babeltrace{nbsp}1 vs. {bt2} endif::[] ifndef::env-github[] .Babeltrace{nbsp}1 vs. {bt2} endif::[]

The Babeltrace project exists since 2010.

In 2020, {bt2} was released. {bt2} is a complete rewrite of the library, Python bindings, and CLI. It's plugin-based and offers much more features and potential than Babeltrace{nbsp}1 while delivering comparable performance.

Some Linux distributions still provide packages for the Babeltrace{nbsp}1 project. Both projects can coexist on the same system as there are no conflicting files.

This README documents the {bt2} project.

ifdef::env-github[] toc::[] endif::[]

== Build Babeltrace{nbsp}{btversion} from source

=== Build-time requirements

To build Babeltrace{nbsp}{btversion}, you need:

Compiler:: * Any https://gcc.gnu.org/[GCC]-like compiler with C99 and https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html[GNU extension] support. + https://clang.llvm.org/[Clang] is one of those.

* Any {cpp} compiler with {cpp}17 support (for example,
  GCC{nbsp}≥{nbsp}7.5 and Clang{nbsp}≥{nbsp}5).

Tools:: * https://www.gnu.org/software/make/[GNU Make] * If you build from a Git clone: ** https://www.gnu.org/software/automake/[GNU Automake]{nbsp}≥{nbsp}1.13 ** https://www.gnu.org/software/autoconf/[GNU Autoconf]{nbsp}≥{nbsp}2.69 ** https://www.gnu.org/software/libtool/[GNU Libtool]{nbsp}≥{nbsp}2.2 ** https://github.com/westes/flex[flex]{nbsp}≥{nbsp}2.5.35 ** https://www.gnu.org/software/bison/bison.html[GNU Bison]{nbsp}≥{nbsp}3.0

Libraries:: * A C library (for example, https://www.gnu.org/software/libc/[GNU{nbsp}C Library], https://www.musl-libc.org/[musl libc])

* https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.56
  (Debian/Ubuntu: `libglib2.0-dev`; Fedora: `glib2-devel`)

* https://fmt.dev/[pass:[{fmt}]]{nbsp}≥{nbsp}10.1.1
  (Debian/Ubuntu: `libfmt-dev`; Fedora: `fmt-devel`)

+ Use an in-tree pass:[{fmt}] with --enable-vendor-fmt if you can't install it.

If you need the bt2 Python bindings:: * https://www.python.org[Python]{nbsp}≥{nbsp}3.5 (development libraries and python3-config) (Debian/Ubuntu: python3-dev; Fedora: python3-devel) * http://www.swig.org[SWIG]{nbsp}≥{nbsp}3.0

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]):: * https://sourceware.org/elfutils/[elfutils]{nbsp}≥{nbsp}0.154 (Debian/Ubuntu: libelf-dev and libdw-dev; Fedora: elfutils-devel and elfutils-libelf-devel)

If you need the {bt2}{nbsp}C{nbsp}API HTML documentation:: * http://www.doxygen.nl/[Doxygen]{nbsp}≥{nbsp}1.8.6

If you need the {bt2} manual pages:: * https://www.methods.co.nz/asciidoc/[Asciidoc]{nbsp}≥{nbsp}8.6.8 * https://pagure.io/xmlto[xmlto]{nbsp}≥{nbsp}0.0.25

If you need the bt2 Python bindings documentation:: * https://www.sphinx-doc.org/[Sphinx]{nbsp}≥{nbsp}1.3 for Python{nbsp}3 (Debian/Ubuntu/Fedora: python3-sphinx)

If you need to build and run the tests:: {empty} +

• https://www.python.org[Python]{nbsp}≥{nbsp}3.5 (development libraries and python3-config) (Debian/Ubuntu: python3-dev; Fedora: python3-devel)

• https://docs.pytest.org/[pytest]{nbsp}≥{nbsp}6.1.0 (Debian/Ubuntu/Fedora: python3-pytest)

Use an in-tree pytest with --enable-vendor-pytest if you can't install it.

• http://www.swig.org[SWIG]{nbsp}≥{nbsp}3.0

• https://github.com/catchorg/Catch2[Catch2]{nbsp}≥{nbsp}3.7.1 (Debian/Ubuntu: libcatch2-dev)

Use an in-tree Catch2{nbsp}v3 with --enable-vendor-catch2 if you can't install it.

Disable test building with --disable-tests at configuration time.

[NOTE] ifdef::env-github[] .Thanks for the code! endif::[] ifndef::env-github[] .Thanks for the code! endif::[]

We'd like to thank the authors of the following projects which are embedded into the {bt2} source tree:

• https://github.com/catchorg/Catch2[Catch2] (with --enable-vendor-catch2)
• https://github.com/fmtlib/fmt[pass:[{fmt}]] (with --enable-vendor-fmt)
• https://github.com/nlohmann/json[JSON for Modern {cpp}]
• https://github.com/martinmoene/span-lite[span lite]
• https://github.com/quicknir/wise_enum[wise_enum]
• https://github.com/wonder-mice/zf_log[zf_log] ====

=== Procedure

To build {bt2}:

. If you build from a Git clone, do: + [role="term"]

$ ./bootstrap

This generates the configure script and other important files.

. [[conf]]Configure the project: + [role="term"]

$ ./configure

-- The following options can modify the build:

--disable-tests:: Do not build the tests at all. + In that case, the check Make target still works, but it doesn't run any test and exits with status{nbsp}0.

--enable-api-doc:: Build the {bt2}{nbsp}C{nbsp}API HTML documentation.

--enable-built-in-plugins:: Statically link the official plugins into the babeltrace2 executable.

--enable-built-in-python-plugin-support:: Statically link the Python plugin provider into libbabeltrace2.

--enable-debug-info:: Build 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]).

--enable-man-pages:: Build the {bt2} manual pages.

--enable-python-bindings:: Build the bt2 Python bindings. + You can set the path to custom python3 and python3-config programs with the PYTHON and PYTHON_CONFIG environment variable.

--enable-python-bindings-doc:: Build the bt2 Python bindings documentation.

--enable-python-plugins:: Build support for {bt2} Python plugins.

--enable-vendor-pytest:: Use an in-tree pytest instead of an installed one.

The following environment variables can modify the build:

BABELTRACE_DEBUG_MODE:: Set to 1 to enable the debug mode. + The debug mode enables more run-time assertions to detect bugs while developing the {bt2} project.

BABELTRACE_DEV_MODE:: Set to 1 to enable the <<dev-mode,developer mode>>. + The {bt2} developer mode enables more precondition and postcondition assertions to detect C{nbsp}API usage errors.

BABELTRACE_MINIMAL_LOG_LEVEL:: Set the build-time, minimal logging level for all the modules of the project. + Set to TRACE, DEBUG, or INFO.

BABELTRACE_PLUGIN_PROVIDERS_DIR:: Installation directory of {bt2} plugin providers.

BABELTRACE_PLUGINS_DIR:: Installation directory of {bt2} official plugins.

Run ./configure --help to list all the available options and environment variables.

. Build {bt2}: + [role="term"]

$ make

To install {bt2}:

• Run:

[role="term"]

make install

---

[[dev-mode]] === Build {bt2} for plugin or application development

If you're developing a {bt2} plugin or an application which uses libbabeltrace2, we recommend to:

• Build {bt2} from source in developer mode.

The {bt2} developer mode enables more precondition and postcondition assertions to detect C{nbsp}API usage errors. + The https://babeltrace.org/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API documentation] always lists the precondition and postconditions of functions. + Set BABELTRACE_DEV_MODE=1 when you <<conf,configure>> the {bt2} build.

• Use TRACE as the minimal logging level at build time to have access to more logging, should you need it to debug your plugin or application.

Set BABELTRACE_MINIMAL_LOG_LEVEL=TRACE when you <<conf,configure>> the {bt2} build.

{bt2} development build configuration command line example:

[role="term"]

$ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure

{bt2} development build configuration with Python support example:

[role="term"]

$ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure
--enable-python-bindings --enable-python-plugins

See the https://babeltrace.org/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API documentation] for