ctf-writer: Fix -Wredundant-decls warning
[babeltrace.git] / README.adoc
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])
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://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])
253 * https://developer.gnome.org/glib/[GLib]{nbsp}≥{nbsp}2.28
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
This page took 0.035121 seconds and 4 git commands to generate.