libcwd: The C++ Debugging Support Library - Reference Manual
Author: Carlo Wood
Description: C++ debugging support library with ostream debug output
Keywords: libcwd, debug output, debug facility, debug channel, object orientation, OO, C++, nested debug output, ostream, memory allocation, debugging, source file and line number

Main Page Reference Manual Namespace List Compound List Namespace Members Compound Members File Members

# libcwd/debug.h

Go to the documentation of this file.

    00001 // $Header$
    00002 //
    00003 // Copyright (C) 2000 - 2004, by
    00004 //
    00005 // Carlo Wood, Run on IRC <carlo@alinoe.com>
    00006 // RSA-1024 0x624ACAD5 1997-01-26                    Sign & Encrypt
    00007 // Fingerprint16 = 32 EC A7 B6 AC DB 65 A6  F6 F6 55 DD 1C DC FF 61
    00008 //
    00009 // This file may be distributed under the terms of the Q Public License
    00010 // version 1.0 as appearing in the file LICENSE.QPL included in the
    00011 // packaging of this file.
    00012 //
    00013
    00023 #ifndef CWDEBUG
    00024
    00025 // If you run into this error then you included <libcwd/debug.h> (or any other libcwd header file)
    00026 // while the macro CWDEBUG was not defined.  Doing so would cause the compilation of your
    00027 // application to fail on machines that do not have libcwd installed.  Instead you should use:
    00028 // #include "debug.h"
    00029 // and add a file debug.h to your applications distribution.  Please see the the example-project
    00030 // that comes with the source code of libcwd (or is included in the documentation that comes with
    00031 // the rpm (ie: /usr/doc/libcwd-1.0/example-project) for a description of the content of "debug.h".
    00032 // Note1: CWDEBUG should be defined on the compiler commandline, for example: g++ -DCWDEBUG ...
    00033 #error "You are including <libcwd/debug.h> while CWDEBUG is not defined.  See the comments in this header file for more information."
    00034
    00035 #else // CWDEBUG (normal usage of this file):
    00036
    00037 #ifndef LIBCWD_SYS_H
    00038 #error "You need to #include "sys.h" at the top of every source file (which in turn should #include <libcwd/sys.h>)."
    00039 #endif
    00040
    00041 #if defined(LIBCWD_DEFAULT_DEBUGCHANNELS) && defined(DEBUGCHANNELS)
    00042 // If you run into this error then you included <libcwd/debug.h> (or any other libcwd header file)
    00043 // without defining DEBUGCHANNELS, and later (the moment of this error) you included it with
    00044 // DEBUGCHANNELS defined.
    00045 //
    00046 // The most likely reason for this is that you include <libcwd/debug.h> in one of your headers
    00047 // instead of using #include "debug.h", and then included that header file before including
    00048 // "debug.h" in the .cpp file.
    00049 // End-applications should #include "debug.h" everywhere.  See the the example-project that comes
    00050 // with the source code of libcwd (or is included in the documentation that comes with the rpm
    00051 // (ie: /usr/doc/libcwd-1.0/example-project) for a description of the content of "debug.h".
    00052 // More information for end-application users can be found on
    00053 // http://libcwd.sourceforge.net/reference-manual/preparation.html
    00054 //
    00055 // Third-party libraries should never include <libcwd/debug.h> but also not "debug.h".  They
    00056 // should include <libcwd/libraries_debug.h> (and not use Dout et al in their headers).  If you
    00057 // are using a library that did include <libcwd/debug.h> then please report this bug the author
    00058 // of that library.  You can workaround it for now by including "debug.h" before including the
    00059 // header of that library.
    00060 // More information for library authors that use libcwd can be found on
    00061 // http://libcwd.sourceforge.net/reference-manual/group__chapter__custom__debug__h.html
    00062 #error "DEBUGCHANNELS is defined while previously it was not defined.  See the comments in this header file for more information."
    00063 #endif
    00064
    00065 #endif // CWDEBUG
    00066
    00067 #ifndef LIBCWD_DEBUG_H
    00068 #define LIBCWD_DEBUG_H
    00069
    00070 #ifdef CWDEBUG
    00071
    00072 // The following header is also needed for end-applications, despite its name.
    00073 #include <libcwd/libraries_debug.h>
    00074
    00075 #ifndef LIBCWD_DOXYGEN
    00076
    00077 // The real code
    00078 #ifdef DEBUGCHANNELS
    00079 #define LIBCWD_DEBUGCHANNELS DEBUGCHANNELS
    00080 #else
    00081 #define LIBCWD_DEBUGCHANNELS libcwd::channels
    00082 #define LIBCWD_DEFAULT_DEBUGCHANNELS
    00083 #endif
    00084
    00085 #else // LIBCWD_DOXYGEN
    00086
    00087 // This is only here for the documentation.  The user will define DEBUGCHANNELS, not LIBCWD_DEBUGCHANNELS.
    00094 #define DEBUGCHANNELS
    00095 #endif // LIBCWD_DOXYGEN
    00096
    00097 // For use in applications
    00124 #define Debug(x) \
    00125     LibcwDebug(LIBCWD_DEBUGCHANNELS, x)
    00126
    00154 #define Dout(cntrl, data) \
    00155     LibcwDout(LIBCWD_DEBUGCHANNELS, ::libcwd::libcw_do, cntrl, data)
    00156
    00164 #define DoutFatal(cntrl, data) \
    00165     LibcwDoutFatal(LIBCWD_DEBUGCHANNELS, ::libcwd::libcw_do, cntrl, data)
    00166
    00190 #define ForAllDebugChannels(STATEMENT...) \
    00191     LibcwdForAllDebugChannels(LIBCWD_DEBUGCHANNELS, STATEMENT)
    00192
    00209 #define ForAllDebugObjects(STATEMENT...) \
    00210     LibcwdForAllDebugObjects(LIBCWD_DEBUGCHANNELS, STATEMENT)
    00211
    00212 // Finally, in order for Dout() to be usable, we need this.
    00213 #ifndef LIBCW_IOSTREAM
    00214 #define LIBCW_IOSTREAM
    00215 #include <iostream>
    00216 #endif
    00217
    00218 #endif // CWDEBUG
    00219 #endif // LIBCWD_DEBUG_H