4 The guides in this section are step-by-step procedures to accomplish
5 common tasks with libbabeltrace2.
7 Guides help you navigate through the most important features of
8 the library and its API.
10 Make sure to eventually read \ref api-fund before you use the \bt_api
13 The available guides are:
15 - \subpage guide-build-bt2-dev
16 - \subpage guide-comp-link-plugin-so
17 - \subpage guide-comp-link-app
21 - \subpage guide-create-graph
22 - \subpage guide-write-min-src-comp-cls
23 - \subpage guide-write-min-flt-comp-cls
24 - \subpage guide-write-min-sink-comp-cls
25 - \subpage guide-write-simple-sink-comp-cls
26 - \subpage guide-create-plugin
27 - \subpage guide-write-full-src-comp-cls
28 - \subpage guide-write-full-flt-comp-cls
29 - \subpage guide-write-full-sink-comp-cls
30 - \subpage guide-query
31 - \subpage guide-seek-msg-iter
32 - \subpage guide-intr-graph
33 - \subpage guide-intr-query
34 - \subpage guide-graph-listeners
38 @page guide-build-bt2-dev Build Babeltrace 2 for development
40 If you are developing a \bt_name \bt_plugin or an application which uses
41 libbabeltrace2, we recommend that:
43 - You build \bt_name from source in <em>developer mode</em>.
45 The \bt_name developer mode enables more \ref api-fund-pre-post
46 "precondition and postcondition" assertions to detect
49 - You use \em TRACE as the minimal logging level at build time to have
50 access to more \ref api-fund-logging "logging", should you need it
51 to debug your plugin or application.
53 To build \bt_name from source in developer mode and using \em TRACE
54 as the minimal logging level:
58 <a href="https://babeltrace.org/#bt2-get">Download the
59 \bt_name tarball</a> and extract it.
62 <a href="https://github.com/efficios/babeltrace/blob/stable-\bt_version_min_maj/README.adoc">README</a>
63 for build-time requirements and detailed build instructions.
65 Configure the build in developer mode and with the \em TRACE
66 minimal logging level:
69 $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure
72 Build and install the project:
80 \bt_name developer mode build configuration command line examples:
83 $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure \
84 --enable-python-bindings --enable-python-plugins
88 $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure \
89 --prefix="$PWD/install" --disable-man-pages --disable-debug-info
94 The development build creates a libbabeltrace2 library which is
95 slower to execute than a production (default) build.
97 We believe that, during the development process, a less efficient,
98 but more strict library is more desirable than the opposite.
101 @page guide-comp-link-plugin-so Compile and link a Babeltrace 2 shared object plugin
103 To compile and link a \bt_name shared object plugin:
107 Compile the plugin's C/C++ source files with the
108 <a href="https://gcc.gnu.org/onlinedocs/gcc/Code-Gen-Options.html"><code>\-fPIC</code></a>
110 <a href="https://gcc.gnu.org/onlinedocs/gcc/Overall-Options.html"><code>\-c</code></a>
111 compiler options to produce position-independent code and
112 to compile without linking:
115 $ cc my-plugin.c analysis.c -fPIC -c $(pkg-config --cflags babeltrace2)
120 Link the resulting object files with the
121 <a href="https://gcc.gnu.org/onlinedocs/gcc/Link-Options.html"><code>\-shared</code></a>
122 linker option and with the \bt_name library:
125 $ ld my-plugin.o analysis.o -o my-plugin.so -shared $(pkg-config --libs babeltrace2)
131 At least one of your C/C++ files must declare a \bt_name plugin
132 and one or more \bt_p_comp_cls using the \ref api-plugin-dev macros.
134 @page guide-comp-link-app Compile and link an application which uses libbabeltrace2
136 To compile and link an application which uses libbabeltrace2:
140 Compile your C/C++ files as usual.
144 Link the resulting object files with the \bt_name library:
147 $ ld my-app.o analysis.o -o my-app $(pkg-config --libs babeltrace2)
154 @page guide-create-graph Create a graph from existing component classes and run it
158 @page guide-write-min-src-comp-cls Write a minimal source component class
162 @page guide-write-min-flt-comp-cls Write a minimal filter component class
166 @page guide-write-min-sink-comp-cls Write a minimal sink component class
170 @page guide-write-simple-sink-comp-cls Write a simple sink component class
174 @page guide-create-plugin Create a Babeltrace 2 plugin
178 @page guide-write-full-src-comp-cls Write a complete source component class
182 @page guide-write-full-flt-comp-cls Write a complete filter component class
186 @page guide-write-full-sink-comp-cls Write a complete sink component class
190 @page guide-query Query an object from a component class
194 @page guide-seek-msg-iter Make a message iterator seek
198 @page guide-intr-graph Interrupt a running graph
202 @page guide-intr-query Interrupt a query operation
206 @page guide-graph-listeners Use graph listeners to react to topology events