Provide a new text file called DEBUG explaining how to use the new debug system.

git-svn-id: http://svn.osgeo.org/postgis/trunk@2798 b70326c6-7e19-0410-871a-916f4a2858ee

diff --git a/configure.in b/configure.in
index 1c8fdad34db4c9353decba7570eedc2d3e7d2ef0..3f354b7352c0d6ae7ed4d861a908e20918156e39 100644 (file)
--- a/configure.in
+++ b/configure.in
@@ -303,15 +303,7 @@ LIBS="$LIBS_SAVE"
 dnl
 dnl Allow the user to enable debugging with --enable-debug
 dnl
-dnl Currently 5 levels are defined (each increasing in complexity):
-dnl   - 1: Reserved 
-dnl   - 2: Output function names upon entry (where defined) 
-dnl   - 3: Normal function debugging 
-dnl   - 4: Verbose function debugging 
-dnl   - 5: Memory allocation/deallocation calls
-dnl
-dnl All levels include the output of all preceding levels. We default to level 4, but the
-dnl developer is encouraged to manually alter postgis_config.h as required.
+dnl Currently we default to debug level 4. See DEBUG for more information. 
 dnl
 
 AC_ARG_ENABLE([debug], AC_HELP_STRING([--enable-debug], [Enable verbose debugging messages]), 

diff --git a/lwgeom/DEBUG b/lwgeom/DEBUG
new file mode 100644 (file)
index 0000000..581af6c
--- /dev/null
+++ b/lwgeom/DEBUG
@@ -0,0 +1,91 @@
+PostGIS debugging information 
+=============================
+
+Written by Mark Cave-Ayland
+2008-05-31
+
+
+Description
+===========
+
+This document attempts to describe the PostGIS debugging system for new developers to
+the project. Previously, all debugging was either performed by uncommenting various
+elog()/lwnotice() statements within the code areas of interest, or using an
+existing #define to enable debugging within each individual file.
+
+The net result of this was that debugging could be quite a painful process, involving
+searching through each file as necessary and uncommenting the various options. There
+were also issues regarding levels of verbosity; some sections of code define multiple
+verbosity levels across many different files, and so getting the information required
+could be quite frustrating.
+
+To this end, a new debugging infrastructure has been added to PostGIS to help make
+life easier for developers. It is now possible to include debugging information using
+a set of new macros for the purpose. Each macro also allows a debug level to be  
+specified, allowing output to be generated at the required verbosity level for the
+task in hand.
+
+Debugging is accomplished using four new macros:
+
+       LWDEBUG(level, "message")
+               - If the current debug level >= level, emit message
+
+       LWDEBUGF(level, "format message", ...)
+               - If the current debug level >= level, emit formatted message
+               (this allows placeholders and extra arguments in exactly the
+               same way as vasprintf())
+
+       POSTGIS_DEBUG(level, "message")
+               - If the current debug level >= level, emit message
+
+       POSTGIS_DEBUGF(level, "format message", ...)
+               - If the current debug level >= level, emit formatted message
+               (this allows placeholders and extra arguments in exactly the
+               same way as vasprintf())
+
+The two LWDEBUG macros are designed for use within liblwgeom; i.e. geometry routines
+that may not necessarily be used from PostgreSQL, and make use of the lwnotice() call.
+Similarly, the POSTGIS_DEBUG macros are designed for code that can *only* be called
+from within PostgreSQL, i.e. it calls ereport() directly. The trick is, of course,
+to distinguish between the two. Generally anything within a function declared as
+returning type Datum should use the POSTGIS_DEBUG macros, as well as code that can
+only be called from these functions. Similarly, any functions that do not take
+PostgreSQL-specific datatypes should use the LWDEBUG functions.
+
+Note that the debugging macros automatically prefix the current filename, function name
+and line number to any debugging messages. As well as allowing debug messages to be
+shorter, it also makes following program flow much easier.
+
+ 
+Usage
+=====
+
+The current debug level is set by the POSTGIS_DEBUG_LEVEL #define in postgis_config.h. 
+By default, configure sets POSTGIS_DEBUG_LEVEL to 0 which disables all debugging output.
+If debugging output is required, it is necessary to either redefine POSTGIS_DEBUG_LEVEL
+to the required level (and rebuild the shared library), or re-run configure with the
+--enable-debug option and then rebuild the shared library (currently configure defaults
+to level 4).
+
+A rebuild of the library is required since the output of the debug macros is conditional;
+if POSTGIS_DEBUG_LEVEL is set to 0 then instead of providing debug output, the macros
+simply evaluate to (void)0 which can be optimised away by the compiler. Hence adding
+debugging statements during development will have negligible performance impact during
+execution when debugging is disabled.
+
+
+Verbosity levels
+================
+
+The following verbosity levels have been defined in the initial implementation; obviously
+these may need to change as experience dictates. By specifying a debug level, output for
+all levels up to and including the current debug level is generated. It should also be
+obvious that as the debug level is increased, more complex output is generated.
+
+0 - All debugging output is disable
+1 - Reserved
+2 - Function entry; for simply announcing when a function has been entered
+3 - Normal function debug; output any information of interest to the developer
+4 - Verbose function debug; output lots of useful detail
+5 - Memory allocation; output all uses of alloc/free within the code
+