Commit | Line | Data |
---|---|---|
94313b56 PP |
1 | // Render with Asciidoctor |
2 | ||
3 | = Babeltrace | |
ba64dfcc | 4 | 13 April 2020 |
94313b56 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 | |
fe0b4563 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], | |
94313b56 | 20 | and a |
fe0b4563 | 21 | https://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, |
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 | ||
fe0b4563 | 32 | See Babeltrace's https://babeltrace.org[official website], in |
94313b56 | 33 | particular the |
fe0b4563 | 34 | https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-intro.7[`**babeltrace2-intro**(7)`] |
94313b56 PP |
35 | manual page, to learn more about the project. |
36 | ||
37 | [NOTE] | |
38 | .Babeltrace{nbsp}1 vs. {bt2} | |
39 | ==== | |
2f06de00 | 40 | The Babeltrace project exists since 2010. In 2020, {bt2} was |
94313b56 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 | ||
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 |
70 | Tools:: |
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 | ||
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]) | |
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 | ||
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 | |
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 | + | |
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 | |
fe0b4563 | 239 | https://babeltrace.org/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API] |
94313b56 PP |
240 | documentation for more information. |
241 | ||
242 | ||
243 | == Use Babeltrace{nbsp}{btversion} | |
244 | ||
fe0b4563 | 245 | See the https://babeltrace.org[Babeltrace website] to learn how |
94313b56 PP |
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]) | |
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 | ==== | |
272 | Babeltrace was born to parse CTF traces produced by LTTng{nbsp}2.0 and | |
273 | pretty-print their events. | |
274 | ||
b48c8cb5 | 275 | Even though Babeltrace is independent from the LTTng project today, |
94313b56 PP |
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 |