| 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 | */ |