README.adoc

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