doc/api/libbabeltrace2/dox/guides.dox

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