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