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
|
<!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">
<H2>Tutorial 1: Hello World</H2>
<P>The smallest C++ program that prints «<SPAN class="output">Hello World</SPAN>» as <I>debug output</I>
to <CODE>cerr</CODE> is:</P>
<P class="download">[<A HREF="hello_world.cc">download</A>]</P>
<P>Compile as: <SPAN class="shell-command">g++ -g -DCWDEBUG hello_world.cc -lcwd -o hello_world</SPAN></P>
<PRE>
// These four lines should actually be part of a custom "sys.h" file. See <A HREF="tut2.html">tutorial 2</A>.
#ifndef _GNU_SOURCE // Already defined by g++ 3.0 and higher.
#define _GNU_SOURCE // This must be defined before including <libcwd/sys.h>
#endif
#include <libcwd/sys.h> // This must be the first header file
// This line should actually be part of a custom "debug.h" file. See <A HREF="tut2.html">tutorial 2</A>.
#include <libcwd/debug.h>
int main(void)
{
Debug( dc::notice.on() ); // Turn on the NOTICE Debug Channel.
Debug( libcw_do.on() ); // Turn on the default Debug Object.
Dout(dc::notice, "Hello World");
return 0;
}
</PRE>
<P>Each of the lines of code in this first example program are explained below:</P>
<H3><CODE>#define _GNU_SOURCE</CODE></H3>
<P>This define is necessary to tell the system headers that you
want to use the GNU extensions (see /usr/include/features.h).
In order to make you explicitely aware of the fact that it is
defined, libcwd does not define this macro itself (which it could do inside <libcwd/sys.h>),
but forces you to define it when using libcwd.
Note that you only really have to define it when you compiled libcwd with
threading support.
If you do not define this macro and libcwd needs it, then you will get
a compile error in <libcwd/sys.h> telling you so.</P>
<DIV class="faq-frame"><H4>FAQ</H4><UL class="faq">
<LI><A HREF="faq.html#GNU_SOURCE">Won't this define make my code non-portable?</A></LI>
</UL></DIV>
<H3><CODE>#include <libcwd/sys.h></CODE></H3>
<P>This must be the very first header file that is included; even before system header files.
Every source file that includes other libcwd headers must include it.</P>
<DIV class="faq-frame"><H4>FAQ</H4><UL class="faq">
<LI><A HREF="faq.html#sys.h">Why?</A></LI>
<LI><A HREF="faq.html#dir">Why do I need to type "<CODE>libcwd/sys.h</CODE>"
and not just "<CODE>sys.h</CODE>"?</LI></A>
</UL></DIV>
<H3><CODE>#include <libcwd/debug.h></CODE></H3>
<P>This header file contains all definitions and declarations that are needed for debug output.
For example, it defines the macros <CODE>Debug</CODE> and <CODE>Dout</CODE> and declares
the debug object <CODE>libcw_do</CODE> and the debug channel <CODE>dc::notice</CODE>.</P>
<DIV class="faq-frame"><H4>FAQ</H4><UL class="faq">
<LI><A HREF="faq.html#debug.h">What is defined <EM>exactly</EM> in <CODE>libcwd/debug.h</CODE>?</A></LI>
<LI><A HREF="faq.html#macros">Why are you using macros for <CODE>Debug</CODE> and <CODE>Dout</CODE>?</A></LI>
</UL></DIV>
<A NAME="turn_on_channel"></A>
<H3><CODE>Debug( dc::notice.on() );</CODE></H3>
<P>This turns on the <I><U>D</U>ebug <U>C</U>hannel</I> <CODE><U>dc</U>::notice</CODE>.
Without this line, the code <CODE>Dout(dc::notice, "Hello World")</CODE> would output
nothing: all <I>Debug Channels</I> are <EM>off</EM> by default, at start up.</P>
<DIV class="faq-frame"><H4>FAQ</H4><UL class="faq">
<LI><A HREF="faq.html#Debug">Why do I need to type the <CODE>Debug( )</CODE> around it?</A></LI>
<LI><A HREF="faq.html#DebugChannels">Which Debug Channels exist? Can I make my own?</A></LI>
<LI><A HREF="faq.html#recursive">Can I turn Debug Channels off again? Can I do that recursively?</A></LI>
<LI><A HREF="faq.html#Channel">Why do you call it a Debug <EM>Channel</EM>? What <EM>is</EM> a Debug Channel?</A></LI>
</UL></DIV>
<H3><CODE>Debug( libcw_do.on() );</CODE></H3>
<P>This turns on the <I><U>D</U>ebug <U>O</U>bject</I> <CODE>libcw_<U>do</U></CODE>.
Without this line, the code <CODE>Dout(dc::notice, "Hello World")</CODE> would output
nothing: all <I>Debug Objects</I> are <EM>off</EM> by default, at start up.</P>
<P>A <I>Debug Object</I> is related to exactly one <CODE>ostream</CODE>.
<CODE>Libcwd</CODE> defines only one <I>Debug Object</I> by itself (being <CODE>libcw_do</CODE>),
this is enough for most applications.
The default ostream is <CODE>cerr</CODE>.
Using the macro <CODE>Dout</CODE> causes debug output to be written to <CODE>libcw_do</CODE>.</P>
<DIV class="faq-frame"><H4>FAQ</H4><UL class="faq">
<LI><A HREF="faq.html#Debug">Why do I need to type the <CODE>Debug( )</CODE> around it?</A></LI>
<LI><A HREF="faq.html#OwnDebugObject">Can I make my own Debug Object?</A></LI>
<LI><A HREF="faq.html#recursive2">Can I turn Debug Objects off again? Can I do that recursively?</A></LI>
<LI><A HREF="faq.html#SetOstream">How do I set a new <CODE>ostream</CODE> for a given Debug Object?</A></LI>
<LI><A HREF="faq.html#WhyOff">Why are Debug Objects turned off at creation?</A></LI>
<LI><A HREF="faq.html#Order">Why do you turn on the debug object after you enable a debug channel, why not the other way around?</A></LI>
<LI><A HREF="faq.html#Object">Why do you call it a Debug <EM>Object</EM>? What <EM>is</EM> a Debug Object?</A></LI>
</UL></DIV>
<H3><CODE>Dout(dc::notice, "Hello World");</CODE></H3>
<P>This outputs "Hello World" to the <CODE>ostream</CODE> currently related to
<CODE>libcw_do</CODE> provided that the <I>Debug Channel</I>
<CODE>dc::notice</CODE> is turned on.</P>
<P>Output is written as if everything in the second field of the macro <CODE>Dout</CODE> is
written to an ostream; It is "equivalent" with: <CODE>cerr << "Hello World" << '\n';</CODE></P>
<DIV class="faq-frame"><H4>FAQ</H4><UL class="faq">
<LI><A HREF="faq.html#macros">Why is <CODE>Dout</CODE> a macro and not a template?</A></LI>
<LI><A HREF="faq.html#semicolon">Do I need to type that semi-colon after the macro? Why isn't it part of the macro?</A></LI>
<LI><A HREF="faq.html#LibcwDout">I made my own Debug Object, can I still use <CODE>Dout</CODE>?</A></LI>
<LI><A HREF="faq.html#evaluation">Is the second field of the macro still evaluated when the Debug Channel and/or Debug Object are turned off?</A></LI>
<LI><A HREF="faq.html#suppress">Can I suppress that new-line character?</A></LI>
</UL></DIV>
</DIV>
<P class="line"><IMG width=870 height=18 src="../images/lines/cat.png"></P>
<DIV class="buttons">
<A HREF="intro.html"><IMG width=64 height=32 src="../images/buttons/lr_prev.png" border=0></A>
<A HREF="index.html"><IMG width=64 height=32 src="../images/buttons/lr_index.png" border="0"></A>
<A HREF="tut2.html"><IMG width=64 height=32 src="../images/buttons/lr_next.png" border=0></A>
</DIV>
<ADDRESS>Copyright © 2001, 2002 Carlo Wood. All rights reserved.</ADDRESS>
</BODY>
</HTML>
|
