Commit | Line | Data |
---|---|---|
1042d167 PP |
1 | // Render with Asciidoctor |
2 | ||
3 | = Babeltrace | |
2467456d | 4 | 13 April 2020 |
1042d167 PP |
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 | |
e8961c83 PP |
18 | https://babeltrace.org/docs/v{btversion}/libbabeltrace2[C{nbsp}API], |
19 | https://babeltrace.org/docs/v{btversion}/python/bt2[Python{nbsp}3 bindings], | |
1042d167 | 20 | and a |
e8961c83 | 21 | https://babeltrace.org/docs/v{btversion}/man1/babeltrace2.1/[command-line tool] |
1042d167 PP |
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 | ||
e8961c83 | 32 | See Babeltrace's https://babeltrace.org[official website], in |
1042d167 | 33 | particular the |
e8961c83 | 34 | https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-intro.7[`**babeltrace2-intro**(7)`] |
1042d167 PP |
35 | manual page, to learn more about the project. |
36 | ||
37 | [NOTE] | |
38 | .Babeltrace{nbsp}1 vs. {bt2} | |
39 | ==== | |
f1f3b045 | 40 | The Babeltrace project exists since 2010. In 2020, {bt2} was |
1042d167 PP |
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**: | |
642cf605 | 70 | ** https://www.gnu.org/software/automake/[GNU Automake]{nbsp}≥{nbsp}1.12 |
1042d167 PP |
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 | |
cdca5604 | 74 | ** https://www.gnu.org/software/bison/bison.html[GNU Bison]{nbsp}≥{nbsp}2.5 |
1042d167 PP |
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]) | |
791f3058 | 80 | * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28 |
1042d167 PP |
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 | ||
e8961c83 | 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`])**_:: |
1042d167 PP |
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 | ||
1042d167 PP |
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 | ||
2467456d SM |
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 | ||
1042d167 PP |
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 | |
e8961c83 | 136 | (https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`]). |
1042d167 PP |
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 | |
e8961c83 | 236 | https://babeltrace.org/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API] |
1042d167 PP |
237 | documentation for more information. |
238 | ||
239 | ||
240 | == Use Babeltrace{nbsp}{btversion} | |
241 | ||
e8961c83 | 242 | See the https://babeltrace.org[Babeltrace website] to learn how |
1042d167 PP |
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]) | |
791f3058 | 252 | * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28 |
1042d167 PP |
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 | ||
e8961c83 | 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`])**_:: |
1042d167 PP |
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 | ||
a88d97c0 | 272 | Even though Babeltrace is independent from the LTTng project today, |
1042d167 PP |
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 |