README.adoc

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