Menu
▾
▴
[libcw-cvs] [CVS] Module src
|
From: Carlo W. <li...@us...> - 2001-12-28 04:12:11
|
CVSROOT : /cvsroot/libcw
Module : src
Branch tags: branch-threading
Commit time: 2001-11-28 04:12:10 UTC
Modified files:
Tag: branch-threading
libcwd/documentation/Makefile libcwd/documentation/magic.dox
Added files:
Tag: branch-threading
libcwd/documentation/images/libcw_magic.png
libcwd/documentation/images/toc.png
libcwd/documentation/images/wink.gif
libcwd/documentation/images/buttons/lr_index.png
libcwd/documentation/images/buttons/lr_next.png
libcwd/documentation/images/buttons/lr_prev.png
libcwd/documentation/images/lines/cat.png
libcwd/documentation/images/lines/caterpil.png
libcwd/documentation/images/lines/ghost.png
libcwd/documentation/images/lines/hippo.png
libcwd/documentation/images/lines/mouse.png
libcwd/documentation/images/lines/owl.png
libcwd/documentation/images/lines/snail.png
libcwd/documentation/tutorial/.cvsignore
libcwd/documentation/tutorial/Makefile
libcwd/documentation/tutorial/channel.cc
libcwd/documentation/tutorial/faq.m4
libcwd/documentation/tutorial/hello_world.cc
libcwd/documentation/tutorial/index.m4
libcwd/documentation/tutorial/intro.m4
libcwd/documentation/tutorial/log_file.cc
libcwd/documentation/tutorial/tut1.m4
libcwd/documentation/tutorial/tut2.m4
libcwd/documentation/tutorial/tut3.m4
libcwd/documentation/tutorial/tut4.m4
libcwd/documentation/tutorial/tut5.m4
libcwd/documentation/tutorial/tut6.m4
libcwd/documentation/tutorial/tut7.m4
libcwd/documentation/tutorial/examples5/Makedefs.h
libcwd/documentation/tutorial/examples5/Makefile
libcwd/documentation/tutorial/examples5/README
libcwd/documentation/tutorial/examples5/sysinclude/README
libcwd/documentation/tutorial/examples5/sysinclude/libbooster/debug.h
libcwd/documentation/tutorial/examples5/sysinclude/libturbo/debug.h
libcwd/documentation/tutorial/examples5/tut5.1/.cvsignore
libcwd/documentation/tutorial/examples5/tut5.1/Makefile
libcwd/documentation/tutorial/examples5/tut5.2/.cvsignore
libcwd/documentation/tutorial/examples5/tut5.3/.cvsignore
libcwd/documentation/tutorial/examples5/tut5.3/Makefile
libcwd/documentation/tutorial/examples5/tut5.4/.cvsignore
libcwd/documentation/tutorial/examples5/tut5.4/Makefile
libcwd/documentation/tutorial/examples7/Makedefs.h
libcwd/documentation/tutorial/examples7/Makefile
libcwd/documentation/tutorial/examples7/debug.h
libcwd/documentation/tutorial/examples7/sys.h
libcwd/documentation/tutorial/examples7/tut7.1/.cvsignore
libcwd/documentation/tutorial/examples7/tut7.1/Makefile
libcwd/documentation/tutorial/examples7/tut7.2/.cvsignore
libcwd/documentation/tutorial/examples7/tut7.2/Makefile
libcwd/documentation/tutorial/examples7/tut7.3/.cvsignore
libcwd/documentation/tutorial/examples7/tut7.3/Makefile
Log message:
Added tutorial to the cvs. Using .png instead of .gif where possible.
---------------------- diff included ----------------------
Index: src/libcwd/documentation/Makefile
diff -u src/libcwd/documentation/Makefile:1.1.2.3 src/libcwd/documentation/Makefile:1.1.2.4
--- src/libcwd/documentation/Makefile:1.1.2.3 Wed Dec 26 21:13:21 2001
+++ src/libcwd/documentation/Makefile Thu Dec 27 20:11:58 2001
@@ -4,7 +4,9 @@
.PHONY: html external styles tutorial
-html: external styles tutorial
+all: html tutorial
+
+html: styles external
rm -rf html
doxygen doxygen.config
mv html/preparation.html html/preparation.tmp
Index: src/libcwd/documentation/images/buttons/lr_index.png
Index: src/libcwd/documentation/images/buttons/lr_next.png
Index: src/libcwd/documentation/images/buttons/lr_prev.png
Index: src/libcwd/documentation/images/libcw_magic.png
Index: src/libcwd/documentation/images/lines/cat.png
Index: src/libcwd/documentation/images/lines/caterpil.png
Index: src/libcwd/documentation/images/lines/ghost.png
Index: src/libcwd/documentation/images/lines/hippo.png
Index: src/libcwd/documentation/images/lines/mouse.png
Index: src/libcwd/documentation/images/lines/owl.png
Index: src/libcwd/documentation/images/lines/snail.png
Index: src/libcwd/documentation/images/toc.png
Index: src/libcwd/documentation/images/wink.gif
Index: src/libcwd/documentation/magic.dox
diff -u src/libcwd/documentation/magic.dox:1.1.2.3 src/libcwd/documentation/magic.dox:1.1.2.4
--- src/libcwd/documentation/magic.dox:1.1.2.3 Wed Dec 26 21:13:21 2001
+++ src/libcwd/documentation/magic.dox Thu Dec 27 20:11:58 2001
@@ -23,7 +23,7 @@
\htmlonly
<p STYLE="margin-left: 1.27cm"> <br>
-<img width=340 height=165 src="../images/libcw_magic.gif" alt="Memory layout of magic numbers" border=0>
+<img width=340 height=165 src="../images/libcw_magic.png" alt="Memory layout of magic numbers" border=0>
<br CLEAR=ALL> <br>
Figure 1. Memory layout of an allocated memory block with <CODE>DEBUGMAGICMALLOC</CODE> defined.
\endhtmlonly
Index: src/libcwd/documentation/tutorial/.cvsignore
diff -u /dev/null src/libcwd/documentation/tutorial/.cvsignore:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/.cvsignore Thu Dec 27 20:11:59 2001
@@ -0,0 +1,7 @@
+hello_world
+channel
+log_file
+turn_on
+amo.cc
+amo
+*.html
Index: src/libcwd/documentation/tutorial/Makefile
diff -u /dev/null src/libcwd/documentation/tutorial/Makefile:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/Makefile Thu Dec 27 20:11:59 2001
@@ -0,0 +1,40 @@
+.SUFFIXES:
+.PHONY: examples html
+
+FILES5:=$(shell grep 'START CODE' tut5.m4 | cut -d \ -f4)
+FILES7:=$(shell grep 'START CODE' tut7.m4 | cut -d \ -f4)
+
+all: examples html
+
+examples: $(FILES5) $(FILES7)
+html: index.html faq.html intro.html tut1.html tut2.html tut3.html tut4.html tut5.html tut6.html tut7.html
+
+%.html: %.m4 ../definitions.m4
+ m4 -D__TUTORIAL=1 -I.. $< > $@
+
+$(FILES5): tut5.m4 ../../.libs/libcwd.so
+ @$(MAKE) $@-x
+
+$(FILES7): tut7.m4 ../../.libs/libcwd.so
+ @$(MAKE) -s $@-x
+
+%-x:
+ @IN=`echo $* | sed -e 's/examples\([57]\).*/tut\1.m4/'`; \
+ grep -A1000 "START CODE $*" $$IN |\
+ grep -B1000 "END CODE $*" |\
+ egrep -v "(START|END) CODE $*" |\
+ sed -e 's/</</g' -e 's/>/>/g' -e 's/&/\&/g' -e 's/"/"/g' -e 's/§/§/g' \
+ -e 's/<SPAN.[^>]*>//g' -e 's/<\/SPAN>//g' > $*.tmp; \
+ if (test ! -f $* || ! cmp -s $* $*.tmp); then \
+ echo "Extracting $* from $$IN."; \
+ mv $*.tmp $*; \
+ else \
+ echo "$* wasn't changed."; \
+ touch $*; \
+ rm $*.tmp; \
+ fi; \
+ OUT=`echo $(*F) | sed -e 's/\.[ch]*$$//'`; \
+ if test "$$OUT" != "debug"; then \
+ $(MAKE) -C $(*D) $$OUT; \
+ fi
+
Index: src/libcwd/documentation/tutorial/channel.cc
diff -u /dev/null src/libcwd/documentation/tutorial/channel.cc:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/channel.cc Thu Dec 27 20:11:59 2001
@@ -0,0 +1,26 @@
+// Compile as: g++ -g -DCWDEBUG channel.cc -lcwd [-lbfd -liberty [-ldl]]
+// Please see the "example-project" in the source distribution of libcwd
+// for a better Real Life example.
+
+#include <libcw/sysd.h>
+#define DEBUGCHANNELS ::example // Where we'll put our namespace dc
+#include <libcw/debug.h>
+
+#ifdef CWDEBUG
+namespace example { // namespace dc cannot be put in ::
+ namespace dc {
+ libcw::debug::channel_ct ghost("GHOST"); // Create our own Debug Channel
+ }
+}
+#endif
+
+int main(void)
+{
+ Debug( dc::ghost.on() ); // Remember: don't forget to turn
+ Debug( libcw_do.on() ); // the debug Channel and Object on!
+
+ for (int i = 0; i < 4; ++i)
+ Dout( dc::ghost, "i = " << i ); // We can write more than just
+ // "Hello World" to the ostream :)
+ return 0;
+}
Index: src/libcwd/documentation/tutorial/examples5/Makedefs.h
diff -u /dev/null src/libcwd/documentation/tutorial/examples5/Makedefs.h:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples5/Makedefs.h Thu Dec 27 20:11:59 2001
@@ -0,0 +1,107 @@
+# This file contains the Project specific variables.
+#
+# Extra parameters can be added to the following variables:
+#
+# CFLAGS, CXXFLAGS, INCLUDEFLAGS, SYSTEMINCLUDEFLAGS, LDFLAGS.
+#
+# Always use a += for these variables to *add* parameters rather
+# than overriding them!
+
+#
+# CFLAGS / CXXFLAGS
+#
+# Project specific compiler flags.
+#
+# Use this when profiling:
+
+##CFLAGS=-pg -O6 -pipe
+##CXXFLAGS=-pg -O6 -pipe -fno-exceptions
+##LDFLAGS=-pg
+
+# Add extra, project specific, defines here, etc.
+
+##CFLAGS+=-D__MYCLIB__
+CXXFLAGS+=-DCWDEBUG
+
+#
+# INCLUDEFLAGS
+#
+# Project specific "include" flags.
+#
+# These directories are searched when you use an #include "foobar.h"
+# in your source code.
+#
+# The given directories will be relative to the directory from which
+# the compiler is started, which is the directory that the source
+# file being compiled is in. Therefore always use -I$(BASEDIR) as
+# a prefix (BASEDIR is the directory this file is in).
+#
+# Note: If you want to add an include directory that is specific for
+# only one executable or library, you might want to add this -I flag
+# to the Makefile for that executable or library respectively instead.
+
+INCLUDEFLAGS+=-I$(BASEDIR)/tut5.2
+
+#
+# SYSTEMINCLUDEFLAGS
+#
+# Project specific system <include> flags.
+#
+# These directories are searched when you use a #include <foobar.h>
+# in your source code.
+#
+# Note: If you are writting a library, then you want to use
+# #include <yourlib/foobar.h> in your headerfiles, because later on
+# these header files are installed in /usr/local/include for instance.
+# In that case you need to add -I$(BASEDIR)/include *here* instead
+# to in INCLUDEFLAGS above.
+#
+
+SYSTEMINCLUDEFLAGS+=-I$(BASEDIR)/sysinclude -I$(BASEDIR)/../../../include
+
+#
+# LDFLAGS
+#
+# Project specific linker flags (Overridden flags: -s or -pg ...)
+#
+# These flags are passed to the compiler at link time, these flags
+# are given a default value in $(PROTODIR)/Makedefs.h. You can
+# override them here.
+#
+
+LIBPATH:=$(shell (cd $(BASEDIR)/../../../.libs; pwd))
+LDFLAGS=-Wl,-rpath,$(LIBPATH)
+
+#
+# LIBFLAGS
+#
+# Project specific linker flags (Persistent flags: -L and -Wl,...)
+#
+# If you want to link your (test) executables with the latest version of
+# your project library instead of the version that was actually installed
+# in /usr/local (for example), then you need to add -L$(BASEDIR)/lib to
+# LIBFLAGS.
+
+LIBFLAGS+=-L$(BASEDIR)/../../../.libs
+
+#
+# DFLAGS
+#
+# Extra flags for generating dependencies.
+# The default is -MM, only including "local" headers.
+# Use this if you need dependencies on <system> headers,
+# (for example when you are writing a library and are using <headers>
+# with angle brackets yourself).
+
+##DFLAGS=-M
+
+#
+# CPPEXT
+#
+# The C++ extension that is used in this project. Correct this!
+
+CPPEXT=.cc
+
+# Speed up
+.SUFFIXES:
+
Index: src/libcwd/documentation/tutorial/examples5/Makefile
diff -u /dev/null src/libcwd/documentation/tutorial/examples5/Makefile:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples5/Makefile Thu Dec 27 20:11:59 2001
@@ -0,0 +1,14 @@
+# List of subdirectories (automatically updated by `makeproto'):
+SUBDIRS=tut5.1 tut5.3 tut5.4
+
+#-----------------------------------------------------------------------------
+
+include $(PROTODIR)/base/PTMakefile
+
+# Add here project specific additions:
+
+#build::
+#depend::
+clean::
+ rm -rf tut5.2/debug.o example-*
+#real-clean::
Index: src/libcwd/documentation/tutorial/examples5/README
diff -u /dev/null src/libcwd/documentation/tutorial/examples5/README:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples5/README Thu Dec 27 20:11:59 2001
@@ -0,0 +1,10 @@
+In order to compile this you will need to have `prototype' installed.
+You can download `prototype' from http://www.xs4all.nl/~carlo17/prototype/
+
+
+Compile by typing:
+
+make
+
+This will create all executables from tutorial 5 in the current directory.
+
Index: src/libcwd/documentation/tutorial/examples5/sysinclude/README
diff -u /dev/null src/libcwd/documentation/tutorial/examples5/sysinclude/README:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples5/sysinclude/README Thu Dec 27 20:11:59 2001
@@ -0,0 +1,3 @@
+The header files in this directory are NOT examples of how
+to write correctly a library headerfile. They are only
+included to be able to test the rest.
Index: src/libcwd/documentation/tutorial/examples5/sysinclude/libbooster/debug.h
diff -u /dev/null src/libcwd/documentation/tutorial/examples5/sysinclude/libbooster/debug.h:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples5/sysinclude/libbooster/debug.h Thu Dec 27 20:11:59 2001
@@ -0,0 +1,14 @@
+#include <libcw/debug.h>
+
+namespace booster {
+ namespace debug {
+ namespace channels {
+ namespace dc {
+ using namespace libcw::debug;
+ using namespace libcw::debug::channels::dc;
+ extern channel_ct booster;
+ extern channel_ct foobar;
+ }
+ }
+ }
+}
Index: src/libcwd/documentation/tutorial/examples5/sysinclude/libturbo/debug.h
diff -u /dev/null src/libcwd/documentation/tutorial/examples5/sysinclude/libturbo/debug.h:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples5/sysinclude/libturbo/debug.h Thu Dec 27 20:11:59 2001
@@ -0,0 +1,20 @@
+#include <libcw/debug.h>
+
+namespace turbo {
+ namespace debug {
+ namespace channels {
+ namespace dc {
+ using namespace libcw::debug;
+ using namespace libcw::debug::channels::dc;
+ extern channel_ct turbo;
+ extern channel_ct foobar;
+ }
+ }
+ }
+}
+
+namespace libcw {
+ namespace debug {
+ using namespace turbo::debug;
+ }
+}
Index: src/libcwd/documentation/tutorial/examples5/tut5.1/.cvsignore
diff -u /dev/null src/libcwd/documentation/tutorial/examples5/tut5.1/.cvsignore:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples5/tut5.1/.cvsignore Thu Dec 27 20:11:59 2001
@@ -0,0 +1,2 @@
+turn_on.cc
+turn_on
Index: src/libcwd/documentation/tutorial/examples5/tut5.1/Makefile
diff -u /dev/null src/libcwd/documentation/tutorial/examples5/tut5.1/Makefile:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples5/tut5.1/Makefile Thu Dec 27 20:11:59 2001
@@ -0,0 +1,30 @@
+# Directory where the base Makefile resides:
+BASEDIR=..
+
+# List of source files (one per executable):
+CSRC=
+CXXSRC=turn_on.cc
+
+# List of subdirectories:
+SUBDIRS=
+
+# Extra static libraries to link with:
+STATICLIBS=
+
+# Extra shared libraries to link with:
+SHAREDLIBS=-lcwd
+
+# Put here extra -L... flags
+LIBFLAGS=
+
+# Extra *.o files that need to be linked:
+EXTRA_OBJS=
+
+#-----------------------------------------------------------------------------
+
+include $(PROTODIR)/test/PTMakefile
+
+build::
+ ln -f turn_on ../example-5.1
+#clean::
+#depend::
Index: src/libcwd/documentation/tutorial/examples5/tut5.2/.cvsignore
diff -u /dev/null src/libcwd/documentation/tutorial/examples5/tut5.2/.cvsignore:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples5/tut5.2/.cvsignore Thu Dec 27 20:11:59 2001
@@ -0,0 +1,3 @@
+debug.h
+debug.cc
+sys.h
Index: src/libcwd/documentation/tutorial/examples5/tut5.3/.cvsignore
diff -u /dev/null src/libcwd/documentation/tutorial/examples5/tut5.3/.cvsignore:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples5/tut5.3/.cvsignore Thu Dec 27 20:11:59 2001
@@ -0,0 +1,4 @@
+test1.cc
+test2.cc
+test1
+test2
Index: src/libcwd/documentation/tutorial/examples5/tut5.3/Makefile
diff -u /dev/null src/libcwd/documentation/tutorial/examples5/tut5.3/Makefile:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples5/tut5.3/Makefile Thu Dec 27 20:11:59 2001
@@ -0,0 +1,31 @@
+# Directory where the base Makefile resides:
+BASEDIR=..
+
+# List of source files (one per executable):
+CSRC=
+CXXSRC=test1.cc test2.cc
+
+# List of subdirectories:
+SUBDIRS=
+
+# Extra static libraries to link with:
+STATICLIBS=
+
+# Extra shared libraries to link with:
+SHAREDLIBS=-lcwd
+
+# Put here extra -L... flags
+LIBFLAGS=
+
+# Extra *.o files that need to be linked:
+EXTRA_OBJS=$(BASEDIR)/tut5.2/debug.o
+
+#-----------------------------------------------------------------------------
+
+include $(PROTODIR)/test/PTMakefile
+
+build::
+ ln -f test1 ../example-5.3.1
+ ln -f test2 ../example-5.3.2
+#clean::
+#depend::
Index: src/libcwd/documentation/tutorial/examples5/tut5.4/.cvsignore
diff -u /dev/null src/libcwd/documentation/tutorial/examples5/tut5.4/.cvsignore:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples5/tut5.4/.cvsignore Thu Dec 27 20:11:59 2001
@@ -0,0 +1,16 @@
+test1.cc
+test2.cc
+test3.cc
+test4.cc
+test5.cc
+test6.cc
+test7.cc
+test8.cc
+test1
+test2
+test3
+test4
+test5
+test6
+test7
+test8
Index: src/libcwd/documentation/tutorial/examples5/tut5.4/Makefile
diff -u /dev/null src/libcwd/documentation/tutorial/examples5/tut5.4/Makefile:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples5/tut5.4/Makefile Thu Dec 27 20:11:59 2001
@@ -0,0 +1,36 @@
+# Directory where the base Makefile resides:
+BASEDIR=..
+
+# List of source files (one per executable):
+CSRC=
+CXXSRC=test3.cc test4.cc test5.cc test6.cc test7.cc test8.cc
+
+# List of sub directories:
+SUBDIRS=
+
+# Extra static libraries to link with:
+STATICLIBS=
+
+# Extra shared libraries to link with:
+SHAREDLIBS=-lcwd
+
+# Put here extra -L... flags
+LIBFLAGS=
+
+# Extra *.o files that need to be linked:
+EXTRA_OBJS=$(BASEDIR)/tut5.2/debug.o
+
+#-----------------------------------------------------------------------------
+
+include $(PROTODIR)/test/PTMakefile
+
+build::
+ ln -f test3 ../example-5.4.1
+ ln -f test4 ../example-5.4.2
+ ln -f test5 ../example-5.4.3
+ ln -f test6 ../example-5.4.4
+ ln -f test7 ../example-5.4.5
+ ln -f test8 ../example-5.4.6
+
+#clean::
+#depend::
Index: src/libcwd/documentation/tutorial/examples7/Makedefs.h
diff -u /dev/null src/libcwd/documentation/tutorial/examples7/Makedefs.h:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples7/Makedefs.h Thu Dec 27 20:12:00 2001
@@ -0,0 +1,103 @@
+# This file contains the Project specific variables.
+#
+# Extra parameters can be added to the following variables:
+#
+# CFLAGS, CXXFLAGS, INCLUDEFLAGS, SYSTEMINCLUDEFLAGS, LDFLAGS.
+#
+# Always use a += for these variables to *add* parameters rather
+# than overriding them!
+
+#
+# CFLAGS / CXXFLAGS
+#
+# Project specific compiler flags.
+#
+# Use this when profiling:
+
+##CFLAGS=-pg -O6 -pipe
+##CXXFLAGS=-pg -O6 -pipe -fno-exceptions
+##LDFLAGS=-pg
+
+# Add extra, project specific, defines here, etc.
+
+##CFLAGS+=-D__MYCLIB__
+CXXFLAGS+=-DCWDEBUG
+
+#
+# INCLUDEFLAGS
+#
+# Project specific "include" flags.
+#
+# These directories are searched when you use an #include "foobar.h"
+# in your source code.
+#
+# The given directories will be relative to the directory from which
+# the compiler is started, which is the directory that the source
+# file being compiled is in. Therefore always use -I$(BASEDIR) as
+# a prefix (BASEDIR is the directory this file is in).
+#
+# Note: If you want to add an include directory that is specific for
+# only one executable or library, you might want to add this -I flag
+# to the Makefile for that executable or library respectively instead.
+
+INCLUDEFLAGS+=-I$(BASEDIR)
+
+#
+# SYSTEMINCLUDEFLAGS
+#
+# Project specific system <include> flags.
+#
+# These directories are searched when you use a #include <foobar.h>
+# in your source code.
+#
+# Note: If you are writting a library, then you want to use
+# #include <yourlib/foobar.h> in your headerfiles, because later on
+# these header files are installed in /usr/local/include for instance.
+# In that case you need to add -I$(BASEDIR)/include *here* instead
+# to in INCLUDEFLAGS above.
+#
+
+SYSTEMINCLUDEFLAGS+=-I$(BASEDIR)/sysinclude -I$(BASEDIR)/../../../include
+
+#
+# LDFLAGS
+#
+# Project specific linker flags (Overridden flags: -s or -pg ...)
+#
+# These flags are passed to the compiler at link time, these flags
+# are given a default value in $(PROTODIR)/Makedefs.h. You can
+# override them here.
+#
+
+LIBPATH:=$(shell (cd $(BASEDIR)/../../../.libs; pwd))
+LDFLAGS=-Wl,-rpath,$(LIBPATH)
+
+#
+# LIBFLAGS
+#
+# Project specific linker flags (Persistent flags: -L and -Wl,...)
+#
+# If you want to link your (test) executables with the latest version of
+# your project library instead of the version that was actually installed
+# in /usr/local (for example), then you need to add -L$(BASEDIR)/lib to
+# LIBFLAGS.
+
+LIBFLAGS+=-L$(BASEDIR)/../../../.libs
+
+#
+# DFLAGS
+#
+# Extra flags for generating dependencies.
+# The default is -MM, only including "local" headers.
+# Use this if you need dependencies on <system> headers,
+# (for example when you are writing a library and are using <headers>
+# with angle brackets yourself).
+
+##DFLAGS=-M
+
+#
+# CPPEXT
+#
+# The C++ extension that is used in this project. Correct this!
+
+CPPEXT=.cc
Index: src/libcwd/documentation/tutorial/examples7/Makefile
diff -u /dev/null src/libcwd/documentation/tutorial/examples7/Makefile:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples7/Makefile Thu Dec 27 20:12:00 2001
@@ -0,0 +1,13 @@
+# List of subdirectories (automatically updated by `makeproto'):
+SUBDIRS=tut7.1 tut7.2 tut7.3
+
+#-----------------------------------------------------------------------------
+
+include $(PROTODIR)/base/PTMakefile
+
+# Add here project specific additions:
+
+#build::
+#depend::
+#clean::
+#real-clean::
Index: src/libcwd/documentation/tutorial/examples7/debug.h
diff -u /dev/null src/libcwd/documentation/tutorial/examples7/debug.h:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples7/debug.h Thu Dec 27 20:12:00 2001
@@ -0,0 +1,25 @@
+#ifndef DEBUG_H
+#define DEBUG_H
+
+#ifndef CWDEBUG
+#define AllocTag1(p)
+#define AllocTag2(p, desc)
+#define AllocTag_dynamic_description(p, x)
+#define AllocTag(p, x)
+#define ASSERT(x)
+#define Debug(x)
+#define Dout(a, b)
+#define DoutFatal(a, b) LibcwDoutFatal(::std, , a, b)
+#define ForAllDebugChannels(STATEMENT)
+#define ForAllDebugObjects(STATEMENT)
+#define LibcwDebug(dc_namespace, x)
+#define LibcwDout(a, b, c, d)
+#define LibcwDoutFatal(a, b, c, d) do { ::std::cerr << d << ::std::endl; exit(-1); } while(1)
+#define NEW(x) new x
+#define set_alloc_checking_off()
+#define set_alloc_checking_on()
+#else
+#include <libcw/debug.h>
+#endif
+
+#endif
Index: src/libcwd/documentation/tutorial/examples7/sys.h
diff -u /dev/null src/libcwd/documentation/tutorial/examples7/sys.h:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples7/sys.h Thu Dec 27 20:12:00 2001
@@ -0,0 +1,13 @@
+// Bug workaround for libstdc++, avoid warnings like
+// /usr/include/g++-3/iostream.h:253:5: "_G_CLOG_CONFLICT" is not defined
+#include <_G_config.h>
+#ifndef _G_CLOG_CONFLICT
+#define _G_CLOG_CONFLICT 0
+#endif
+#ifndef _G_HAS_LABS
+#define _G_HAS_LABS 1
+#endif
+
+#ifdef CWDEBUG
+#include <libcw/sysd.h>
+#endif
Index: src/libcwd/documentation/tutorial/examples7/tut7.1/.cvsignore
diff -u /dev/null src/libcwd/documentation/tutorial/examples7/tut7.1/.cvsignore:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples7/tut7.1/.cvsignore Thu Dec 27 20:12:00 2001
@@ -0,0 +1,6 @@
+invisible.cc
+test_delete.cc
+coredump.cc
+invisible
+test_delete
+coredump
Index: src/libcwd/documentation/tutorial/examples7/tut7.1/Makefile
diff -u /dev/null src/libcwd/documentation/tutorial/examples7/tut7.1/Makefile:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples7/tut7.1/Makefile Thu Dec 27 20:12:00 2001
@@ -0,0 +1,33 @@
+# Directory where the base Makefile resides:
+BASEDIR=..
+
+# List of source files (one per executable):
+CSRC=
+CXXSRC=invisible.cc coredump.cc test_delete.cc
+
+# List of sub directories:
+SUBDIRS=
+
+# Extra static libraries to link with:
+STATICLIBS=
+
+# Extra shared libraries to link with:
+SHAREDLIBS=-lcwd
+
+# Put here extra -L... flags
+LIBFLAGS=
+
+# Extra *.o files that need to be linked:
+EXTRA_OBJS=
+
+#-----------------------------------------------------------------------------
+
+include $(PROTODIR)/test/PTMakefile
+
+build::
+ ln -f invisible ../example-7.1.1
+ ln -f coredump ../example-7.1.2
+ ln -f test_delete ../example-7.1.3
+
+#clean::
+#depend::
Index: src/libcwd/documentation/tutorial/examples7/tut7.2/.cvsignore
diff -u /dev/null src/libcwd/documentation/tutorial/examples7/tut7.2/.cvsignore:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples7/tut7.2/.cvsignore Thu Dec 27 20:12:00 2001
@@ -0,0 +1,2 @@
+find_alloc.cc
+find_alloc
Index: src/libcwd/documentation/tutorial/examples7/tut7.2/Makefile
diff -u /dev/null src/libcwd/documentation/tutorial/examples7/tut7.2/Makefile:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples7/tut7.2/Makefile Thu Dec 27 20:12:00 2001
@@ -0,0 +1,31 @@
+# Directory where the base Makefile resides:
+BASEDIR=..
+
+# List of source files (one per executable):
+CSRC=
+CXXSRC=find_alloc.cc
+
+# List of sub directories:
+SUBDIRS=
+
+# Extra static libraries to link with:
+STATICLIBS=
+
+# Extra shared libraries to link with:
+SHAREDLIBS=-lcwd
+
+# Put here extra -L... flags
+LIBFLAGS=
+
+# Extra *.o files that need to be linked:
+EXTRA_OBJS=
+
+#-----------------------------------------------------------------------------
+
+include $(PROTODIR)/test/PTMakefile
+
+build::
+ ln -f find_alloc ../example-7.2
+
+#clean::
+#depend::
Index: src/libcwd/documentation/tutorial/examples7/tut7.3/.cvsignore
diff -u /dev/null src/libcwd/documentation/tutorial/examples7/tut7.3/.cvsignore:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples7/tut7.3/.cvsignore Thu Dec 27 20:12:00 2001
@@ -0,0 +1,10 @@
+total_alloc.cc
+memleak.cc
+memleak2.cc
+marker.cc
+marker2.cc
+total_alloc
+memleak
+memleak2
+marker
+marker2
Index: src/libcwd/documentation/tutorial/examples7/tut7.3/Makefile
diff -u /dev/null src/libcwd/documentation/tutorial/examples7/tut7.3/Makefile:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/examples7/tut7.3/Makefile Thu Dec 27 20:12:00 2001
@@ -0,0 +1,35 @@
+# Directory where the base Makefile resides:
+BASEDIR=..
+
+# List of source files (one per executable):
+CSRC=
+CXXSRC=total_alloc.cc marker.cc marker2.cc memleak.cc memleak2.cc
+
+# List of sub directories:
+SUBDIRS=
+
+# Extra static libraries to link with:
+STATICLIBS=
+
+# Extra shared libraries to link with:
+SHAREDLIBS=-lcwd
+
+# Put here extra -L... flags
+LIBFLAGS=
+
+# Extra *.o files that need to be linked:
+EXTRA_OBJS=
+
+#-----------------------------------------------------------------------------
+
+include $(PROTODIR)/test/PTMakefile
+
+build::
+ ln -f total_alloc ../example-7.3.1
+ ln -f marker.cc ../example-7.3.2
+ ln -f marker2.cc ../example-7.3.3
+ ln -f memleak.cc ../example-7.3.4
+ ln -f memleak2.cc ../example-7.3.5
+
+#clean::
+#depend::
Index: src/libcwd/documentation/tutorial/faq.m4
diff -u /dev/null src/libcwd/documentation/tutorial/faq.m4:1.1.2.1
--- /dev/null Thu Dec 27 20:12:10 2001
+++ src/libcwd/documentation/tutorial/faq.m4 Thu Dec 27 20:11:59 2001
@@ -0,0 +1,440 @@
+include(definitions.m4)dnl
+__HTMLHEADER
+__PAGEHEADER
+__PAGESTART
+
+<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="sysd.h"></A>
+<H3>1. Why do I have to include "libcw/sysd.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>This header file defines also a few very important operating system
+dependend macros like the ones used for inclusion of the ident string.
+Therefore <EM>nothing</EM> will compile without this header file.
+Because it 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 libcw header file before including libcw/sysd.h,
+will definitely lead to compile errors in that header file. </P>
+
+<A name="libcwd"></A>
+<H3>2. What is this <SPAN class="H3code">libcw</SPAN> talk?
+Aren't you forgetting the <U><SPAN class="H3code">d</SPAN></U> of
+<SPAN class="H3code">libcw<U>d</U></SPAN>?</H3>
+
+<P>Libcwd is a spin off of the larger libcw project.
+The header files of both are put in the same directory,
+called <SPAN class="filename">libcw </SPAN>(for example,
+<SPAN class="filename">/usr/include/libcw</SPAN>).</P>
+
+<P>The <U><SPAN class="code">d</SPAN></U> in
+<SPAN class="code">libcw<U>d</U></SPAN> stands for <U>D</U>ebugging.
+The <U><SPAN class="code">cw</SPAN></U> in
+<SPAN class="code">lib<U>cw</U></SPAN> stand for the initials of
+the designer/developer of this life-span project [but I suppose you already
+guessed that ;) ].</P>
+
+<A name="dir"></A>
+<H3>3. Why do I need to type "<SPAN class="H3code">libcw/sysd.h</SPAN>"
+and not just "<SPAN class="H3code">sysd.h</SPAN>"?</H3>
+
+<P>The header file names of libcw are not unique. In order to uniquely
+identify which header file needs to be included the "libcw/" 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/libcw</SPAN></SPAN> so you can skip
+the "libcw/" 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">libcw/debug.h</SPAN>?</H3>
+
+<P>Everything.
+Go and read the <A HREF="../html/reference.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="../html/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">libcw::debug</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">libcw::debug</SPAN>.
+The expression <SPAN class="code">Debug( STATEMENT );</SPAN> is equivalent with:</P>
+
+<PRE class="code">
+#ifdef CWDEBUG
+ do {
+ using namespace ::libcw::debug;
+ 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="../html/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="../html/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 <libcw/debug.h>
+
+namespace myapplication {
+ namespace debug {
+ namespace channels {
+ namespace dc {
+ using namespace ::libcw::debug::channels::dc;
+ extern ::libcw::debug::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="../html/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="../html/group__chapter__custom__debug__h.html">your own "debug.h"</A> file:</P>
+
+<PRE class="code">
+#ifdef CWDEBUG
+extern libcw::debug::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="../html/classlibcw_1_1debug_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"> libcw::debug::max_label_len</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 can not 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 can not make all of them current however. Worse, we can not
+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="../html/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="../html/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>
+
+__PAGEEND
+__PAGEFOOTER
+__HTMLFOOTER
+
Index: src/libcwd/documentation/tutorial/hello_world.cc
diff -u /dev/null src/libcwd/documentation/tutorial/hello_world.cc:1.1.2.1
--- /dev/null Thu Dec 27 20:12:11 2001
+++ src/libcwd/documentation/tutorial/hello_world.cc Thu Dec 27 20:11:59 2001
@@ -0,0 +1,13 @@
+#include <libcw/sysd.h> // This must be the first header file
+#include <libcw/debug.h>
+
+int main(void)
+{
+ Debug( dc::notice.on() ); // Turn on the NOTICE Debug Channel
+ Debug( libcw_do.on() ); // Turn the default Debug Object on
+
+ Dout( dc::notice, "Hello World" );
+
+ return 0;
+}
+
Index: src/libcwd/documentation/tutorial/index.m4
diff -u /dev/null src/libcwd/documentation/tutorial/index.m4:1.1.2.1
--- /dev/null Thu Dec 27 20:12:11 2001
+++ src/libcwd/documentation/tutorial/index.m4 Thu Dec 27 20:11:59 2001
@@ -0,0 +1,87 @@
+include(definitions.m4)dnl
+define(__TOC_START, [[
+</DIV>
+<TABLE border=0 cellpadding=0 cellspacing=10>
+
+<TR>
+<TD WIDTH=15 valign=center>
+ <IMG width=34 height=34 src="../images/toc.png" alt="Main index" align=top border=0>
+</TD>
+<TD valign=center><DIV class="toc-header1">
+ <A class="toc1" href="../html/index.html" target="_top">
+ Back to main index
+ </A></DIV>
+</TD>
+</TR>
+]])dnl
+define(__TOC_END, [[
+</TABLE>
+<DIV class="normal">
+]])dnl
+define(__PAGE, [[<!-- -Page $1---------------------------------------------------- -->
+
+<TR>
+<TD WIDTH=15 valign=center>
+ <IMG width=34 height=34 src="../images/toc.png" align=top border=0>
+</TD>
+<TD valign=center><DIV class="toc-header1">
+ <A class="toc1" href="$3">
+ $2
+ </A></DIV>
+</TD>
+</TR>]])dnl
+define(__PAGE_START, [[
+<TR>
+<TD WIDTH=15></TD>
+<TD>
+ <TABLE border=0 cellpadding=0 cellspacing=0>]])dnl
+define(__PAGE_END, [[
+ </TABLE>
+</TD>
+</TR>]])dnl
+define(__PARAGRAPH, [[
+<TR>
+<TD WIDTH=50><DIV class="toc-number$1">
+ $2
+</DIV></TD>
+<TD><DIV class="toc-header$1">
+ <A class="toc" HREF="$4">
+ $3
+ </A></DIV>
+</TD>
+</TR>]])dnl
+dnl#
+dnl# Start of document
+dnl#
+__HTMLHEADER
+__PAGEHEADER
+__PAGESTART
+<P>Welcome to the tutorial of libcwd, an Object Oriented debugging support library for C++ developers.</P>
+
+<H1>Table of Contents</H1>
+__TOC_START
+__PAGE(1, [[Introduction]], intro.html)
+__PAGE(2, [[Tutorial 1 : Hello World]], tut1.html)
+__PAGE(3, [[Tutorial 2 : Creating your own Debug Channels]], tut2.html)
+__PAGE(4, [[Tutorial 3 : Setting the <CODE>ostream</CODE>]], tut3.html)
+__PAGE(5, [[Tutorial 4 : Management of <CODE>CWDEBUG</CODE>]], tut4.html)
+__PAGE(6, [[Tutorial 5 : Advanced examples]], tut5.html)
+__PAGE_START
+__PARAGRAPH(2f, 5.1, [[Running over all Debug Channels]], [[tut5.html#Running]])
+__PARAGRAPH(2, 5.2, [[Debug Channels and name spaces]], [[tut5.html#Debug]])
+__PARAGRAPH(2, 5.3, [[Combining channels]], [[tut5.html#Combining]])
+__PARAGRAPH(2, 5.4, [[Formatting debug output]], [[tut5.html#Formatting]])
+__PARAGRAPH(3, 5.4.1, [[Control flags]], [[tut5.html#Control]])
+__PARAGRAPH(3, 5.4.2, [[Methods of the debug object]], [[tut5.html#Methods]])
+__PAGE_END
+__PAGE(7, [[Tutorial 6 : The debugging of dynamic memory allocations]], tut6.html)
+__PAGE(8, [[Tutorial 7 : Advanced examples]], tut7.html)
+__PAGE_START
+__PARAGRAPH(2f, 7.1, [[Removing allocations from the Allocated memory Overview]], [[tut7.html#Removing]])
+__PARAGRAPH(2, 7.2, [[Retrieving information about memory allocations]], [[tut7.html#Retrieving]])
+__PARAGRAPH(2, 7.3, [[Memory leak detection]], [[tut7.html#Memory]])
+__PAGE_END
+__TOC_END
+__PAGEEND
+__PAGEFOOTER
+__HTMLFOOTER
Index: src/libcwd/documentation/tutorial/intro.m4
diff -u /dev/null src/libcwd/documentation/tutorial/intro.m4:1.1.2.1
--- /dev/null Thu Dec 27 20:12:11 2001
+++ src/libcwd/documentation/tutorial/intro.m4 Thu Dec 27 20:11:59 2001
@@ -0,0 +1,32 @@
+include(definitions.m4)dnl
+__HTMLHEADER
+__PAGEHEADER
+__PAGESTART
+
+<H1>Tutorial</H1>
+
+<P><FONT class="hello">Hello</FONT>,
+my name is <A HREF="http://www.xs4all.nl/~carlo17/" TARGET="_blank">Carlo Wood</A>
+and I will guide you through a few example programs in order to help familiarize you
+with <code>libcwd</code>.</P>
+
+<P class="line"><IMG class="line" width=870 height=34 src="../images/lines/mouse.png"></P>
+
+<P>Hopefully you have already installed the library and the header files.
+If not, then do so now - see the <A HREF="../external/INSTALL">INSTALL</A> file in the
+<A HREF="http://sourceforge.net/project/showfiles.php?group_id=354" TARGET="_blank">distribution package</A>
+for detailed instructions.</P>
+
+<P>This tutorial is mixed with a lot of FAQ-style questions, which are linked to a more detailed explanation.
+For a correct understanding of the tutorial it is <EM>not</EM> needed to read these FAQs; they are only provided for your
+convenience, only read if you really want to know the answer.</P>
+
+__PAGEEND
+<P class="line"><IMG width=870 height=18 src="../images/lines/cat.png"></P>
+<DIV class="buttons">
+<A HREF="index.html"><IMG width=64 height=32 src="../images/buttons/lr_index.png" border="0"></A>
+<A HREF="tut1.html"><IMG width=64 height=32 src="../images/buttons/lr_next.png" border="0"></A>
+</DIV>
+__PAGEFOOTER
+__HTMLFOOTER
+
Index: src/libcwd/documentation/tutorial/log_file.cc
diff -u /dev/null src/libcwd/documentation/tutorial/log_file.cc:1.1.2.1
--- /dev/null Thu Dec 27 20:12:11 2001
+++ src/libcwd/documentation/tutorial/log_file.cc Thu Dec 27 20:11:59 2001
@@ -0,0 +1,21 @@
+#include <libcw/sysd.h>
+#include <fstream>
+#include <libcw/debug.h>
+
+int main(void)
+{
+ Debug( dc::notice.on() );
+ Debug( libcw_do.on() );
+
+#ifdef CWDEBUG
+ ofstream file;
+ file.open("log");
+#endif
+
+ // Set the ostream related with libcw_do to `file':
+ Debug( libcw_do.set_ostream(&file) );
+
+ Dout( dc::notice, "Hippopotamus are heavy" );
+
+ return 0;
+}
Index: src/libcwd/documentation/tutorial/tut1.m4
diff -u /dev/null src/libcwd/documentation/tutorial/tut1.m4:1.1.2.1
--- /dev/null Thu Dec 27 20:12:11 2001
+++ src/libcwd/documentation/tutorial/tut1.m4 Thu Dec 27 20:11:59 2001
@@ -0,0 +1,119 @@
+include(definitions.m4)dnl
+__HTMLHEADER
+__PAGEHEADER
+__PAGESTART
+
+<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>
+#include <libcw/sysd.h> // This must be the first header file
+#include <libcw/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>#include <libcw/sysd.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 libcw headers must include it.</P>
+
+<DIV class="faq-frame"><H4>FAQ</H4><UL class="faq">
+<LI><A HREF="faq.html#sysd.h">Why?</A></LI>
+<LI><A HREF="faq.html#libcwd">What is this <TT>libcw</TT> talk?
+Aren't you forgetting the <U><TT>d</TT></U> of
+<TT>libcw<U>d</U></TT>?</A></LI>
+<LI><A HREF="faq.html#dir">Why do I need to type "<CODE>libcw/sysd.h</CODE>"
+and not just "<CODE>sysd.h</CODE>"?</LI></A>
+</UL></DIV>
+
+<H3><CODE>#include <libcw/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>libcw/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 give...
[truncated message content] |
