The C++ Debugging Support Library
By Carlo Wood, ©1999 - 2003.
|
|
The C++ Debugging Support Library
By Carlo Wood, ©1999 - 2003.
|
Warning: The ammount of information included in this FAQ is exhaustive. Do NOT read it except as a replacement for self-torture. Instead read the tutorial and skip all the references to this FAQ unless you find yourself banging your head into the wall asking yourself the same question as is listed in the tutorial. In that case a link will bring you here to read just that one question.
No, not unless you actually use the GNU extensions in parts of your
application that need to be portable (like non-debugging code).
While debugging the application you will only benefit from using as
much compiler support as you can get, allowing the compiler to tell you
what could possibly be wrong with your code.
Once the application works, you don't have to define _GNU_SOURCE
because you won't be including the debug code anymore, nor link with
libcwd.
Note that GNU g++ 3.x already defines this macro currently itself as a hack
to get the libstdc++ headers work properly, hence the test with #ifndef
is always needed (see http://gcc.gnu.org/ml/gcc/2002-02/msg00996.html).
This header file is used to fix operating systems bugs, including bugs in the system header files. The only way it can do this is when it is included before any other header file, including system header files.
Any project should have one header file that is included at the top of every source file.
If you already have one then you can add #include <libcwd/sys.h> to that file.
Otherwise you should add such a header file: its a Good Thing(tm) to have.
Because this must be included in every source file as very first header file, it would make no sense to include it also in another header file; so it isn't. As a result, forgetting this header file or including any other libcwd header file before including libcwd/sys.h, will definitely lead to compile errors in that header file.
The header file names of libcwd are not unique. In order to uniquely identify which header file needs to be included the "libcwd/" part is needed.
Never use the compiler option -I /usr/include/libcwd so you can skip the "libcwd/" part in your #include directives. There is no garantee that there isn't a header file name collision in that case.
Everything. Go and read the Reference Manual to get all gory details if you dare.
Because it is the only way to easy remove debugging code from an application as function of a macro and because it allows for the fastest possible code even without optimisation, which is often the case while debugging. A more detailed explanation is given in the Reference Manual.
The macro Debug() is used for two things. 1) The code inside it is only included when the macro CWDEBUG is defined. 2) It includes the namespace libcwd.
As a result, you don't have to add #ifdef CWDEBUG ... #endif around the code and in most cases you don't have to type libcwd. The expression Debug( STATEMENT ); is equivalent with:
#ifdef CWDEBUG
do {
using namespace ::libcwd;
using namespace DEBUGCHANNELS;
{ STATEMENT; }
} while(0);
#endif
Please note that definitions within a Debug() statement will be restricted to their own scope. Please read the Reference Manual for an explanation of DEBUGCHANNELS.
This question is covered in chapter Controlling The Output Level (Debug Channels) of the Reference Manual. As is described there, creating your own debug channels is best done by writing your own debug.h header file. The following template is a good start for such a debug.h for an end application (a library needs more work):
#ifndef MY_DEBUG_H
#define MY_DEBUG_H
#define DEBUGCHANNELS ::myapplication::debug::channels
#include <libcwd/debug.h>
namespace myapplication {
namespace debug {
namespace channels {
namespace dc {
using namespace ::libcwd::channels::dc;
extern ::libcwd::channel_ct mychannel;
// ... more channels here
}
}
}
}
#endif // MY_DEBUG_H
Replace «MY_DEBUG_H», «myapplication::debug» and «mychannel» with your own names.
See the example-project that comes with the source distribution of libcwd for a Real Life example.
Debug channels can be switched on and off at any time. At the start of your program you should turn on the channels of your choice by calling Debug(dc::channel.on()) once. Sometimes you want to temporally turn off certain channels: you want to make sure that no debug output is written to that particular debug channel, at that moment. This can be achieved by calling the methods off() and on() in pairs and in that order. For example:
// Make sure no allocation debug output is generated: Debug( dc::malloc.off() ); char* temporal_buffer = new char [1024]; // ... do stuff ... delete [] temporal_buffer; Debug( dc::malloc.on() );
This will work even when `do stuff' calls a function that also turns dc::malloc off and on: after the call to on() the debug channel can still be off: it is restored to the on/off state that it was in before the corresponding call to off(). In fact, the calls to off() and on() only respectively increment and decrement a counter.
A Debug Channel is a fictious "news channel". It should contain information of a certain kind that is interesting or not interesting as a whole. A Debug Channel is not a device or stream, a single debug channel is best viewed upon as a single bit in a bitmask. Every time you write debug output you have to specify a "bitmask" which specifies when that message is written; like when you are cross posting to usenet news groups, specifying multiple news groups for a single message. When any of the specified Debug Channels is turned on, then the message is written to the output stream of the underlaying debug object.
Yes, you can make as many debug objects as you like.
Each debug object is associated with one ostream. However, the default debug output macros Dout and
DoutFatal use the default debug object libcw_do.
It isn't hard at all to define your own macros though; for example add something like the following to
your own "debug.h" file:
#ifdef CWDEBUG extern libcwd::debug_ct my_debug_object; #define MyDout(cntrl, data) LibcwDout(DEBUGCHANNELS, my_debug_object, cntrl, data) #define MyDoutFatal(cntrl, data) LibcwDoutFatal(DEBUGCHANNELS, my_debug_object, cntrl, data) #else // !CWDEBUG #define MyDout(a, b) #define MyDoutFatal(a, b) LibcwDoutFatal(::std, /*nothing*/, a, b) #endif // !CWDEBUG
Debug objects can be switched on and off at any time. At the start of your program you should turn on the debug object(s) by calling Debug(debugobject.on()) once. Sometimes you want to temporally turn off all debug output. This can be achieved by calling the methods off() and on() in pairs and in that order. For example:
// Disable all debug output to `libcw_do': Debug( libcw_do.off() ); // ... do stuff ... Debug( libcw_do.on() );
This will work even when `do stuff' calls a function that also turns libcw_do off and on: after the call to on() the debug object can still be off: it is restored to the on/off state that it was in before the corresponding call to off(). In fact, the calls to off() and on() only respectively increment and decrement a counter.
You can change the ostream that is associated with a Debug Object at any time. For example, changing the ostream of libcw_do from the default cerr to cout:
Debug( libcw_do.set_ostream(&cout) );
See also tutorial 3.
The Debug Objects and Debug Channels are global objects. Because libcwd could not be
dependant of libcw, they do not use libcw's Global<> template.
As a result, the order in which the debug channels and objects are initialized is
unknown; moreover, other global objects whose constructors might try to write debug output could
be constructed before the debug objects are initialized! The debug objects are therefore
designed in a way that independent of there internal state of initialisation they function without
crashing. It should be obvious that the only way this could be achieved was by creating them
in the state off.
The order in which Debug Channels and Debug Objects are turned on does not matter at all. At most, when you think about the Debug Object as the «main switch» then it seems to make sense to first play with the little channel switches before finally activating the complete Debug machinery. Others might think more in the lines of: lets start with setting the debug object on before I forget it. That is a bit too fuzzy (logic) for me though ;)
Good question. It can't be because I wasn't creative, I am very creative. Note that I didn't think of Object as in OOP (that would be uncreative) but more along the lines of an object, like in science fiction stories -- objects you can't get around. The monolith of 2001: A Space Odyssey is a good example I guess.
Unlike the monolith however, a Debug Object is not mysterious at all. Basically it is a pointer to an ostream with a few extra attributes added to give it an internal state for 'on' (pass output on) and 'off' (don't pass output on) as well as some formatting information of how to write the data that is passed on to its ostream.
Yes, that colon needs to be there. It was chosen not to include the semi-colon in the macro because this way it looks a bit like a function call which feels more natural.
The code Dout(dc::notice, "Hello World"); is definitely a statement and therefore needs to end on a semi-colon (after expansion). When the macro CWDEBUG is not defined, the macro is replaced with whitespace but still has to be a statement: it must be a single semi-colon then.
For example,
if (error)
Dout(dc::notice, "An error occured");
exit(0);
cerr << "We should never reach this\n";
If the complete line Dout(dc::notice, "An error occured");, including semi-colon is removed (replaced with whitespace), then the line exit(0); would be executed only when error is true! And when the semi-colon would be included in the macro then people could easily be tempted to add a semi-colon anyway (because it looks so much better), which would break code like:
if (error)
Dout(dc::notice, "An error occured");
else
cout << "Everything is ok\n";
because after macro expansion that would become:
if (error)
;
;
else // <-- syntax error
cout << "Everything is ok\n";
No, macro Dout et al. use exclusively the debug object that comes with libcwd. It is easy to define your own macros however (see above). You are free to redefine the Dout macros however, just realize that libcwd will continue to use its own debug object (libcw_do), debug output written by libcwd in its header files do not use the Dout macro (especially in order to allow you to redefine it).
No! And that is a direct result of the fact that Dout et al. are macros. Indeed this fact could therefore be a little confusing. In pseudo-code the macro expansion looks something like
if (debug object and any of the debug channels are turned on)
the_ostream << your message;
and so, "your message" is not evaluated when it isn't also actually written. This fact is also covered in the Reference Manual.
Note that debug code should never have an effect on any of your variables (and thus on the application) anyway. In the production version of your application all debug code will be removed and you don't want it to behave differently then!
Yes, and a lot more. See tutorial 5.4.
The maximum length of the label of a new Debug Channel is given by the constant libcwd::max_label_len_c. At this moment that is 16.
This is a complex reason. Basically because of a flaw in the design of namespaces in C++. Namespaces have been introduced in order to avoid name collisions, which was a good thing. It doesn't make much sense if you constantly have to type ::somelibrary::debug::channel::notice of course, then you could as well have avoided the name space problem by using somelibrary_debug_channel_notice right? Therefore you don't have to type the name of the namespace that is "current". There can be only one namespace current at a time however. The result is that this cannot be used to solve our problem: We want to avoid both, name collisions between debug channels and any other variable or function name, but also between debug channels defined in different libraries. That means we need more than one namespace: A namespace for each of the libraries. We cannot make all of them current however. Worse, we cannot make any namespace current because it must be possible to add code that writes debug output everywhere. We can only use the using namespace directive. Now here is the real flaw: A using namespace directive gives no priority whatsoever to names when resolving them, for example, you can't do this:
namespace base {
int base1;
int base2;
}
namespace derived {
using namespace base;
int derived1;
char base1;
}
// ...
using namespace derived;
base1 = 'a';
because C++ will make absolutely no difference between variables defined in derived and variables defined in base but will complain that base1 is ambigious.
The only opening that the ANSI/ISO C++ Standard allows us here is in the following phrase:
Given X::m (where X is a user-declared namespace), or given ::m (where X is the global namespace), let S be the set of all declarations of m in X and in the transitive closure of all namespaces nominated by using-directives in X and its used namespaces, except that using-directives are ignored in any namespace, including X, directly containing one or more declarations of m. No namespace is searched more than once in the lookup of a name. If S is the empty set, the program is ill-formed. Otherwise, if S has exactly one member, or if the context of the reference is a using-declaration, S is the required set of declarations of m. Otherwise if the use of m is not one that allows a unique declaration to be chosen from S, the program is ill-formed.
Replace X with dc:: (obviously we don't want to put the debug channels in global namespace) and we can use this rule to at least select a specific channel by using the trick that the used dc namespace is not the same namespace for the different libraries. Then we can use debug channels with the same name in dc namespaces in different namespaces in different libraries and use the namespaces of one library at a time to select the current dc namespace.
If this is over your head then that is probably because I can't explain :). Don't worry however, you only need to know how to introduce new debug channels and not understand how it works. The correct procedure is described in the Reference Manual.
Yes. How, is described in the Reference Manual. For some background information on why this has to be so complex, please read the previous question.
The colon is indented so it ends up in the same column for all existing debug channels. Hence, the longest label of all existing/created debug channels determines the number of spaces. This value can be less than the maximum allowed label size of course.