Fix: src.ctf.fs: Not resolving event common ctx
[babeltrace.git] / README.adoc
CommitLineData
94313b56
PP
1// Render with Asciidoctor
2
3= Babeltrace
ba64dfcc 413 April 2020
94313b56
PP
5:btversion: 2.0
6:bt2: Babeltrace{nbsp}2
7
8
9Babeltrace /ˈbæbəltreɪs/, an
10https://efficios.com/[EfficiOS] project, is an open-source
11https://en.wikipedia.org/wiki/Tracing_(software)[trace]
12manipulation framework.
13
14https://ci.lttng.org/job/babeltrace_master_build[image:https://img.shields.io/jenkins/s/https/ci.lttng.org/babeltrace_master_build.svg[]]
15https://scan.coverity.com/projects/babeltrace[image:https://img.shields.io/coverity/scan/babeltrace.svg[]]
16
17The **_{bt2}_** project offers a library with a
fe0b4563
PP
18https://babeltrace.org/docs/v{btversion}/libbabeltrace2[C{nbsp}API],
19https://babeltrace.org/docs/v{btversion}/python/bt2[Python{nbsp}3 bindings],
94313b56 20and a
fe0b4563 21https://babeltrace.org/docs/v{btversion}/man1/babeltrace2.1/[command-line tool]
94313b56
PP
22(CLI) which makes it very easy for mere mortals to view, convert,
23transform, and analyze traces.
24
25{bt2} is also the reference parser implementation of the
26https://diamon.org/ctf/[Common Trace Format] (CTF), a versatile
27trace format produced by various tracers and tools such as
28https://lttng.org/[LTTng] and
29https://barectf.org/[barectf]. The {bt2} library and its Python bindings
30can read and write CTF traces.
31
fe0b4563 32See Babeltrace's https://babeltrace.org[official website], in
94313b56 33particular the
fe0b4563 34https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-intro.7[`**babeltrace2-intro**(7)`]
94313b56
PP
35manual page, to learn more about the project.
36
37[NOTE]
38.Babeltrace{nbsp}1 vs. {bt2}
39====
2f06de00 40The Babeltrace project exists since 2010. In 2020, {bt2} was
94313b56
PP
41released. {bt2} is a complete rewrite of the library, Python
42bindings, and CLI. It is plugin-based and offers much more features and
43potential than Babeltrace{nbsp}1 while showing comparable performance.
44
45Because {bt2} is still a young major release, some
46distributions still provide packages for the Babeltrace{nbsp}1 project.
47Both projects can coexist on the same system as there are no common
48files.
49
50This file documents the **{bt2}** project.
51====
52
53
54== Build Babeltrace{nbsp}{btversion} from source
55
56=== Build-time requirements
57
58To build Babeltrace{nbsp}{btversion}, you need:
59
60Compiler::
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+
65https://clang.llvm.org/[Clang] is one of those.
66
c20049fd
MJ
67 * Any {cpp} compiler with {cpp}11 support (for example,
68 GCC{nbsp}≥{nbsp}4.8 and Clang{nbsp}≥{nbsp}3.3).
69
94313b56
PP
70Tools::
71 * https://www.gnu.org/software/make/[GNU Make]
72 * **If you build from a Git clone**:
271fb690
MJ
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
94313b56
PP
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
79Libraries::
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])
ef9559ae 83 * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28
94313b56
PP
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
fe0b4563 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`])**_::
94313b56
PP
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
94313b56
PP
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
ba64dfcc
SM
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
94313b56
PP
109
110=== Procedure
111
112To build {bt2}:
113
114. **If you build from a Git clone**, do:
115+
116[role="term"]
117----
118$ ./bootstrap
119----
120+
121This generates the `configure` script and other important files.
122
123. [[conf]]Configure the project:
124+
125[role="term"]
126----
127$ ./configure
128----
129+
130--
131The 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
fe0b4563 139 (https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`]).
94313b56
PP
140
141`--enable-man-pages`::
142 Build the {bt2} manual pages.
143
144`--enable-python-bindings`::
145 Build the `bt2` Python bindings.
146+
147You can set the path to custom `python3` and `python3-config` programs
148with 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
156The following environment variables can modify the build:
157
158`BABELTRACE_DEBUG_MODE`::
159 Set to `1` to enable the debug mode.
160+
161The 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+
167The {bt2} developer mode enables more precondition and postcondition
168assertions 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+
174Set 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
182See `./configure --help` to list all the available options and
183environment variables.
184--
185
186. Build {bt2}:
187+
188[role="term"]
189----
190$ make
191----
192
193To 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
206If you are developing a {bt2} plugin or an application which uses
207libbabeltrace2, we recommend that:
208
209* You build {bt2} from source in _developer mode_.
210+
211The {bt2} developer mode enables more precondition and postcondition
212assertions to detect programming errors.
213+
214Set `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+
220Set `BABELTRACE_MINIMAL_LOG_LEVEL=TRACE` when you <<conf,configure>>
221the {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
238See the
fe0b4563 239https://babeltrace.org/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API]
94313b56
PP
240documentation for more information.
241
242
243== Use Babeltrace{nbsp}{btversion}
244
fe0b4563 245See the https://babeltrace.org[Babeltrace website] to learn how
94313b56
PP
246to use the different parts of the project.
247
248
249=== Run-time requirements
250
251Libraries::
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])
ef9559ae 255 * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28
94313b56
PP
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
fe0b4563 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`])**_::
94313b56
PP
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====
272Babeltrace was born to parse CTF traces produced by LTTng{nbsp}2.0 and
273pretty-print their events.
274
b48c8cb5 275Even though Babeltrace is independent from the LTTng project today,
94313b56
PP
276their communities remain very close, which is why they share some
277communication channels and services.
278====
279
280Mailing 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
284IRC channel::
285 irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network
286
287Bug tracker::
288 https://bugs.lttng.org/projects/babeltrace[Babeltrace bug tracker]
289
290GitHub project::
291 https://github.com/efficios/babeltrace/[efficios/babeltrace]
292
293Continuous integration::
294 https://ci.lttng.org/job/babeltrace_master_build/[Babeltrace's master build]
295 on LTTng's CI
296
297Code review::
298 https://review.lttng.org/q/project:babeltrace[_babeltrace_ project]
299 on LTTng Review
This page took 0.04521 seconds and 4 git commands to generate.