README.adoc

   1 // Render with Asciidoctor
   2
   3 = Babeltrace
   4 15 October 2019
   5 :btversion: 2.0
   6 :bt2: Babeltrace{nbsp}2
   7
   8
   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.
  13
  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[]]
  16
  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],
  20 and a
  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.
  24
  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.
  31
  32 See Babeltrace's https://babeltrace.org[official website], in
  33 particular the
  34 https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-intro.7[`**babeltrace2-intro**(7)`]
  35 manual page, to learn more about the project.
  36
  37 [NOTE]
  38 .Babeltrace{nbsp}1 vs. {bt2}
  39 ====
  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.
  44
  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
  48 files.
  49
  50 This file documents the **{bt2}** project.
  51 ====
  52
  53
  54 == Build Babeltrace{nbsp}{btversion} from source
  55
  56 === Build-time requirements
  57
  58 To build Babeltrace{nbsp}{btversion}, you need:
  59
  60 Compiler::
  61     * Any https://gcc.gnu.org/[GCC]-like compiler with C99 and
  62       https://gcc.gnu.org/onlinedocs/gcc/C-Extensions.html[GNU extension]
  63       support.
  64 +
  65 https://clang.llvm.org/[Clang] is one of those.
  66
  67 Tools::
  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.4
  75
  76 Libraries::
  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`)
  82
  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
  88
  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`)
  93
  94 _**If you need the {bt2}{nbsp}C{nbsp}API HTML documentation**_::
  95     * http://www.doxygen.nl/[Doxygen]{nbsp}≥{nbsp}1.8.6
  96
  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
 100
 101
 102 === Procedure
 103
 104 To build {bt2}:
 105
 106 . **If you build from a Git clone**, do:
 107 +
 108 [role="term"]
 109 ----
 110 $ ./bootstrap
 111 ----
 112 +
 113 This generates the `configure` script and other important files.
 114
 115 . [[conf]]Configure the project:
 116 +
 117 [role="term"]
 118 ----
 119 $ ./configure
 120 ----
 121 +
 122 --
 123 The following options can modify the build:
 124
 125 `--enable-api-doc`::
 126     Build the {bt2}{nbsp}C{nbsp}API HTML documentation.
 127
 128 `--enable-debug-info`::
 129     Build the https://lttng.org/[LTTng] debug information filter
 130     component class
 131     (https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`]).
 132
 133 `--enable-man-pages`::
 134     Build the {bt2} manual pages.
 135
 136 `--enable-python-bindings`::
 137     Build the `bt2` Python bindings.
 138 +
 139 You can set the path to custom `python3` and `python3-config` programs
 140 with the `PYTHON` and `PYTHON_CONFIG` environment variable.
 141
 142 `--enable-python-bindings-doc`::
 143     Build the `bt2` Python bindings documentation.
 144
 145 `--enable-python-plugins`::
 146     Build support for {bt2} Python plugins.
 147
 148 The following environment variables can modify the build:
 149
 150 `BABELTRACE_DEBUG_MODE`::
 151     Set to `1` to enable the debug mode.
 152 +
 153 The debug mode enables more run-time assertions to detect bugs in the
 154 {bt2} project.
 155
 156 `BABELTRACE_DEV_MODE`::
 157     Set to `1` to enable the <<dev-mode,developer mode>>.
 158 +
 159 The {bt2} developer mode enables more precondition and postcondition
 160 assertions to detect programming errors.
 161
 162 `BABELTRACE_MINIMAL_LOG_LEVEL`::
 163     Set the build-time, minimal logging level for all the project's
 164     modules.
 165 +
 166 Set to `TRACE`, `DEBUG`, or `INFO`.
 167
 168 `BABELTRACE_PLUGIN_PROVIDERS_DIR`::
 169     Installation directory of {bt2} plugin providers.
 170
 171 `BABELTRACE_PLUGINS_DIR`::
 172     Installation directory of {bt2} project plugins.
 173
 174 See `./configure --help` to list all the available options and
 175 environment variables.
 176 --
 177
 178 . Build {bt2}:
 179 +
 180 [role="term"]
 181 ----
 182 $ make
 183 ----
 184
 185 To install {bt2}:
 186
 187 * Do:
 188 +
 189 [role="term"]
 190 ----
 191 # make install
 192 ----
 193
 194
 195 [[dev-mode]]
 196 === Build {bt2} for plugin or application development
 197
 198 If you are developing a {bt2} plugin or an application which uses
 199 libbabeltrace2, we recommend that:
 200
 201 * You build {bt2} from source in _developer mode_.
 202 +
 203 The {bt2} developer mode enables more precondition and postcondition
 204 assertions to detect programming errors.
 205 +
 206 Set `BABELTRACE_DEV_MODE=1` when you <<conf,configure>> the {bt2} build.
 207
 208 * You use _TRACE_ as the minimal logging level at build time to have
 209   access to more logging, should you need it to debug your plugin or
 210   application.
 211 +
 212 Set `BABELTRACE_MINIMAL_LOG_LEVEL=TRACE` when you <<conf,configure>>
 213 the {bt2} build.
 214
 215 {bt2} development build configuration command line example:
 216
 217 [role="term"]
 218 ----
 219 $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure
 220 ----
 221
 222 {bt2} development build configuration with Python support example:
 223
 224 [role="term"]
 225 ----
 226 $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure \
 227   --enable-python-bindings --enable-python-plugins
 228 ----
 229
 230 See the
 231 https://babeltrace.org/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API]
 232 documentation for more information.
 233
 234
 235 == Use Babeltrace{nbsp}{btversion}
 236
 237 See the https://babeltrace.org[Babeltrace website] to learn how
 238 to use the different parts of the project.
 239
 240
 241 === Run-time requirements
 242
 243 Libraries::
 244     * A C library (for example,
 245       https://www.gnu.org/software/libc/[GNU{nbsp}C Library],
 246       https://www.musl-libc.org/[musl libc])
 247     * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28
 248       (Debian/Ubuntu: `libglib2.0-0`; Fedora: `glib2`)
 249
 250 _**If you need the `bt2` Python bindings**_::
 251     * https://www.python.org[Python]{nbsp}≥{nbsp}3.4
 252       (Debian/Ubuntu/Fedora: `python3`)
 253
 254 _**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`])**_::
 255     * https://sourceware.org/elfutils/[elfutils]{nbsp}≥{nbsp}0.154
 256       (Debian/Ubuntu: `libelf` and `libdw`; Fedora: `elfutils-libs` and
 257       `elfutils-libelf`)
 258
 259
 260 == Community
 261
 262 [NOTE]
 263 ====
 264 Babeltrace was born to parse CTF traces produced by LTTng{nbsp}2.0 and
 265 pretty-print their events.
 266
 267 Even though Babeltrace is independent from the LTTng project today,
 268 their communities remain very close, which is why they share some
 269 communication channels and services.
 270 ====
 271
 272 Mailing list::
 273     https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[lttng-dev]
 274     (mailto:lttng-dev@lists.lttng.org[lttng-dev@lists.lttng.org])
 275
 276 IRC channel::
 277     irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network
 278
 279 Bug tracker::
 280     https://bugs.lttng.org/projects/babeltrace[Babeltrace bug tracker]
 281
 282 GitHub project::
 283     https://github.com/efficios/babeltrace/[efficios/babeltrace]
 284
 285 Continuous integration::
 286     https://ci.lttng.org/job/babeltrace_master_build/[Babeltrace's master build]
 287     on LTTng's CI
 288
 289 Code review::
 290     https://review.lttng.org/q/project:babeltrace[_babeltrace_ project]
 291     on LTTng Review