docs/gst/running.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
   3                "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
   4 <!ENTITY % version-entities SYSTEM "version.entities">
   5 %version-entities;
   6 <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
   7 ]>
   8 <refentry id="gst-running" revision="08 Oct 2005">
   9 <refmeta>
  10 <refentrytitle>Running GStreamer Applications</refentrytitle>
  11 <manvolnum>3</manvolnum>
  12 <refmiscinfo>GStreamer Core</refmiscinfo>
  13 </refmeta>
  14
  15 <refnamediv>
  16 <refname>Running GStreamer Applications</refname>
  17 <refpurpose>
  18 How to run and debug your GStreamer application
  19 </refpurpose>
  20 </refnamediv>
  21
  22 <refsect1>
  23 <title>Running and debugging GStreamer Applications</title>
  24
  25 <refsect2>
  26 <title>Environment variables</title>
  27
  28 <para>
  29 GStreamer inspects a few of environment variables in addition to standard
  30 variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>.
  31 </para>
  32
  33 <formalpara id="GST_PLUGIN_SYSTEM_PATH">
  34   <title><envar>GST_PLUGIN_SYSTEM_PATH</envar></title>
  35
  36   <para>
  37
  38 This environment variable can be set to a colon-separated list of paths.
  39 If this variable is not set, GStreamer will fill in this list for you
  40 with
  41 <itemizedlist>
  42   <listitem>
  43     <para>
  44 plug-ins in the user's home directory.  These are stored in a directory called
  45 <filename>plugins</filename> inside the
  46 <filename>.gstreamer-&GST_API_VERSION;</filename> directory in the user's
  47 home directory.
  48     </para>
  49   </listitem>
  50   <listitem>
  51     <para>
  52 plug-ins installed system-wide.  On this system, they are stored in
  53 <filename>&GST_PLUGINS_DIR;</filename>.
  54     </para>
  55
  56 </listitem>
  57 </itemizedlist>
  58    </para>
  59
  60     <para>
  61 GStreamer will scan these paths for GStreamer plug-ins.  These plug-ins will
  62 be loaded after the plug-ins in the GST_PLUGIN_PATH variable below.
  63
  64 The paths are scanned in the given order.  This allows a user to override
  65 system-installed plug-ins with his own versions.
  66    </para>
  67
  68     <para>
  69 Setting this variable to an empty string will cause GStreamer not to scan any
  70 system paths at all for plug-ins.  This can be useful if you're running
  71 uninstalled (for development purposes) or while running testsuites.
  72    </para>
  73
  74 </formalpara>
  75
  76 <formalpara id="GST_PLUGIN_PATH">
  77   <title><envar>GST_PLUGIN_PATH</envar></title>
  78
  79   <para>
  80 This environment variable can be set to a colon-separated list of paths.
  81 GStreamer will scan these paths for GStreamer plug-ins.  These plug-ins will
  82 be loaded in addition to, and before, the plug-ins in the system paths.
  83   </para>
  84
  85 </formalpara>
  86
  87 <formalpara id="GST_DEBUG">
  88   <title><envar>GST_DEBUG</envar></title>
  89
  90   <para>
  91 If GStreamer has been configured with <option>--enable-gst-debug=yes</option>,
  92 this variable can be set to a list of debug options, which cause GStreamer
  93 to print out different types of debugging information to stderr.
  94   </para>
  95   <para>
  96 The variable takes a comma-separated list of "category_name:level" pairs
  97 to set specific levels for the individual categories.
  98 The level value ranges from 0 (nothing) to 9 (MEMDUMP).
  99     <variablelist>
 100
 101       <varlistentry>
 102         <term>1 - <option>ERROR</option></term>
 103         <listitem>
 104 <para>
 105 Logs all fatal errors.  These are errors that do not allow the core or elements
 106 to perform the requested action.  The application can still recover if
 107 programmed to handle the conditions that triggered the error.
 108 </para>
 109         </listitem>
 110       </varlistentry>
 111
 112       <varlistentry>
 113         <term>2 - <option>WARNING</option></term>
 114         <listitem>
 115 <para>
 116 Logs all warnings.  Typically these are non-fatal, but user-visible problems
 117 are expected to happen.
 118 </para>
 119         </listitem>
 120       </varlistentry>
 121
 122       <varlistentry>
 123         <term>3 - <option>FIXME</option></term>
 124         <listitem>
 125 <para>
 126 Logs all fixme messages. Fixme messages are messages that indicate that something
 127 in the executed code path is not fully implemented or handled yet.  The purpose
 128 of this message is to make it easier to spot incomplete/unfinished pieces of
 129 code when reading the debug log.
 130 </para>
 131         </listitem>
 132       </varlistentry>
 133
 134       <varlistentry>
 135         <term>4 - <option>INFO</option></term>
 136         <listitem>
 137 <para>
 138 Logs all informational messages.  These are typically used for events in
 139 the system that only happen once, or are important and rare enough to be
 140 logged at this level.
 141 </para>
 142         </listitem>
 143       </varlistentry>
 144
 145       <varlistentry>
 146         <term>5 - <option>DEBUG</option></term>
 147         <listitem>
 148 <para>
 149 Logs all debug messages.  These are general debug messages for events
 150 that happen only a limited number of times during an object's lifetime;
 151 these include setup, teardown, change of parameters, ...
 152 </para>
 153         </listitem>
 154       </varlistentry>
 155
 156       <varlistentry>
 157         <term>6 - <option>LOG</option></term>
 158         <listitem>
 159 <para>
 160 Logs all log messages.  These are messages for events
 161 that happen repeatedly during an object's lifetime;
 162 these include streaming and steady-state conditions.
 163 </para>
 164         </listitem>
 165       </varlistentry>
 166
 167       <varlistentry>
 168         <term>7 - <option>TRACE</option></term>
 169         <listitem>
 170 <para>
 171 Logs all trace messages.  These messages for events
 172 that happen repeatedly during an object's lifetime such as the
 173 ref/unref cycles.
 174 </para>
 175         </listitem>
 176       </varlistentry>
 177
 178       <varlistentry>
 179         <term>9 - <option>MEMDUMP</option></term>
 180         <listitem>
 181 <para>
 182 Log all memory dump messages. Memory dump messages are used to log
 183 (small) chunks of data as memory dumps in the log. They will be displayed
 184 as hexdump with ASCII characters.
 185 </para>
 186         </listitem>
 187       </varlistentry>
 188     </variablelist>
 189
 190  The category_name can contain "<option>*"</option> as a wildcard.
 191   </para>
 192
 193   <para>
 194 For example, setting <envar>GST_DEBUG</envar> to
 195 <option>GST_AUTOPLUG:6,GST_ELEMENT_*:4</option>, will cause the
 196 <option>GST_AUTOPLUG</option> category to be logged at full
 197 <option>LOG</option> level, while all categories starting with
 198 <option>GST_ELEMENT_</option> will be logged at <option>INFO</option> level.
 199   </para>
 200
 201   <para>
 202 To get all possible debug output, set
 203 <envar>GST_DEBUG</envar>
 204 to <option>*:9</option>
 205   </para>
 206
 207 </formalpara>
 208
 209 <formalpara id="GST_DEBUG_NO_COLOR">
 210   <title><envar>GST_DEBUG_NO_COLOR</envar></title>
 211
 212   <para>
 213 Set this environment variable to any value ("1" typically) to switch off
 214 colouring in GST_DEBUG output. This has the same effect as specifying the
 215 <option>--gst-debug-no-color</option> command line option to well-behaved
 216 GStreamer applications (ie. those that pass command-line options correctly to
 217 GStreamer).
 218 This is particularly useful to reduce the size of debug output and also allows
 219 for the output to be compressed much better than with colours turned on.
 220   </para>
 221
 222 </formalpara>
 223
 224 <formalpara id="GST_DEBUG_OPTIONS">
 225   <title><envar>GST_DEBUG_OPTIONS</envar></title>
 226
 227   <para>
 228 This environment variable can be used to tweak the behaviour of the debugging
 229 system. Currently the only options supported are "pretty-tags" and "full-tags".
 230 In "pretty-tags" mode (the default), taglists in the debug log will be
 231 serialized so that only the first few and last few bytes of a buffer-type tag
 232 will be serialized into the log, to avoid dumping hundreds of lines of useless
 233 output into the log in case of large image tags and the like.
 234   </para>
 235
 236 </formalpara>
 237
 238 <formalpara id="GST_DEBUG_DUMP_DOT_DIR">
 239   <title><envar>GST_DEBUG_DUMP_DOT_DIR</envar></title>
 240
 241   <para>
 242 Set this environment variable to a path to turn on all
 243 #GST_DEBUG_BIN_TO_DOT_FILE or #GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS calls
 244 and have the dot files in that location.
 245   </para>
 246
 247 </formalpara>
 248
 249 <formalpara id="GST_REGISTRY_FORK">
 250   <title><envar>GST_REGISTRY_FORK</envar></title>
 251
 252   <para>
 253 Set this environment variable to "no" to prevent GStreamer from forking on
 254 startup in order to update the plugin registry. This is useful for debugging
 255 purposes, but should not be used under normal circumstances, since it means
 256 that plugins may be loaded into memory even if they are not needed by the
 257 application.
 258   </para>
 259
 260 </formalpara>
 261
 262 <formalpara id="GST_REGISTRY_UPDATE">
 263   <title><envar>GST_REGISTRY_UPDATE</envar></title>
 264
 265   <para>
 266 Set this environment variable to "no" to prevent GStreamer from updating the
 267 plugin registry. This is useful for embedded device which is not updating the
 268 plugins frequently, it will save time when doing gst_init().
 269   </para>
 270
 271 </formalpara>
 272
 273 <formalpara id="GST_TRACE">
 274   <title><envar>GST_TRACE</envar></title>
 275
 276   <para>
 277     Enable memory allocation tracing. Most GStreamer objects have support for
 278     tracing the number of unfreed objects and their memory pointers.
 279   </para>
 280   <para>
 281 The variable takes a comma-separated list of tracing options to enable.
 282     <variablelist>
 283
 284       <varlistentry>
 285         <term>live</term>
 286         <listitem>
 287 <para>
 288   Counts all live objects and dumps an overview of the number of unfreed
 289   objects at program exit.
 290 </para>
 291         </listitem>
 292       </varlistentry>
 293
 294       <varlistentry>
 295         <term>mem-live</term>
 296         <listitem>
 297 <para>
 298   Keep track of the unfreed memory pointers and dump an overview of all unfreed
 299   memory at program exit. Together with a level 9 debug log this can be used to
 300   follow the lifecycle of leaked objects in order to track down where they are
 301   leaked.
 302 </para>
 303         </listitem>
 304       </varlistentry>
 305     </variablelist>
 306
 307  Use <option>all</option> to enable all tracing flags.
 308   </para>
 309 </formalpara>
 310
 311 <formalpara id="ORC_CODE">
 312   <title><envar>ORC_CODE</envar></title>
 313
 314   <para>
 315 Useful Orc environment variable. Set ORC_CODE=debug to enable debuggers
 316 such as gdb to create useful backtraces from Orc-generated code.  Set
 317 ORC_CODE=backup or ORC_CODE=emulate if you suspect Orc's SIMD code
 318 generator is producing incorrect code (Quite a few important
 319 GStreamer plugins like videotestsrc, audioconvert or audioresample use Orc).
 320 One can also combine flags like ORC_CODE=backup,debug.
 321   </para>
 322
 323 </formalpara>
 324
 325 <formalpara id="G_DEBUG">
 326   <title><envar>G_DEBUG</envar></title>
 327
 328   <para>
 329 Useful GLib environment variable. Set G_DEBUG=fatal_warnings to make
 330 GStreamer programs abort when a critical warning such as an assertion failure
 331 occurs. This is useful if you want to find out which part of the code caused
 332 that warning to be triggered and under what circumstances. Simply set G_DEBUG
 333 as mentioned above and run the program in gdb (or let it core dump). Then get
 334 a stack trace in the usual way.
 335   </para>
 336
 337 </formalpara>
 338
 339 <formalpara id="G_SLICE">
 340   <title><envar>G_SLICE</envar></title>
 341
 342   <para>
 343 Useful GLib environment variable. Set G_SLICE=always-malloc when running
 344 GStreamer programs in valgrind, or debugging memory leaks with other tools.
 345 See the GLib API reference for more details.
 346   </para>
 347
 348 </formalpara>
 349
 350 </refsect2>
 351
 352 </refsect1>
 353
 354 </refentry>