// Work around for bug in doxygen.
#define debug somethingelse

/*!
\defgroup chapter_custom_debug_h The Custom debug.h File
\ingroup book_start
*/
/*!
\page page_custom_debug_h
\ingroup chapter_custom_debug_h

\section debug_channels_and_namespace Debug channels and namespace

\subsection applications Applications

User applications have less strict requirements than libraries, because nobody else will link with it.&nbsp;
The developer of an application directly controls and checks and resolves name collisions when needed.&nbsp;
If you are writing an end-application then you are still urged to create a header file
called %debug.h and use \em that in your source files, instead of including <libcwd/debug.h> directly.&nbsp;
You will benefit greatly from this in terms on flexibility (trust me).

\sa \ref preparation

\subsection libraries Libraries

If you are developing a library that uses libcwd then do not put your debug channels in the
libcwd::channels::dc namespace.&nbsp;
The correct way to declare new debug channels is by putting them in a namespace of the library itself.&nbsp;
Also end-applications will benefit by using this method (in terms of flexibility).

The following code would define a debug channel \c warp in the namespace \c libexample:

\verbatim // This is some .cpp file of your library.
 #include "debug.h"
 // ...
 #ifdef CWDEBUG
 namespace libexample {
   namespace channels {
     namespace dc {
       libcwd::channel_ct warp("WARP");
       // Add new channels here...
     }
   }
 }
 #endif
\endverbatim

The namespace channels in this example is not really necessary but it illustrates
which namespace DEBUGCHANNELS will be set to.  This is the namespace that needs to
contain the dc namespace.

Next provide two debug header files (both named %debug.h), one for installation
with the library headers (ie libexample/debug.h) and one in an include directory
that is only used while compiling your library itself - this one would not be installed.

The first one (the %debug.h that will be installed) would look something like this:

\code
 // This is for example <libexample/debug.h>
 #ifndef LIBEXAMPLE_DEBUG_H
 #define LIBEXAMPLE_DEBUG_H

 #ifdef CWDEBUG
 #include <libcwd/libraries_debug.h>

 namespace libexample {
   namespace channels {
     namespace dc {
       using namespace libcwd::channels::dc;
       extern libcwd::channel_ct warp;
       // Add new channels here...
     }
   }
 }

 // Define private debug output macros for use in header files of the library,
 // there is no reason to do this for normal applications.
 // We use a literal libexample::channels here and not LIBCWD_DEBUGCHANNELS!
 #define LibexampleDebug(STATEMENT...) LibcwDebug(libexample::channels, STATEMENT)
 #define LibexampleDout(cntrl, data) LibcwDout(libexample::channels, libcwd::libcw_do, cntrl, data)
 #define LibexampleDoutFatal(cntrl, data) LibcwDoutFatal(libexample::channels, libcwd::libcw_do, cntrl, data)
 #define LibexampleForAllDebugChannels(STATEMENT...) LibcwdForAllDebugChannels(libexample::channels, STATEMENT)
 #define LibexampleForAllDebugObjects(STATEMENT...) LibcwdForAllDebugObjects(libexample::channels, STATEMENT)

 // All other macros might be used in header files of libexample, but need to be
 // defined by the debug.h of the application that uses it.
 // LIBEXAMPLE_INTERNAL is defined when the library itself is being compiled (see below).
 #if !defined(Debug) && !defined(LIBEXAMPLE_INTERNAL)
 #error The application source file (.cc or .cpp) must use '#include "debug.h"' _before_ including the header file that it includes now, that led to this error.
 #endif

 #else

 #define LibexampleDebug(STATEMENT...) do { } while(0)
 #define LibexampleDout(cntrl, data) do { } while(0)
 #define LibexampleDoutFatal(cntrl, data) do { ::std::cerr << data << ::std::endl; ::std::exit(EXIT_FAILURE); } while(1)
 #define LibexampleForAllDebugChannels(STATEMENT...) do { } while(0)
 #define LibexampleForAllDebugObjects(STATEMENT...) do { } while(0)

 #endif // CWDEBUG

 #endif // LIBEXAMPLE_DEBUG_H
\endcode

The second "debug.h", which would not be installed but only be included when compiling
the .cpp files (that \#include "debug.h") of your library itself, then looks like this:

\htmlonly
<div class="fragment">
\endhtmlonly
<PRE> \#ifndef DEBUG_H
 \#define DEBUG_H
 &nbsp;
 \#ifndef CWDEBUG
 &nbsp;
 \#include &lt;iostream&gt;     // std::cerr
 \#include &lt;cstdlib&gt;      // std::exit, EXIT_FAILURE
\include nodebug.h \#endif // CWDEBUG
 &nbsp;
 \#define LIBEXAMPLE_INTERNAL		// See above.
 \#include &lt;libexample/debug.h&gt;	// The debug<b></b>.h shown above.
 \#define DEBUGCHANNELS libexample::channels
 \#ifdef CWDEBUG
 \#include &lt;libcwd/debug.h&gt;
 \#endif
 &nbsp;
 \#endif // DEBUG_H
</PRE>
\htmlonly
</div>
\endhtmlonly

\subsection header_files_of_libraries Header files of libraries

Don't use Dout etc. in header files of libraries, instead use (for example) LibExampleDout etc., as shown above.&nbsp;
If you want to use Dout etc. in your \em source files then you can do so
after first including the "debug.h" as shown above.

\subsection debug_channel_name_collisions Debug channel name collisions

The reason that libcwd uses the convention to put debug channels in the namespace dc
is to avoid collisions between debug channel names of libraries.&nbsp;
There are two types of name collisions possible: you upgrade or start to use a library which uses a debug channel
that you had already defined, in that case you might need to change the name of your own channel,
or you link with two or more libraries that both use libcwd and that defined the same debug channel,
in that case you will have to make your own debug namespace as shown above and choose a new name for one of the channels.

For example, suppose you link with two libraries: lib1 and lib2 who use the above convention and defined their
own namespaces called lib1 and lib2, but both defined a debug channel called foobar.&nbsp;
Then you can rename these channels as follows.&nbsp;
Make a debug header file that contains:

\code
 #define DEBUGCHANNELS ::application::channels
 #include <lib1/debug.h>
 #include <lib2/debug.h>
 namespace application {
   namespace channels {
     namespace dc {
       using namespace lib1::channels::dc;
       using namespace lib2::channels::dc;
       static libcwd::channel_ct& foobar1(lib1::channels::dc::foobar);
       static libcwd::channel_ct& foobar2(lib2::channels::dc::foobar);
     }
   }
 }
\endcode

\htmlonly
<DIV class="normal">
\endhtmlonly
The hiding mechanism of the above `cascading' of debug channel declarations of libraries works as follows.&nbsp;
The debug macros use a using-directive to include the scope LIBCWD_DEBUGCHANNELS, which is set to DEBUGCHANNELS
if you defined that and to libcwd::channels otherwise.&nbsp;
All debug channels are specified as <CODE>dc::channelname</CODE> in the source code and the namespace \c dc will
be uniquely defined.&nbsp;
For instance, in the case of the above example, when writing <CODE>dc::%notice</CODE> the \c dc will be unambiguously
resolved to <CODE>application::debug::channels::dc</CODE>, because it is the only \c dc name space in LIBCWD_DEBUGCHANNELS
(<CODE>application::debug::channels</CODE>).&nbsp;
The C++ standard states: "During the lookup of a name qualified by a namespace name, declarations that would otherwise be made
visible by a using-directive can be hidden by declarations with the same name in the namespace containing the using-directive;".&nbsp;
This allows us to put a list of using-directives in <CODE>application::debug::channels::dc</CODE> and then hide any collision by
redefining it in <CODE>application::debug::channels::dc</CODE> itself, either as new debug channel, or as reference to one of the
%debug %channels of the library of choice.
\htmlonly
</DIV>
\endhtmlonly

*/
