Commit 803ce6bf authored by Benjamin Otte's avatar Benjamin Otte

GST_DEBUG reorganization containing loads of stuff:

Original commit message from CVS:
GST_DEBUG reorganization
This is a big diff (ca 450k), containing loads of stuff:
- gstinfo.[ch] complete rewrite
- changing of all GST_DEBUG messages to reflect that change
- reorganization of subsystem disabling
- addition of gstconfig.h.in so we can track the disablings
- <gst/gst.h> does not include <unistd.h> and <config.h> anymore
- documentation updated for gstinfo stuff (build the docs yourself to know what changed)
- bugfixes for making of the docs (files from CVS are not deleted anymore
- testsuite for debugging changes in testsuite/debug

expect breakage
parent 30438fd4
common @ 2a3efdc2
Subproject commit 4e379694ae9ff9843d65cf08928642eea44abdf8
Subproject commit 2a3efdc282fb1ecfd2720dea40523b3441f10fed
......@@ -255,8 +255,6 @@ AC_HELP_STRING([--enable-plugin-builddir],[allow tests/demos to use non-installe
esac],
[PLUGINS_USE_BUILDDIR=no]) dnl Default value
GST_DEBUGINFO
AC_ARG_ENABLE(profiling,
AC_HELP_STRING([--enable-profiling],[adds -pg to compiler commandline, for profiling]),
[case "${enableval}" in
......@@ -327,6 +325,18 @@ AM_CONDITIONAL(BUILD_EXAMPLES, test "x$BUILD_EXAMPLES" = "xyes")
dnl Next, check for the optional components:
dnl ========================================
dnl debugging stuff
AC_ARG_ENABLE(debug,
AC_HELP_STRING([--disable-debug],[disable addition of -g debugging info]),
[case "${enableval}" in
yes) USE_DEBUG=yes ;;
no) USE_DEBUG=no ;;
*) AC_MSG_ERROR(bad value ${enableval} for --enable-debug) ;;
esac],
[USE_DEBUG=yes]) dnl Default value
translit(dnm, m, l) AM_CONDITIONAL(GST_DISABLE_GST_DEBUG, true)
GST_SUBSYSTEM_DISABLE(GST_DEBUG,[debugging subsystem])
translit(dnm, m, l) AM_CONDITIONAL(GST_DISABLE_LOADSAVE, true)
GST_SUBSYSTEM_DISABLE(LOADSAVE,[pipeline XML load/save])
translit(dnm, m, l) AM_CONDITIONAL(GST_DISABLE_TYPEFIND, true)
......@@ -351,8 +361,6 @@ GST_SUBSYSTEM_DISABLE(PLUGIN,[plugin])
translit(dnm, m, l) AM_CONDITIONAL(GST_DISABLE_URI, true)
GST_SUBSYSTEM_DISABLE(URI,[uri handlers])
GST_EXT_CFLAGS="$GST_EXT_CFLAGS $GST_SUBSYSTEM_DISABLE_DEFINES"
dnl ################################################
dnl # Set defines according to variables set above #
dnl ################################################
......@@ -514,6 +522,7 @@ AC_OUTPUT(
Makefile
include/Makefile
gst/Makefile
gst/gstconfig.h
gst/gstversion.h
gst/autoplug/Makefile
gst/indexers/Makefile
......@@ -541,6 +550,7 @@ testsuite/bytestream/Makefile
testsuite/caps/Makefile
testsuite/cleanup/Makefile
testsuite/clock/Makefile
testsuite/debug/Makefile
testsuite/dynparams/Makefile
testsuite/elements/Makefile
testsuite/indexers/Makefile
......@@ -569,7 +579,6 @@ tools/Makefile
docs/Makefile
docs/faq/Makefile
docs/gst/Makefile
docs/gst/gstreamer.types
docs/libs/Makefile
docs/manual/Makefile
docs/pwg/Makefile
......
......@@ -113,6 +113,7 @@ DOC_STAMPS=scan-build.stamp tmpl-build.stamp sgml-build.stamp html-build.stamp \
SCANOBJ_FILES = \
$(DOC_MODULE).args \
$(DOC_MODULE).hierarchy \
$(DOC_MODULE)-scan.o \
$(DOC_MODULE).signals
if HAVE_GTK_DOC
......@@ -182,12 +183,15 @@ clean-local:
maintainer-clean-local: clean
cd $(srcdir) && rm -rf sgml html $(DOC_MODULE)-decl-list.txt $(DOC_MODULE)-decl.txt
# company: don't delete .sgml and -sections.txt as they're in CVS
# FIXME : thomas added all sgml files and some other things to make
# make distcheck work
distclean-local: clean
rm -rf $(DOC_MODULE)-decl-list.txt
rm -rf $(DOC_MODULE)-*.txt
rm -rf tmpl/*.sgml
rm -rf $(DOC_MODULE)-decl.txt
rm -rf $(DOC_MODULE)-undocumented.txt
rm -rf $(DOC_MODULE)-unused.txt
rm -rf tmpl/*.sgml.bak
rm -f $(DOC_MODULE).hierarchy
rm -f *.stamp || true
......
......@@ -3,23 +3,21 @@
"http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
<!ENTITY Gst SYSTEM "xml/gst.xml">
<!ENTITY GstAutoplug SYSTEM "xml/gstautoplug.xml">
<!ENTITY GstAutoplugFactory SYSTEM "xml/gstautoplugfactory.xml">
<!ENTITY GstAtomic SYSTEM "xml/gstatomic.xml">
<!ENTITY GstBin SYSTEM "xml/gstbin.xml">
<!ENTITY GstConfig SYSTEM "xml/gstconfig.xml">
<!ENTITY GstData SYSTEM "xml/gstdata.xml">
<!ENTITY GstBuffer SYSTEM "xml/gstbuffer.xml">
<!ENTITY GstEvent SYSTEM "xml/gstevent.xml">
<!ENTITY GstBufferPool SYSTEM "xml/gstbufferpool.xml">
<!ENTITY GstBufferPool SYSTEM "xml/gstbuffer.xml">
<!ENTITY GstCpu SYSTEM "xml/gstcpu.xml">
<!ENTITY GstElement SYSTEM "xml/gstelement.xml">
<!ENTITY GstElementFactory SYSTEM "xml/gstelementfactory.xml">
<!ENTITY GstFormat SYSTEM "xml/gstformat.xml">
<!ENTITY GstInfo SYSTEM "xml/gstinfo.xml">
<!ENTITY GstLog SYSTEM "xml/gstlog.xml">
<!ENTITY GstMemChunk SYSTEM "xml/gstmemchunk.xml">
<!ENTITY GstObject SYSTEM "xml/gstobject.xml">
<!ENTITY GstPad SYSTEM "xml/gstpad.xml">
<!ENTITY GstPadTemplate SYSTEM "xml/gstpadtemplate.xml">
<!ENTITY GstParse SYSTEM "xml/gstparse.xml">
<!ENTITY GstProbe SYSTEM "xml/gstprobe.xml">
<!ENTITY GstPipeline SYSTEM "xml/gstpipeline.xml">
......@@ -30,10 +28,9 @@
<!ENTITY GstRegistry SYSTEM "xml/gstregistry.xml">
<!ENTITY GstRegistryPool SYSTEM "xml/gstregistrypool.xml">
<!ENTITY GstScheduler SYSTEM "xml/gstscheduler.xml">
<!ENTITY GstSchedulerFactory SYSTEM "xml/gstschedulerfactory.xml">
<!ENTITY GstTrace SYSTEM "xml/gsttrace.xml">
<!ENTITY GstType SYSTEM "xml/gsttype.xml">
<!ENTITY GstTypeFactory SYSTEM "xml/gsttypefactory.xml">
<!ENTITY GstTypeFactory SYSTEM "xml/gsttype.xml">
<!ENTITY GstCaps SYSTEM "xml/gstcaps.xml">
<!ENTITY GstProps SYSTEM "xml/gstprops.xml">
<!ENTITY GstClock SYSTEM "xml/gstclock.xml">
......@@ -46,7 +43,6 @@
<!ENTITY GstTypeFind SYSTEM "xml/gsttypefind.xml">
-->
<!ENTITY GstIndex SYSTEM "xml/gstindex.xml">
<!ENTITY GstIndexFactory SYSTEM "xml/gstindexfactory.xml">
<!ENTITY cothreads SYSTEM "xml/cothreads.xml">
<!-- if none of the API is documented, these shouldn't go in
......@@ -67,6 +63,8 @@
<!ENTITY GstTee SYSTEM "xml/gsttee.xml">
<!ENTITY gstreamer-tree-index SYSTEM "xml/tree_index.xml">
<!ENTITY hash "#">
]>
<book>
<bookinfo>
......@@ -92,24 +90,20 @@ with some more specialized elements.</para>
&Gst;
&GstAutoplug;
&GstAutoplugFactory;
&GstBin;
&GstBuffer;
&GstBufferPool;
&GstConfig;
&GstCaps;
&GstClock;
&GstCpu;
&GstData;
&GstElement;
&GstElementFactory;
&GstEvent;
&GstFormat;
&GstIndex;
&GstIndexFactory;
&GstInfo;
&GstObject;
&GstPad;
&GstPadTemplate;
&GstParse;
&GstPipeline;
&GstPlugin;
......@@ -122,11 +116,9 @@ with some more specialized elements.</para>
&GstRegistry;
&GstRegistryPool;
&GstScheduler;
&GstSchedulerFactory;
&GstSystemClock;
&GstThread;
&GstType;
&GstTypeFactory;
<!-- no API docs
&GstTypeFind; -->
&GstUri;
......
......@@ -82,41 +82,72 @@ gst_marshal_VOID__VOID
<SECTION>
<FILE>gstinfo</FILE>
<TITLE>GstInfo</TITLE>
gst_get_category_name
gst_info_get_categories
gst_info_set_categories
gst_info_enable_category
gst_info_disable_category
gst_default_info_handler
GST_INFO_ENABLED
GST_STR_NULL
GST_DEBUG_PAD_NAME
GST_FUNCTION
<SUBSECTION>
GstDebugLevel
GST_LEVEL_DEFAULT
gst_debug_level_get_name
GstDebugColorFlags
gst_debug_construct_term_color
GstDebugCategory
GST_CAT_DEFAULT
<SUBSECTION>
GstLogFunction
gst_debug_log
gst_debug_logv
gst_debug_log_default
gst_debug_add_log_function
gst_debug_remove_log_function
gst_debug_remove_log_function_by_data
<SUBSECTION>
gst_debug_set_active
gst_debug_is_active
gst_debug_set_colored
gst_debug_is_colored
gst_debug_set_default_threshold
gst_debug_get_default_threshold
gst_debug_set_threshold_for_name
gst_debug_unset_threshold_for_name
<SUBSECTION>
GST_DEBUG_CATEGORY
GST_DEBUG_CATEGORY_EXTERN
GST_DEBUG_CATEGORY_STATIC
GST_DEBUG_CATEGORY_INIT
gst_debug_category_free
gst_debug_category_set_threshold
gst_debug_category_reset_threshold
gst_debug_category_get_threshold
gst_debug_category_get_name
gst_debug_category_get_color
gst_debug_category_get_description
gst_debug_get_all_categories
<SUBSECTION>
GST_CAT_LEVEL_LOG
GST_INFO
GST_INFO_ELEMENT
gst_debug_get_categories
gst_debug_set_categories
gst_debug_enable_category
gst_debug_disable_category
GST_DEBUG_ENTER
GST_DEBUG_LEAVE
GST_DEBUG
GST_CAT_ERROR_OBJECT
GST_CAT_WARNING_OBJECT
GST_CAT_INFO_OBJECT
GST_CAT_DEBUG_OBJECT
GST_CAT_LOG_OBJECT
GST_CAT_ERROR
GST_CAT_WARNING
GST_CAT_LOG
GST_ERROR_OBJECT
GST_WARNING_OBJECT
GST_INFO_OBJECT
GST_DEBUG_OBJECT
GST_LOG_OBJECT
GST_ERROR
GST_WARNING
GST_CAT_INFO
GST_CAT_DEBUG
GST_LOG
<SUBSECTION>
GST_DEBUG_FUNCPTR
GST_DEBUG_FUNCPTR_NAME
GST_DEBUG_PAD_NAME
GST_DEBUG_THREAD_ARGS
GST_DEBUG_THREAD_FORMAT
GST_DEBUG_ELEMENT
GST_ERROR
GST_ERROR_OBJECT
GstDebugHandler
gst_default_debug_handler
gst_default_error_handler
GstInfoHandler
GstErrorHandler
<SUBSECTION Standard>
gst_debug_print_stack_trace
GST_DEBUG_CHAR_MODE
GST_DEBUG_ENABLED
GST_DEBUG_ENABLE_CATEGORIES
</SECTION>
<SECTION>
......@@ -166,6 +197,23 @@ GST_SCHEDULER_FACTORY_GET_CLASS
GST_SCHEDULER_GET_CLASS
</SECTION>
<SECTION>
<FILE>gstconfig</FILE>
GST_DISABLE_ALLOC_TRACE
GST_DISABLE_AUTOPLUG
GST_DISABLE_ENUMTYPES
GST_DISABLE_GST_DEBUG
GST_DISABLE_INDEX
GST_DISABLE_LOADSAVE
GST_DISABLE_LOADSAVE_REGISTRY
GST_DISABLE_PARSE
GST_DISABLE_PLUGIN
GST_DISABLE_TRACE
GST_DISABLE_TYPEFIND
GST_DISABLE_URI
GST_DISABLE_REGISTRY
</SECTION>
<SECTION>
<FILE>gstschedulerfactory</FILE>
<TITLE>GstSchedulerFactory</TITLE>
......
<!-- ##### SECTION Title ##### -->
GstConfig
<!-- ##### SECTION Short_Description ##### -->
configuration options
<!-- ##### SECTION Long_Description ##### -->
<para>
This describes the configureation options for GStreamer. When building
GStreamer there are a lot of parts (known internally as "subsystems" ) that can
be disabled for various reasons. The most common reasons are speed and size,
which is important because GStreamer is designed to run on embedded systems.
</para>
<para>
If a subsystem is disabled, most of this changes are done in an API compatible
way, so you don't need to adapt your code in most cases. It is never done in an
ABI compatible way though. So if you want to disable a suybsystem, you have to
rebuild all programs depending on GStreamer, too.
</para>
<para>
If a subsystem is disabled in GStreamer, a value is defined in
&lt;gst/gst.h&gt;. You can check this if you do subsystem-specific stuff.
<example>
<title>Doing subsystem specific things</title>
<programlisting>
&hash;ifndef GST_DISABLE_GST_DEBUG
/* do stuff specific to the debugging subsystem */
&hash;endif /* GST_DISABLE_GST_DEBUG */
</programlisting>
</example>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
</para>
<!-- ##### MACRO GST_DISABLE_LOADSAVE_REGISTRY ##### -->
<para>
</para>
<!-- ##### MACRO GST_DISABLE_GST_DEBUG ##### -->
<para>
If this is defined, the <link linkend="gstreamer-gstinfo">debugging subsystem
</link> is disabled and debugging messages are not output.
</para>
<!-- ##### MACRO GST_DISABLE_LOADSAVE ##### -->
<para>
</para>
<!-- ##### MACRO GST_DISABLE_TYPEFIND ##### -->
<para>
</para>
<!-- ##### MACRO GST_DISABLE_AUTOPLUG ##### -->
<para>
</para>
<!-- ##### MACRO GST_DISABLE_PARSE ##### -->
<para>
</para>
<!-- ##### MACRO GST_DISABLE_TRACE ##### -->
<para>
</para>
<!-- ##### MACRO GST_DISABLE_ALLOC_TRACE ##### -->
<para>
</para>
<!-- ##### MACRO GST_DISABLE_REGISTRY ##### -->
<para>
</para>
<!-- ##### MACRO GST_DISABLE_ENUMTYPES ##### -->
<para>
</para>
<!-- ##### MACRO GST_DISABLE_INDEX ##### -->
<para>
</para>
<!-- ##### MACRO GST_DISABLE_PLUGIN ##### -->
<para>
</para>
<!-- ##### MACRO GST_DISABLE_URI ##### -->
<para>
</para>
......@@ -2,315 +2,668 @@
GstInfo
<!-- ##### SECTION Short_Description ##### -->
info/debugging/error handling
debugging subsystem
<!-- ##### SECTION Long_Description ##### -->
<para>
gstinfo.c contains a number of debuggins subsystems.
This file describes the debugging subsystem. The debugging subsystem works
only after GStreamer was initilized - for example by calling #gst_init.
</para>
<para>The INFO subsystem is used to provide informative printouts to
application and plugin developers. These messages can be enabled and
disabled via a category system, which is a bitmask enabling you to turn
on and off any subset of categories.</para>
<para>
The debugging subsystem is used to send informational strings to the debugging
developer. Each messages has some properties attached to it. These properties
are the debugging category, the severity (called "level" here) and an obtional
#GObject it belongs to. Each of these messages is sent to all registered
debugging handlers, which then handle the messages. GStreamer attaches a
default handler on startup, which outputs requested messages to stderr.
</para>
<para>
Messages are output by using shortcut macros like #GST_DEBUG,
#GST_CAT_ERROR_OBJECT or similar. These all expand to calling #gst_debug_log
with the right parameters.
The only thing a developer will probably want to do is define his own
categories. This is easily done with 3 lines. At the top of your code, declare
the variables and set the default category.
<informalexample>
<programlisting>
GST_DEBUG_CATEGORY (my_category); /* define category */
&hash;define GST_CAT_DEFAULT my_category /* set as default */
</programlisting>
</informalexample>
After that you only need to initialize the category.
<informalexample>
<programlisting>
GST_DEBUG_CATEGORY_INIT (my_category, "my category", 0, "This is my very own");
</programlisting>
</informalexample>
Initialization must be done before the category is used first. Plugins do this
in their plugin_init function, libraries and applications should do that
during their initialization.
</para>
<para>The DEBUG subsystem is similar, but is intended for core developers
and those writing more complex pipelines or filters. It uses the same
category system, but must be enabled at configure time else it's not
compiled into the library. autogen.sh automatically enables the DEBUG
subsystem.
<para>
The whole debugging subsystem can be disabled at build time with passing the
--disable-gst-debug switch to configure. If this is done, every function, macro
and even structs described in this file evaluate to default values or nothing
at all. So don't take addresses of these functions or use other tricks.
If you must do that for some reason, there is still an option. If the debugging
subsystem was compiled out, #GST_DISABLE_GST_DEBUG is defined in &lt;gst/gst.h&gt;,
so you can check that before doing your trick.
Disabling the debugging subsystem will give you a slight (read: unnoticable)
speed increase and will reduce the size of your compiled code. The GStreamer
library itself becomes around 10% smaller.
</para>
<para>The ERROR subsystem doesn't use categories, but will print out a
more verbose message, and attempt to print out a stack trace of the error
before aborting the application.
<para>
Please note that there are naming conventions for the names of debugging
categories. These are explained at GST_DEBUG_CATEGORY_INIT().
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
<link linkend="gstreamer-gstconfig">configuration</link>,
<link linkend="gstreamer-gst">initialization</link> for command line parameters
and environment variables that affect the debugging output.
</para>
<!-- ##### MACRO GST_STR_NULL ##### -->
<para>
Macro to use when a string must not be NULL, but may be NULL. If the string is
NULL, "(NULL)" is printed instead.
In GStreamer printf string arguments may not be NULL, because on some platforms
(ie Solaris) the libc crashes in that case. This includes debugging strings.
</para>
@str: The string to check.
@Returns: A string that is guaranteed to be not NULL.
<!-- ##### MACRO GST_DEBUG_PAD_NAME ##### -->
<para>
Evaluates to 2 strings, that describe the pad. Often used in debugging
statements.
</para>
<!-- ##### FUNCTION gst_get_category_name ##### -->
@pad: The pad to debug.
<!-- ##### MACRO GST_FUNCTION ##### -->
<para>
This macro should evaluate to the name of the current function and be should
be defined when configuring your project, as it is compiler dependant. If it
is not defined, some default value is used. It is used to provide debugging
output with the function name of the message.
</para>
<!-- ##### ENUM GstDebugLevel ##### -->
<para>
The level defines the importance of a debugging message. The more important a
message is, the greater the probability that the debugging system outputs it.
</para>
@GST_LEVEL_NONE: No debugging level specified or desired. Used to deactivate
debugging output.
@GST_LEVEL_ERROR: Error messages are to be used only when an error occured
that stops the application from keeping working correctly.
An examples is gst_element_error, which outputs a message with this priority.
It does not mean that the application is terminating as with g_errror.
@GST_LEVEL_WARNING: Warning messages are to inform about abnormal behaviour
that could lead to problems or weird behaviour later on. An example of this
would be clocking issues ("your computer is pretty slow") or broken input
data ("Can't synchronize to stream.")
@GST_LEVEL_INFO: Informational messages should be used to keep the developer
updated about what is happening.
Examples where this should be used are when a typefind function has
successfully determined the type of the stream or when an mp3 plugin detects
the format to be used. ("This file has mono sound.")
@GST_LEVEL_DEBUG: Debugging messages should be used when something common
happens that is not the expected default behavior.
An example would be notifications about state changes or receiving/sending of
events.
@GST_LEVEL_LOG: Log messages are messages that are very common but might be
useful to know. As a rule of thumb a pipeline that is iterating as expected
should never output anzthing else but LOG messages.
Examples for this are referencing/dereferencing of objects or cothread switches.
@GST_LEVEL_COUNT: The number of defined debugging levels.
<!-- ##### MACRO GST_LEVEL_DEFAULT ##### -->
<para>
Defines the default debugging level to be used with GStreamer. It is
normally set to #GST_LEVEL_ERROR so only errors are printed. Developer
builds may chose to override that though.
You can use this as an argument to gst_debug_set_default_threshold() to
reset the debugging output to default behaviour.
</para>
@category:
@Returns:
<!-- ##### FUNCTION gst_info_get_categories ##### -->
<!-- ##### FUNCTION gst_debug_level_get_name ##### -->