1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML LANG="en-us">
<HEAD>
<META name="Author" content="Carlo Wood">
<META http-equiv="content-type" content="text/html; charset=iso-8859-1">
<META http-equiv="content-script-type" content="text/javascript">
<TITLE>libcwd: The C++ Debugging Support Library - Tutorial</TITLE>
<SCRIPT SRC="../scripts/detect_browser.js"></SCRIPT>
<SCRIPT>need_style_tutorial=1</SCRIPT>
<SCRIPT SRC="../scripts/load_style_sheets.js"></SCRIPT>
</HEAD>
<BODY>
<TABLE class="header" height=64 width="100%" cellpadding=0 cellspacing=0 border=0>
<TR>
<TD width=237 valign=top>
<IMG valign=top src="../images/libcwd_logo.png" alt="" align=left border=0>
</TD>
<TD width="100%" align=center>
<DIV class="header-title">
The C++ Debugging Support Library
</DIV>
<DIV class="header-copyright">
By Carlo Wood, ©1999 - 2003.
</DIV>
</TD>
</TR>
<SCRIPT>if (is_mozilla4) document.write("<TR><TD colspan=2 height=19 valign=bottom><HR SIZE=2 NOSHADE></TD></TR>");</SCRIPT>
</TABLE>
<DIV class="body">
<H1>FAQ</H1>
<P>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
<A HREF="index.html">tutorial</A> 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.</P>
<HR SIZE=1 NOSHADE>
<A name="GNU_SOURCE"></A>
<H3>1. Won't this define make my code non-portable?</H3>
<P>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 <CODE>#ifndef</CODE>
is always needed (see <A HREF="http://gcc.gnu.org/ml/gcc/2002-02/msg00996.html">http://gcc.gnu.org/ml/gcc/2002-02/msg00996.html</A>).</P>
<A name="sys.h"></A>
<H3>2. Why do I have to include "libcwd/sys.h" as first header file?</H3>
<P>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 <EM>any</EM> other header file, including system header
files.</P>
<P>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 <CODE>#include <libcwd/sys.h></CODE> to that file.
Otherwise you should add such a header file: its a Good Thing(tm) to have.</P>
<P>Because this must be included in <EM>every</EM> 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. </P>
<A name="dir"></A>
<H3>3. Why do I need to type "<SPAN class="H3code">libcwd/sys.h</SPAN>"
and not just "<SPAN class="H3code">sys.h</SPAN>"?</H3>
<P>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.</P>
<P>Never use the compiler option <SPAN class="code"><SPAN class="command-line-parameter">-I</SPAN>
<SPAN class="command-line-variable">/usr/include/libcwd</SPAN></SPAN> so you can skip
the "libcwd/" part in your <SPAN class="code">#include</SPAN>
directives. There is no garantee that there isn't a header file name
collision in that case.</P>
<A name="debug.h"></A>
<H3>4. What is defined <EM>exactly</EM> in <SPAN class="H3code">libcwd/debug.h</SPAN>?</H3>
<P>Everything.
Go and read the <A HREF="../reference-manual/index.html">Reference Manual</A> to get <EM>all</EM> gory details if you dare.</P>
<A name="macros"></A>
<H3>5. Why are you using macros for <SPAN class="H3code">Debug</SPAN> and <SPAN class="H3code">Dout</SPAN>?</H3>
<P>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 <A HREF="../reference-manual/page_why_macro.html">Reference Manual</A>.</P>
<A name="Debug"></A>
<H3>6. Why do I need to type the <SPAN class="H3code">Debug( )</SPAN> around it?</H3>
<P>The macro <SPAN class="code">Debug()</SPAN> is used for two things. 1) The code inside it is only included
when the macro <SPAN class="code">CWDEBUG</SPAN> is defined. 2) It includes the namespace <SPAN class="code">libcwd</SPAN>.</P>
<P>As a result, you don't have to add <SPAN class="code">#ifdef CWDEBUG ... #endif</SPAN> around the code and
in most cases you don't have to type <SPAN class="code">libcwd</SPAN>.
The expression <SPAN class="code">Debug( STATEMENT );</SPAN> is equivalent with:</P>
<PRE class="code">
#ifdef CWDEBUG
do {
using namespace ::libcwd;
using namespace DEBUGCHANNELS;
{ STATEMENT; }
} while(0);
#endif
</PRE>
<P>Please note that definitions within a <SPAN class="code">Debug()</SPAN> statement will be
restricted to their own scope.
Please read the <A HREF="../reference-manual/group__chapter__custom__debug__h.html">Reference Manual</A> for an
explanation of <SPAN class="code">DEBUGCHANNELS</SPAN>.</P>
<A name="DebugChannels"></A>
<H3>7. Which Debug Channels exist? Can I make my own?</H3>
<P>This question is covered in chapter
<A HREF="../reference-manual/group__group__debug__channels.html">Controlling The Output Level (Debug Channels)</A>
of the Reference Manual.
As is described there, creating your own debug channels is best done by writing your own <SPAN class="code">debug.h</SPAN>
header file. The following template is a good start for such a <SPAN class="code">debug.h</SPAN> for an end application
(a library needs more work):</P>
<PRE class="code">
#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
</PRE>
<P>Replace «<SPAN class="code">MY_DEBUG_H</SPAN>»,
«<SPAN class="code">myapplication::debug</SPAN>» and «<SPAN class="code">mychannel</SPAN>» with your own names.
<P>See the <SPAN class="filename">example-project</SPAN> that comes
with the source distribution of libcwd for a Real Life example.</P>
<A name="recursive"></A>
<H3>8. Can I turn Debug Channels off again? Can I do that recursively?</H3>
<P>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 <SPAN class="code">Debug(dc::<EM>channel</EM>.on())</SPAN>
<EM>once</EM>. 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 <SPAN class="code">off()</SPAN> and <SPAN class="code">on()</SPAN> in
<EM>pairs</EM> and in that order. For example:</P>
<PRE class="code">
// 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() );
</PRE>
<P>This will work even when `do stuff' calls a function that also turns <SPAN class="code">dc::malloc</SPAN> off and on:
after the call to <SPAN class="code">on()</SPAN> the debug channel can still be off: it is restored to the on/off state
that it was in before the corresponding call to <SPAN class="code">off()</SPAN>. In fact, the calls to
<SPAN class="code">off()</SPAN> and <SPAN class="code">on()</SPAN> only respectively increment and decrement a counter.</P>
<A name="Channel"></A>
<H3>9. Why do you call it a Debug <EM>Channel</EM>? What <EM>is</EM> a Debug Channel?</H3>
<P>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.</P>
<A name="OwnDebugObject"></A>
<H3>10. Can I make my own Debug Object?</H3>
<P><A HREF="../reference-manual/group__chapter__custom__do.html">Yes</A>, you can make as many debug objects as you like.
Each debug object is associated with one ostream. However, the default debug output macros <CODE>Dout</CODE> and
<CODE>DoutFatal</CODE> use the default debug object <CODE>libcw_do</CODE>.
It isn't hard at all to define your own macros though; for example add something like the following to
<A HREF="../reference-manual/group__chapter__custom__debug__h.html">your own "debug.h"</A> file:</P>
<PRE class="code">
#ifdef CWDEBUG
extern libcwd::debug_ct <SPAN class="highlight">my_debug_object</SPAN>;
#define <SPAN class="highlight">MyDout</SPAN>(cntrl, data) LibcwDout(DEBUGCHANNELS, <SPAN class="highlight">my_debug_object</SPAN>, cntrl, data)
#define <SPAN class="highlight">MyDoutFatal</SPAN>(cntrl, data) LibcwDoutFatal(DEBUGCHANNELS, <SPAN class="highlight">my_debug_object</SPAN>, cntrl, data)
#else // !CWDEBUG
#define <SPAN class="highlight">MyDout</SPAN>(a, b)
#define <SPAN class="highlight">MyDoutFatal</SPAN>(a, b) LibcwDoutFatal(::std, /*nothing*/, a, b)
#endif // !CWDEBUG
</PRE>
<A name="recursive2"></A>
<H3>11. Can I turn Debug Objects off again? Can I do that recursively?</H3>
<P>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 <SPAN class="code">Debug(<EM>debugobject</EM>.on())</SPAN>
<EM>once</EM>. Sometimes you want to temporally turn off all debug output.
This can be achieved by calling the methods <SPAN class="code">off()</SPAN> and <SPAN class="code">on()</SPAN> in
<EM>pairs</EM> and in that order. For example:</P>
<PRE class="code">
// Disable all debug output to `libcw_do':
Debug( libcw_do.off() );
// ... do stuff ...
Debug( libcw_do.on() );
</PRE>
<P>This will work even when `do stuff' calls a function that also turns <SPAN class="code">libcw_do</SPAN> off and on:
after the call to <SPAN class="code">on()</SPAN> the debug object can still be off: it is restored to the on/off state
that it was in before the corresponding call to <SPAN class="code">off()</SPAN>. In fact, the calls to
<SPAN class="code">off()</SPAN> and <SPAN class="code">on()</SPAN> only respectively increment and decrement a counter.</P>
<A name="SetOstream"></A>
<H3>12. How do I set a new <SPAN class="H3code">ostream</SPAN> for a given Debug Object?</H3>
<P>You can change the <SPAN class="code">ostream</SPAN> that is associated with a Debug Object at any time.
For example, changing the <SPAN class="code">ostream</SPAN> of <SPAN class="code">libcw_do</SPAN> from the
default <SPAN class="code">cerr</SPAN> to <SPAN class="code">cout</SPAN>:</P>
<PRE class="code">
Debug( libcw_do.set_ostream(&cout) );
</PRE>
<P>See also <A HREF="tut3.html">tutorial 3</A>.</P>
<A name="WhyOff"></A>
<H3>13. Why are Debug Objects turned off at creation?</H3>
<P>The Debug Objects and Debug Channels are global objects. Because libcwd could not be
dependant of libcw, they do not use libcw's <CODE>Global<></CODE> 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 <EM>off</EM>.</P>
<A name="Order"></A>
<H3>14. Why do you turn on the debug object after you enable a debug channel, why not the other way around?</H3>
<P>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
<EM>on</EM> before I forget it. That is a bit <EM>too</EM> fuzzy (logic) for me though ;)</P>
<A name="Object"></A>
<H3>15. Why do you call it a Debug <EM>Object</EM>? What <EM>is</EM> a Debug Object?</H3>
<P>Good question. It can't be because I wasn't creative, I am very creative.
Note that I didn't think of <EM>Object</EM> as in OOP (<EM>that</EM> would be uncreative)
but more along the lines of an <EM>object</EM>, like in science fiction stories -- objects
you can't get around. The monolith of <A HREF="http://uk.imdb.com/Title?0062622" target="_blank">2001: A Space Odyssey</A>
is a good example I guess.</P>
<P>Unlike the monolith however, a Debug Object is not mysterious at all. Basically it
is a pointer to an <SPAN class="code">ostream</SPAN> 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
<SPAN class="code">ostream</SPAN>.</P>
<A name="semicolon"></A>
<H3>16. Do I need to type that semi-colon after the macro? Why isn't it part of the macro?</H3>
<P>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.</P>
<P>The code <SPAN class="code">Dout(dc::notice, "Hello World");</SPAN> is definitely
a <EM>statement</EM> and therefore needs to end on a semi-colon (after expansion). When the
macro <SPAN class="code">CWDEBUG</SPAN> is not defined, the macro is replaced with
whitespace but still has to be a statement: it must be a single semi-colon then.</P>
<P>For example,</P>
<PRE class="code">
if (error)
Dout(dc::notice, "An error occured");
exit(0);
cerr << "We should never reach this\n";
</PRE>
<P>If the complete line <SPAN class="code">Dout(dc::notice, "An error occured");</SPAN>,
including semi-colon is removed (replaced with whitespace), then the line
<SPAN class="code">exit(0);</SPAN> would be executed only when <SPAN class="code">error</SPAN>
is <SPAN class="code">true</SPAN>! 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:</P>
<PRE class="code">
if (error)
Dout(dc::notice, "An error occured");
else
cout << "Everything is ok\n";
</PRE>
<P>because after macro expansion that would become:</P>
<PRE class="code">
if (error)
;
;
else // <-- syntax error
cout << "Everything is ok\n";
</PRE>
<A name="LibcwDout"></A>
<H3>17. I made my own Debug Object, can I still use <SPAN class="H3code">Dout</SPAN>?</H3>
<P>No, macro <SPAN class="code">Dout</SPAN> et al. use exclusively the debug object that
comes with libcwd. It is easy to define your own macros however (see <A HREF="#OwnDebugObject">above</A>).
You are free to <EM>redefine</EM> the <SPAN class="code">Dout</SPAN> macros however, just realize that libcwd
will continue to use its own debug object (<SPAN class="code">libcw_do</SPAN>), debug output written by libcwd
in its header files do not use the <SPAN class="code">Dout</SPAN> macro (especially in order to allow you
to redefine it).</P>
<A name="evaluation"></A>
<H3>18. Is the second field of the macro still evaluated when the Debug Channel and/or Debug Object are turned off?</H3>
<P>No! And that is a direct result of the fact that <SPAN class="code">Dout</SPAN> et al. are <EM>macros</EM>.
Indeed this fact could therefore be a little confusing.
In pseudo-code the macro expansion looks something like</P>
<PRE class="code">
if (debug object and any of the debug channels are turned on)
the_ostream << your message;
</PRE>
<P>and so, "your message" is <EM>not</EM> evaluated when it isn't also
actually written. This fact is also covered in the
<A HREF="../reference-manual/classlibcwd_1_1debug__ct.html#eval_example">Reference Manual</A>.</P>
<P>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!</P>
<A name="suppress"></A>
<H3>19. Can I suppress that new-line character?</H3>
<P>Yes, and a lot more. See <A HREF="tut5.html#Formatting">tutorial 5.4</A>.</P>
<A name="label"></A>
<H3>20. What is the maximum length of a label?</H3>
<P>The maximum length of the label of a new Debug Channel is given
by the constant<SPAN class="code"> libcwd::max_label_len_c</SPAN>.
At this moment that is 16.</P>
<A name="prefix"></A>
<H3>21. Why do I have to use the <SPAN class="H3code">dc::</SPAN> prefix?</H3>
<P>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 <SPAN class="code">::somelibrary::debug::channel::notice</SPAN>
of course, then you could as well have avoided the name space problem by using
<SPAN class="code">somelibrary_debug_channel_notice</SPAN> right?
Therefore you don't have to type the name of the namespace that is "current".
There can be only <EM>one</EM> 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 <EM>also</EM> 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
<EM>everywhere</EM>. We can only use the <SPAN class="code">using namespace</SPAN>
directive. Now here is the real flaw: A <SPAN class="code">using namespace</SPAN> directive
gives no priority whatsoever to names when resolving them, for example, you can't do this:</P>
<PRE class="code">
namespace base {
int base1;
int base2;
}
namespace derived {
using namespace base;
int derived1;
char base1;
}
// ...
using namespace derived;
base1 = 'a';
</PRE>
<P>because C++ will make absolutely no difference between variables defined in
<SPAN class="code">derived</SPAN> and variables defined in <SPAN class="code">base</SPAN>
but will complain that <SPAN class="code">base1</SPAN> is ambigious.</P>
<P>The only opening that the ANSI/ISO C++ Standard allows us here is in the
following phrase:</P>
<QUOTE>
Given <SPAN class="code">X::m</SPAN> (where <SPAN class="code">X</SPAN> is a user-declared namespace),
or given <SPAN class="code">::m</SPAN> (where <SPAN class="code">X</SPAN> is the global namespace),
let <SPAN class="code">S</SPAN> be the set of all declarations of <SPAN class="code">m</SPAN> in <SPAN class="code">X</SPAN>
and in the transitive closure of all namespaces nominated by <I>using-directive</I>s in X and its used namespaces,
except that <I>using-directive</I>s are ignored in any namespace, including <SPAN class="code">X</SPAN>,
directly containing one or more declarations of <SPAN class="code">m</SPAN>.
No namespace is searched more than once in the lookup of a name. If <SPAN class="code">S</SPAN> is the empty set,
the program is ill-formed. Otherwise, if <SPAN class="code">S</SPAN> has exactly one member,
or if the context of the reference is a using-declaration, <SPAN class="code">S</SPAN> is
the required set of declarations of <SPAN class="code">m</SPAN>.
Otherwise if the use of <SPAN class="code">m</SPAN> is not one that allows a unique
declaration to be chosen from <SPAN class="code">S</SPAN>, the program is ill-formed.
</QUOTE>
<P>Replace <SPAN class="code">X</SPAN> with <SPAN class="code">dc::</SPAN>
(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 <SPAN class="code">dc</SPAN> namespace is <EM>not the same</EM>
namespace for the different libraries. Then we can use debug channels with
the same name in <SPAN class="code">dc</SPAN> namespaces in <EM>different</EM>
namespaces in different libraries and use the namespaces of <EM>one</EM> library
at a time to select the current <SPAN class="code">dc</SPAN> namespace.</P>
<P>If this is over your head then that is probably because I can't explain :).
Don't worry however, you only need to know <EM>how</EM> to introduce new debug
channels and not understand how it works. The correct procedure is described
in the <A HREF="../reference-manual/group__group__debug__channels.html">Reference Manual</A>.</P>
<A name="ownnamespace"></A>
<H3>22. Can I put my debug channels in my own name space?</H3>
<P>Yes. How, is described in the <A HREF="../reference-manual/group__group__debug__channels.html">Reference Manual</A>.
For some background information on why this has to be so complex, please read the <A HREF="#prefix">previous question</A>.</P>
<A name="labelwidth"></A>
<H3>23. Why does it print spaces between the label and the colon? How is the field width of the label determined?</H3>
<P>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 <A HREF="#label">maximum allowed label size</A> of course.</P>
</DIV>
<ADDRESS>Copyright © 2001, 2002 Carlo Wood. All rights reserved.</ADDRESS>
</BODY>
</HTML>
|
