From: Mark Cave-Ayland Date: Sat, 31 May 2008 10:35:04 +0000 (+0000) Subject: Provide a new text file called DEBUG explaining how to use the new debug system. X-Git-Tag: 1.4.0b1~894 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=c49701ca676561dcc16d67a10141ac21fa3781b7;p=postgis 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 1c8fdad34..3f354b735 100644 --- 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 index 000000000..581af6c33 --- /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 +