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