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 5 (LOG).
  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>INFO</option></term>
 124         <listitem>
 125 <para>
 126 Logs all informational messages.  These are typically used for events in
 127 the system that only happen once, or are important and rare enough to be
 128 logged at this level.
 129 </para>
 130         </listitem>
 131       </varlistentry>
 132
 133       <varlistentry>
 134         <term>4 - <option>DEBUG</option></term>
 135         <listitem>
 136 <para>
 137 Logs all debug messages.  These are general debug messages for events
 138 that happen only a limited number of times during an object's lifetime;
 139 these include setup, teardown, change of parameters, ...
 140 </para>
 141         </listitem>
 142       </varlistentry>
 143
 144       <varlistentry>
 145         <term>5 - <option>LOG</option></term>
 146         <listitem>
 147 <para>
 148 Logs all log messages.  These are messages for events
 149 that happen repeatedly during an object's lifetime;
 150 these include streaming and steady-state conditions.
 151 </para>
 152         </listitem>
 153       </varlistentry>
 154     </variablelist>
 155
 156  The category_name can contain "<option>*"</option> as a wildcard.
 157   </para>
 158
 159   <para>
 160 For example, setting <envar>GST_DEBUG</envar> to
 161 <option>GST_AUTOPLUG:5,GST_ELEMENT_*:3</option>, will cause the
 162 <option>GST_AUTOPLUG</option> category to be logged at full
 163 <option>LOG</option> level, while all categories starting with
 164 <option>GST_ELEMENT_</option> will be logged at <option>INFO</option> level.
 165   </para>
 166
 167   <para>
 168 To get all possible debug output, set
 169 <envar>GST_DEBUG</envar>
 170 to <option>*:5</option>
 171   </para>
 172
 173 </formalpara>
 174
 175 <formalpara id="GST_DEBUG_NO_COLOR">
 176   <title><envar>GST_DEBUG_NO_COLOR</envar></title>
 177
 178   <para>
 179 Set this environment variable to any value ("1" typically) to switch off
 180 colouring in GST_DEBUG output. This has the same effect as specifying the
 181 <option>--gst-debug-no-color</option> command line option to well-behaved
 182 GStreamer applications (ie. those that pass command-line options correctly to
 183 GStreamer).
 184 This is particularly useful to reduce the size of debug output and also allows
 185 for the output to be compressed much better than with colours turned on.
 186   </para>
 187
 188 </formalpara>
 189
 190 <formalpara id="GST_DEBUG_OPTIONS">
 191   <title><envar>GST_DEBUG_OPTIONS</envar></title>
 192
 193   <para>
 194 This environment variable can be used to tweak the behaviour of the debugging
 195 system. Currently the only options supported are "pretty-tags" and "full-tags".
 196 In "pretty-tags" mode (the default), taglists in the debug log will be
 197 serialized so that only the first few and last few bytes of a buffer-type tag
 198 will be serialized into the log, to avoid dumping hundreds of lines of useless
 199 output into the log in case of large image tags and the like.
 200   </para>
 201
 202 </formalpara>
 203
 204 <formalpara id="GST_DEBUG_DUMP_DOT_DIR">
 205   <title><envar>GST_DEBUG_DUMP_DOT_DIR</envar></title>
 206
 207   <para>
 208 Set this environment variable to a path to turn on all
 209 #GST_DEBUG_BIN_TO_DOT_FILE or #GST_DEBUG_BIN_TO_DOT_FILE_WITH_TS calls
 210 and have the dot files in that location.
 211   </para>
 212
 213 </formalpara>
 214
 215 <formalpara id="GST_REGISTRY_FORK">
 216   <title><envar>GST_REGISTRY_FORK</envar></title>
 217
 218   <para>
 219 Set this environment variable to "no" to prevent GStreamer from forking on
 220 startup in order to update the plugin registry. This is useful for debugging
 221 purposes, but should not be used under normal circumstances, since it means
 222 that plugins may be loaded into memory even if they are not needed by the
 223 application.
 224   </para>
 225
 226 </formalpara>
 227
 228 <formalpara id="GST_REGISTRY_UPDATE">
 229   <title><envar>GST_REGISTRY_UPDATE</envar></title>
 230
 231   <para>
 232 Set this environment variable to "no" to prevent GStreamer from updating the
 233 plugin registry. This is useful for embedded device which is not updating the
 234 plugins frequently, it will save time when doing gst_init().
 235   </para>
 236
 237 </formalpara>
 238
 239 <formalpara id="ORC_CODE">
 240   <title><envar>ORC_CODE</envar></title>
 241
 242   <para>
 243 Useful Orc environment variable. Set ORC_CODE=debug to enable debuggers
 244 such as gdb to create useful backtraces from Orc-generated code.  Set
 245 ORC_CODE=backup or ORC_CODE=emulate if you suspect Orc's SIMD code
 246 generator is producing incorrect code (Quite a few important
 247 GStreamer plugins like videotestsrc, audioconvert or audioresample use Orc).
 248 One can also combine flags like ORC_CODE=backup,debug.
 249   </para>
 250
 251 </formalpara>
 252
 253 <formalpara id="G_DEBUG">
 254   <title><envar>G_DEBUG</envar></title>
 255
 256   <para>
 257 Useful GLib environment variable. Set G_DEBUG=fatal_warnings to make
 258 GStreamer programs abort when a critical warning such as an assertion failure
 259 occurs. This is useful if you want to find out which part of the code caused
 260 that warning to be triggered and under what circumstances. Simply set G_DEBUG
 261 as mentioned above and run the program in gdb (or let it core dump). Then get
 262 a stack trace in the usual way.
 263   </para>
 264
 265 </formalpara>
 266
 267 <formalpara id="G_SLICE">
 268   <title><envar>G_SLICE</envar></title>
 269
 270   <para>
 271 Useful GLib environment variable. Set G_SLICE=always-malloc when running
 272 GStreamer programs in valgrind, or debugging memory leaks with other tools.
 273 See the GLib API reference for more details.
 274   </para>
 275
 276 </formalpara>
 277
 278 </refsect2>
 279
 280 </refsect1>
 281
 282 </refentry>