gstreamer/docs/manual/appendix-debugging.xml

153 lines
4.8 KiB
XML
Raw Normal View History

<chapter id="chapter-debugging">
<title>Debugging</title>
<para>
GStreamer has an extensive set of debugging tools for
plugin developers.
</para>
<sect1 id="section-debugging-command-line">
<title>Command line options</title>
<para>
Applications using the GStreamer libraries accept the following set
of command line argruments that help in debugging.
</para>
<para>
<itemizedlist>
<listitem>
<para>
<option>--gst-debug-help</option>
Print available debug categories and exit
</para>
</listitem>
<listitem>
<para>
<option>--gst-debug-level=<replaceable>LEVEL</replaceable></option>
Sets the default debug level from 0 (no output) to 5 (everything)
</para>
</listitem>
<listitem>
<para>
<option>--gst-debug=<replaceable>LIST</replaceable></option>
Comma-separated list of category_name:level pairs to set specific
levels for the individual categories.
Example: GST_AUTOPLUG:5,GST_ELEMENT_*:3
</para>
</listitem>
<listitem>
<para>
<option>--gst-debug-no-color</option>
Disable color debugging output
</para>
</listitem>
<listitem>
<para>
<option>--gst-debug-disable</option>
Disable debugging
</para>
</listitem>
<listitem>
<para>
<option>--gst-plugin-spew</option>
Enable printout of errors while loading GStreamer plugins.
</para>
</listitem>
</itemizedlist>
</para>
</sect1>
<sect1 id="section-debugging-adding">
<title>Adding debugging to a plugin</title>
<para>
Plugins can define their own categories for the debugging system.
Three things need to happen:
<itemizedlist>
<listitem>
<para>
The debugging variable needs to be defined somewhere.
If you only have one source file, you can Use GST_DEBUG_CATEGORY_STATIC to
define a static debug category variable.
</para>
<para>
If you have multiple source files, you should define the variable using
GST_DEBUG_CATEGORY in the source file where you're initializing the debug
category. The other source files should use GST_DEBUG_CATEGORY_EXTERN to
declare the debug category variable, possibly by including a common header
that has this statement.
</para>
</listitem>
<listitem>
<para>
The debugging category needs to be initialized. This is done through
GST_DEBUG_CATEGORY_INIT.
If you're using a global debugging category for the complete plugin,
you can call this in the
plugin's <function>plugin_init</function>.
If the debug category is only used for one of the elements, you can call it
from the element's <function>_class_init</function> function.
</para>
</listitem>
<listitem>
<para>
You should also define a default category to be used for debugging. This is
done by defining GST_CAT_DEFAULT for the source files where you're using
debug macros.
</para>
</listitem>
</itemizedlist>
</para>
<para>
Elements can then log debugging information using the set of macros. There
are five levels of debugging information:
<orderedlist>
<listitem>
<para>ERROR for fatal errors (for example, internal errors)</para>
</listitem>
<listitem>
<para>WARNING for warnings</para>
</listitem>
<listitem>
<para>INFO for normal information</para>
</listitem>
<listitem>
<para>DEBUG for debug information (for example, device parameters)</para>
</listitem>
<listitem>
<para>LOG for regular operation information (for example, chain handlers)</para>
</listitem>
</orderedlist>
</para>
<para>
For each of these levels, there are four macros to log debugging information.
Taking the LOG level as an example, there is
<itemizedlist>
<listitem>
<para>
GST_CAT_LOG_OBJECT logs debug information in the given GstCategory
and for the given GstObject
</para>
</listitem>
<listitem>
<para>
GST_CAT_LOG logs debug information in the given GstCategory
but without a GstObject (this is useful for libraries, for example)
</para>
</listitem>
<listitem>
<para>
GST_LOG_OBJECT logs debug information in the default GST_CAT_DEFAULT
category (as defined somewhere in the source), for the given GstObject
</para>
</listitem>
<listitem>
<para>
GST_LOG logs debug information in the default GST_CAT_DEFAULT
category, without a GstObject
</para>
</listitem>
</itemizedlist>
</para>
</sect1>
</chapter>