fix: running black on python 3.11
[babeltrace.git] / 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.5
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
This page took 0.035824 seconds and 4 git commands to generate.