Commit | Line | Data |
---|---|---|
94313b56 PP |
1 | // Render with Asciidoctor |
2 | ||
3 | = Babeltrace | |
4 | 15 October 2019 | |
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://diamon.org/babeltrace/docs/v{btversion}/libbabeltrace2[C{nbsp}API], | |
19 | https://diamon.org/babeltrace/docs/v{btversion}/python/bt2[Python{nbsp}3 bindings], | |
20 | and a | |
21 | https://diamon.org/babeltrace/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://diamon.org/babeltrace[official website], in | |
33 | particular the | |
34 | https://diamon.org/babeltrace/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 2019, {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.4 | |
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]) | |
ef9559ae | 80 | * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28 |
94313b56 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 | ||
89 | _**If you need the https://lttng.org/[LTTng] debug information filter component class (https://diamon.org/babeltrace/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` Python bindings documentation**_:: | |
95 | * Python{nbsp}≥{nbsp}3.4 | |
96 | (Debian/Ubuntu/Fedora: `python3`) | |
97 | * https://www.sphinx-doc.org/en/master/[Sphinx]{nbsp}≥{nbsp}1.6.5 | |
98 | for Python{nbsp}3 (Debian/Ubuntu/Fedora: `python3-sphinx`) | |
99 | ||
100 | _**If you need the {bt2}{nbsp}C{nbsp}API HTML documentation**_:: | |
101 | * http://www.doxygen.nl/[Doxygen]{nbsp}≥{nbsp}1.8.6 | |
102 | ||
103 | _**If you need the {bt2} manual pages**_:: | |
104 | * https://www.methods.co.nz/asciidoc/[Asciidoc]{nbsp}≥{nbsp}8.6.8 | |
105 | * https://pagure.io/xmlto[xmlto]{nbsp}≥{nbsp}0.0.25 | |
106 | ||
107 | ||
108 | === Procedure | |
109 | ||
110 | To build {bt2}: | |
111 | ||
112 | . **If you build from a Git clone**, do: | |
113 | + | |
114 | [role="term"] | |
115 | ---- | |
116 | $ ./bootstrap | |
117 | ---- | |
118 | + | |
119 | This generates the `configure` script and other important files. | |
120 | ||
121 | . [[conf]]Configure the project: | |
122 | + | |
123 | [role="term"] | |
124 | ---- | |
125 | $ ./configure | |
126 | ---- | |
127 | + | |
128 | -- | |
129 | The following options can modify the build: | |
130 | ||
131 | `--enable-api-doc`:: | |
132 | Build the {bt2}{nbsp}C{nbsp}API HTML documentation. | |
133 | ||
134 | `--enable-debug-info`:: | |
135 | Build the https://lttng.org/[LTTng] debug information filter | |
136 | component class | |
137 | (https://diamon.org/babeltrace/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`]). | |
138 | ||
139 | `--enable-man-pages`:: | |
140 | Build the {bt2} manual pages. | |
141 | ||
142 | `--enable-python-bindings`:: | |
143 | Build the `bt2` Python bindings. | |
144 | + | |
145 | You can set the path to custom `python3` and `python3-config` programs | |
146 | with the `PYTHON` and `PYTHON_CONFIG` environment variable. | |
147 | ||
148 | `--enable-python-bindings-doc`:: | |
149 | Build the `bt2` Python bindings documentation. | |
150 | ||
151 | `--enable-python-plugins`:: | |
152 | Build support for {bt2} Python plugins. | |
153 | ||
154 | The following environment variables can modify the build: | |
155 | ||
156 | `BABELTRACE_DEBUG_MODE`:: | |
157 | Set to `1` to enable the debug mode. | |
158 | + | |
159 | The debug mode enables more run-time assertions to detect bugs in the | |
160 | {bt2} project. | |
161 | ||
162 | `BABELTRACE_DEV_MODE`:: | |
163 | Set to `1` to enable the <<dev-mode,developer mode>>. | |
164 | + | |
165 | The {bt2} developer mode enables more precondition and postcondition | |
166 | assertions to detect programming errors. | |
167 | ||
168 | `BABELTRACE_MINIMAL_LOG_LEVEL`:: | |
169 | Set the build-time, minimal logging level for all the project's | |
170 | modules. | |
171 | + | |
172 | Set to `TRACE`, `DEBUG`, or `INFO`. | |
173 | ||
174 | `BABELTRACE_PLUGIN_PROVIDERS_DIR`:: | |
175 | Installation directory of {bt2} plugin providers. | |
176 | ||
177 | `BABELTRACE_PLUGINS_DIR`:: | |
178 | Installation directory of {bt2} project plugins. | |
179 | ||
180 | See `./configure --help` to list all the available options and | |
181 | environment variables. | |
182 | -- | |
183 | ||
184 | . Build {bt2}: | |
185 | + | |
186 | [role="term"] | |
187 | ---- | |
188 | $ make | |
189 | ---- | |
190 | ||
191 | To install {bt2}: | |
192 | ||
193 | * Do: | |
194 | + | |
195 | [role="term"] | |
196 | ---- | |
197 | # make install | |
198 | ---- | |
199 | ||
200 | ||
201 | [[dev-mode]] | |
202 | === Build {bt2} for plugin or application development | |
203 | ||
204 | If you are developing a {bt2} plugin or an application which uses | |
205 | libbabeltrace2, we recommend that: | |
206 | ||
207 | * You build {bt2} from source in _developer mode_. | |
208 | + | |
209 | The {bt2} developer mode enables more precondition and postcondition | |
210 | assertions to detect programming errors. | |
211 | + | |
212 | Set `BABELTRACE_DEV_MODE=1` when you <<conf,configure>> the {bt2} build. | |
213 | ||
214 | * You use _TRACE_ as the minimal logging level at build time to have | |
215 | access to more logging, should you need it to debug your plugin or | |
216 | application. | |
217 | + | |
218 | Set `BABELTRACE_MINIMAL_LOG_LEVEL=TRACE` when you <<conf,configure>> | |
219 | the {bt2} build. | |
220 | ||
221 | {bt2} development build configuration command line example: | |
222 | ||
223 | [role="term"] | |
224 | ---- | |
225 | $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure | |
226 | ---- | |
227 | ||
228 | {bt2} development build configuration with Python support example: | |
229 | ||
230 | [role="term"] | |
231 | ---- | |
232 | $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure \ | |
233 | --enable-python-bindings --enable-python-plugins | |
234 | ---- | |
235 | ||
236 | See the | |
237 | https://diamon.org/babeltrace/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API] | |
238 | documentation for more information. | |
239 | ||
240 | ||
241 | == Use Babeltrace{nbsp}{btversion} | |
242 | ||
243 | See the https://diamon.org/babeltrace[Babeltrace website] to learn how | |
244 | to use the different parts of the project. | |
245 | ||
246 | ||
247 | === Run-time requirements | |
248 | ||
249 | Libraries:: | |
250 | * A C library (for example, | |
251 | https://www.gnu.org/software/libc/[GNU{nbsp}C Library], | |
252 | https://www.musl-libc.org/[musl libc]) | |
ef9559ae | 253 | * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28 |
94313b56 PP |
254 | (Debian/Ubuntu: `libglib2.0-0`; Fedora: `glib2`) |
255 | ||
256 | _**If you need the `bt2` Python bindings**_:: | |
257 | * https://www.python.org[Python]{nbsp}≥{nbsp}3.4 | |
258 | (Debian/Ubuntu/Fedora: `python3`) | |
259 | ||
260 | _**If you need the https://lttng.org/[LTTng] debug information filter component class (https://diamon.org/babeltrace/docs/v{btversion}/man7/babeltrace2-filter.lttng-utils.debug-info.7/[`filter.lttng-utils.debug-info`])**_:: | |
261 | * https://sourceware.org/elfutils/[elfutils]{nbsp}≥{nbsp}0.154 | |
262 | (Debian/Ubuntu: `libelf` and `libdw`; Fedora: `elfutils-libs` and | |
263 | `elfutils-libelf`) | |
264 | ||
265 | ||
266 | == Community | |
267 | ||
268 | [NOTE] | |
269 | ==== | |
270 | Babeltrace was born to parse CTF traces produced by LTTng{nbsp}2.0 and | |
271 | pretty-print their events. | |
272 | ||
273 | Even though Babeltrace is independant from the LTTng project today, | |
274 | their communities remain very close, which is why they share some | |
275 | communication channels and services. | |
276 | ==== | |
277 | ||
278 | Mailing list:: | |
279 | https://lists.lttng.org/cgi-bin/mailman/listinfo/lttng-dev[lttng-dev] | |
280 | (mailto:lttng-dev@lists.lttng.org[lttng-dev@lists.lttng.org]) | |
281 | ||
282 | IRC channel:: | |
283 | irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network | |
284 | ||
285 | Bug tracker:: | |
286 | https://bugs.lttng.org/projects/babeltrace[Babeltrace bug tracker] | |
287 | ||
288 | GitHub project:: | |
289 | https://github.com/efficios/babeltrace/[efficios/babeltrace] | |
290 | ||
291 | Continuous integration:: | |
292 | https://ci.lttng.org/job/babeltrace_master_build/[Babeltrace's master build] | |
293 | on LTTng's CI | |
294 | ||
295 | Code review:: | |
296 | https://review.lttng.org/q/project:babeltrace[_babeltrace_ project] | |
297 | on LTTng Review |