Libbtrace

Libbtrace is an open-source Common Trace Format (CTF) parser providing C API, Python 3 bindings, as well as command-line interface (CLI), that allows to view, convert, transform and analyze traces.

It is based on parts of Babeltrace 2.

Table of Contents

• Build libbtrace from source
  • Build-time requirements
  • Procedure
  • Build libbtrace for plugin or application development
• Use libbtrace
  • Run-time requirements

Build libbtrace from source

Build-time requirements

To build libbtrace, you need:

Compiler

• Any GCC-like compiler with C99 and GNU extension support.

  Clang is one of those.

• Any C++ compiler with C++11 support (for example, GCC ≥ 4.8 and Clang ≥ 3.3).

Tools

• GNU Make

• If you build from a Git clone:

  • GNU Automake ≥ 1.13

  • GNU Autoconf ≥ 2.69

  • GNU Libtool ≥ 2.2

  • flex ≥ 2.5.35

  • GNU Bison ≥ 2.5

Libraries

• A C library (for example, GNU C Library, musl libc)

• GLib ≥ 2.28 (Debian/Ubuntu: libglib2.0-dev; Fedora: glib2-devel)

If you need the bt2 Python bindings

• Python ≥ 3.4 (development libraries and python3-config) (Debian/Ubuntu: python3-dev; Fedora: python3-devel)

• SWIG ≥ 3.0

If you need the LTTng debug information filter component class (filter.lttng-utils.debug-info)

• elfutils ≥ 0.154 (Debian/Ubuntu: libelf-dev and libdw-dev; Fedora: elfutils-devel and elfutils-libelf-devel)

If you need the libbtrace C API HTML documentation

• Doxygen ≥ 1.8.6

If you need the libbtrace manual pages

• Asciidoc ≥ 8.6.8

• xmlto ≥ 0.0.25

If you need the bt2 Python bindings documentation

• Sphinx ≥ 1.3 for Python 3 (Debian/Ubuntu/Fedora: python3-sphinx)

Note	Thanks for the code! We’d like to thank the authors of the following projects which are embedded into the libbtrace source tree: {fmt} JSON for Modern C++ optional lite span lite string_view lite wise_enum zf_log

Procedure

To build libbtrace:

1. If you build from a Git clone, do:

   $ ./bootstrap

   This generates the configure script and other important files.

2. Configure the project:

   $ ./configure

   The following options can modify the build:

   --enable-api-doc

   Build the libbtrace C 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 the babeltrace2 executable.

   --enable-debug-info

   Build the LTTng debug information filter component class (filter.lttng-utils.debug-info).

   --enable-man-pages

   Build the libbtrace 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 libbtrace Python plugins.

   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 libbtrace project.

   BABELTRACE_DEV_MODE

   Set to 1 to enable the developer mode.

   The libbtrace developer mode enables more precondition and postcondition assertions to detect C 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 libbtrace plugin providers.

   BABELTRACE_PLUGINS_DIR

   Installation directory of libbtrace official plugins.

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

3. Build libbtrace:

   $ make

To install libbtrace:

• Run:

  # make install

Build libbtrace for plugin or application development

If you’re developing a libbtrace plugin or an application which uses libbabeltrace2, we recommend to:

• Build libbtrace from source in developer mode.

  The libbtrace developer mode enables more precondition and postcondition assertions to detect C API usage errors.

  The Babeltrace C API documentation always lists the precondition and postconditions of functions.

  Set BABELTRACE_DEV_MODE=1 when you configure the libbtrace 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 configure the libbtrace build.

libbtrace development build configuration command line example:

$ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure

libbtrace development build configuration with Python support example:

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

See the Babeltrace C API documentation for more information.

Use libbtrace

See the Babeltrace website to learn how to use the different parts of the project.

If you’re new to libbtrace, make sure to read the babeltrace2-intro(7) manual page to familiarize yourself with the project.

Run-time requirements

Libraries

• A C library (for example, GNU C Library or musl libc)

• GLib ≥ 2.28 (Debian/Ubuntu: libglib2.0-0; Fedora: glib2)

If you need the bt2 Python bindings

• Python ≥ 3.4 (Debian/Ubuntu/Fedora: python3)

If you need the LTTng debug information filter component class (filter.lttng-utils.debug-info)

• elfutils ≥ 0.154 (Debian/Ubuntu: libelf and libdw; Fedora: elfutils-libs and elfutils-libelf)