tools/format-cpp: run `xargs` with `-P$(nproc)` (format in parallel)
[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 * 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.5
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
This page took 0.043862 seconds and 4 git commands to generate.