Commit | Line | Data |
---|---|---|
43c59509 PP |
1 | /*! |
2 | @page guides Guides | |
3 | ||
4 | The guides in this section are step-by-step procedures to accomplish | |
5 | common tasks with libbabeltrace2. | |
6 | ||
7 | Guides help you navigate through the most important features of | |
8 | the library and its API. | |
9 | ||
10 | Make sure to eventually read \ref api-fund before you use the \bt_api | |
11 | seriously. | |
12 | ||
13 | The available guides are: | |
14 | ||
15 | - \subpage guide-build-bt2-dev | |
16 | - \subpage guide-comp-link-plugin-so | |
17 | - \subpage guide-comp-link-app | |
18 | ||
19 | @if meow | |
20 | ||
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 | |
35 | ||
36 | @endif | |
37 | ||
38 | @page guide-build-bt2-dev Build Babeltrace 2 for development | |
39 | ||
40 | If you are developing a \bt_name \bt_plugin or an application which uses | |
41 | libbabeltrace2, we recommend that: | |
42 | ||
43 | - You build \bt_name from source in <em>developer mode</em>. | |
44 | ||
45 | The \bt_name developer mode enables more \ref api-fund-pre-post | |
46 | "precondition and postcondition" assertions to detect | |
47 | programming errors. | |
48 | ||
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. | |
52 | ||
53 | To build \bt_name from source in developer mode and using \em TRACE | |
54 | as the minimal logging level: | |
55 | ||
56 | <ol> | |
57 | <li> | |
58 | <a href="https://babeltrace.org/#bt2-get">Download the | |
59 | \bt_name tarball</a> and extract it. | |
60 | ||
61 | See the project's | |
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. | |
64 | <li> | |
65 | Configure the build in developer mode and with the \em TRACE | |
66 | minimal logging level: | |
67 | ||
68 | @code{.unparsed} | |
69 | $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure | |
70 | @endcode | |
71 | <li> | |
72 | Build and install the project: | |
73 | ||
74 | @code{.unparsed} | |
75 | $ make | |
76 | # make install | |
77 | @endcode | |
78 | </ol> | |
79 | ||
80 | \bt_name developer mode build configuration command line examples: | |
81 | ||
82 | @code{.unparsed} | |
83 | $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure \ | |
84 | --enable-python-bindings --enable-python-plugins | |
85 | @endcode | |
86 | ||
87 | @code{.unparsed} | |
88 | $ BABELTRACE_DEV_MODE=1 BABELTRACE_MINIMAL_LOG_LEVEL=TRACE ./configure \ | |
89 | --prefix="$PWD/install" --disable-man-pages --disable-debug-info | |
90 | @endcode | |
91 | ||
92 | @note | |
93 | @parblock | |
94 | The development build creates a libbabeltrace2 library which is | |
95 | slower to execute than a production (default) build. | |
96 | ||
97 | We believe that, during the development process, a less efficient, | |
98 | but more strict library is more desirable than the opposite. | |
99 | @endparblock | |
100 | ||
101 | @page guide-comp-link-plugin-so Compile and link a Babeltrace 2 shared object plugin | |
102 | ||
103 | To compile and link a \bt_name shared object plugin: | |
104 | ||
105 | <ol> | |
106 | <li> | |
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> | |
109 | and | |
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: | |
113 | ||
114 | @code{.unparsed} | |
115 | $ cc my-plugin.c analysis.c -fPIC -c $(pkg-config --cflags babeltrace2) | |
116 | @endcode | |
117 | </li> | |
118 | ||
119 | <li> | |
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: | |
123 | ||
124 | @code{.unparsed} | |
125 | $ ld my-plugin.o analysis.o -o my-plugin.so -shared $(pkg-config --libs babeltrace2) | |
126 | @endcode | |
127 | </li> | |
128 | </ol> | |
129 | ||
130 | @note | |
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. | |
133 | ||
134 | @page guide-comp-link-app Compile and link an application which uses libbabeltrace2 | |
135 | ||
136 | To compile and link an application which uses libbabeltrace2: | |
137 | ||
138 | <ol> | |
139 | <li> | |
140 | Compile your C/C++ files as usual. | |
141 | </li> | |
142 | ||
143 | <li> | |
144 | Link the resulting object files with the \bt_name library: | |
145 | ||
146 | @code{.unparsed} | |
147 | $ ld my-app.o analysis.o -o my-app $(pkg-config --libs babeltrace2) | |
148 | @endcode | |
149 | </li> | |
150 | </ol> | |
151 | ||
152 | @if meow | |
153 | ||
154 | @page guide-create-graph Create a graph from existing component classes and run it | |
155 | ||
156 | TODO! | |
157 | ||
158 | @page guide-write-min-src-comp-cls Write a minimal source component class | |
159 | ||
160 | TODO! | |
161 | ||
162 | @page guide-write-min-flt-comp-cls Write a minimal filter component class | |
163 | ||
164 | TODO! | |
165 | ||
166 | @page guide-write-min-sink-comp-cls Write a minimal sink component class | |
167 | ||
168 | TODO! | |
169 | ||
170 | @page guide-write-simple-sink-comp-cls Write a simple sink component class | |
171 | ||
172 | TODO! | |
173 | ||
174 | @page guide-create-plugin Create a Babeltrace 2 plugin | |
175 | ||
176 | TODO! | |
177 | ||
178 | @page guide-write-full-src-comp-cls Write a complete source component class | |
179 | ||
180 | TODO! | |
181 | ||
182 | @page guide-write-full-flt-comp-cls Write a complete filter component class | |
183 | ||
184 | TODO! | |
185 | ||
186 | @page guide-write-full-sink-comp-cls Write a complete sink component class | |
187 | ||
188 | TODO! | |
189 | ||
190 | @page guide-query Query an object from a component class | |
191 | ||
192 | TODO! | |
193 | ||
194 | @page guide-seek-msg-iter Make a message iterator seek | |
195 | ||
196 | TODO! | |
197 | ||
198 | @page guide-intr-graph Interrupt a running graph | |
199 | ||
200 | TODO! | |
201 | ||
202 | @page guide-intr-query Interrupt a query operation | |
203 | ||
204 | TODO! | |
205 | ||
206 | @page guide-graph-listeners Use graph listeners to react to topology events | |
207 | ||
208 | TODO! | |
209 | ||
210 | @endif | |
211 | */ |