RFC: docs: fix: Match stated automake requirement
[babeltrace.git] / README.adoc
CommitLineData
1042d167
PP
1// Render with Asciidoctor
2
3= Babeltrace
2467456d 413 April 2020
1042d167
PP
5:btversion: 2.0
6:bt2: Babeltrace{nbsp}2
7
8
9Babeltrace /ˈbæbəltreɪs/, an
10https://efficios.com/[EfficiOS] project, is an open-source
11https://en.wikipedia.org/wiki/Tracing_(software)[trace]
12manipulation framework.
13
14https://ci.lttng.org/job/babeltrace_master_build[image:https://img.shields.io/jenkins/s/https/ci.lttng.org/babeltrace_master_build.svg[]]
15https://scan.coverity.com/projects/babeltrace[image:https://img.shields.io/coverity/scan/babeltrace.svg[]]
16
17The **_{bt2}_** project offers a library with a
e8961c83
PP
18https://babeltrace.org/docs/v{btversion}/libbabeltrace2[C{nbsp}API],
19https://babeltrace.org/docs/v{btversion}/python/bt2[Python{nbsp}3 bindings],
1042d167 20and a
e8961c83 21https://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,
23transform, and analyze traces.
24
25{bt2} is also the reference parser implementation of the
26https://diamon.org/ctf/[Common Trace Format] (CTF), a versatile
27trace format produced by various tracers and tools such as
28https://lttng.org/[LTTng] and
29https://barectf.org/[barectf]. The {bt2} library and its Python bindings
30can read and write CTF traces.
31
e8961c83 32See Babeltrace's https://babeltrace.org[official website], in
1042d167 33particular the
e8961c83 34https://babeltrace.org/docs/v{btversion}/man7/babeltrace2-intro.7[`**babeltrace2-intro**(7)`]
1042d167
PP
35manual page, to learn more about the project.
36
37[NOTE]
38.Babeltrace{nbsp}1 vs. {bt2}
39====
f1f3b045 40The Babeltrace project exists since 2010. In 2020, {bt2} was
1042d167
PP
41released. {bt2} is a complete rewrite of the library, Python
42bindings, and CLI. It is plugin-based and offers much more features and
43potential than Babeltrace{nbsp}1 while showing comparable performance.
44
45Because {bt2} is still a young major release, some
46distributions still provide packages for the Babeltrace{nbsp}1 project.
47Both projects can coexist on the same system as there are no common
48files.
49
50This file documents the **{bt2}** project.
51====
52
53
54== Build Babeltrace{nbsp}{btversion} from source
55
56=== Build-time requirements
57
58To build Babeltrace{nbsp}{btversion}, you need:
59
60Compiler::
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+
65https://clang.llvm.org/[Clang] is one of those.
66
67Tools::
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
76Libraries::
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
109To build {bt2}:
110
111. **If you build from a Git clone**, do:
112+
113[role="term"]
114----
115$ ./bootstrap
116----
117+
118This generates the `configure` script and other important files.
119
120. [[conf]]Configure the project:
121+
122[role="term"]
123----
124$ ./configure
125----
126+
127--
128The 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+
144You can set the path to custom `python3` and `python3-config` programs
145with 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
153The following environment variables can modify the build:
154
155`BABELTRACE_DEBUG_MODE`::
156 Set to `1` to enable the debug mode.
157+
158The 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+
164The {bt2} developer mode enables more precondition and postcondition
165assertions 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+
171Set 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
179See `./configure --help` to list all the available options and
180environment variables.
181--
182
183. Build {bt2}:
184+
185[role="term"]
186----
187$ make
188----
189
190To 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
203If you are developing a {bt2} plugin or an application which uses
204libbabeltrace2, we recommend that:
205
206* You build {bt2} from source in _developer mode_.
207+
208The {bt2} developer mode enables more precondition and postcondition
209assertions to detect programming errors.
210+
211Set `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+
217Set `BABELTRACE_MINIMAL_LOG_LEVEL=TRACE` when you <<conf,configure>>
218the {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
235See the
e8961c83 236https://babeltrace.org/docs/v{btversion}/libbabeltrace2[{bt2}{nbsp}C{nbsp}API]
1042d167
PP
237documentation for more information.
238
239
240== Use Babeltrace{nbsp}{btversion}
241
e8961c83 242See the https://babeltrace.org[Babeltrace website] to learn how
1042d167
PP
243to use the different parts of the project.
244
245
246=== Run-time requirements
247
248Libraries::
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====
269Babeltrace was born to parse CTF traces produced by LTTng{nbsp}2.0 and
270pretty-print their events.
271
a88d97c0 272Even though Babeltrace is independent from the LTTng project today,
1042d167
PP
273their communities remain very close, which is why they share some
274communication channels and services.
275====
276
277Mailing 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
281IRC channel::
282 irc://irc.oftc.net/lttng[`#lttng`] on the OFTC network
283
284Bug tracker::
285 https://bugs.lttng.org/projects/babeltrace[Babeltrace bug tracker]
286
287GitHub project::
288 https://github.com/efficios/babeltrace/[efficios/babeltrace]
289
290Continuous integration::
291 https://ci.lttng.org/job/babeltrace_master_build/[Babeltrace's master build]
292 on LTTng's CI
293
294Code review::
295 https://review.lttng.org/q/project:babeltrace[_babeltrace_ project]
296 on LTTng Review
This page took 0.045842 seconds and 4 git commands to generate.