Short:        C macros for turning on/off stdout debug
Author:       mikko.koivunalho@kolumbus.fi (Mikko Koivunalho)
Uploader:     mikko koivunalho kolumbus fi (Mikko Koivunalho)
Type:         dev/debug
Version:      1.0
Replaces:     SimpleDebug.lha
Requires:     C compiler with a C preprocessor
Architecture: generic

CHANGES

V1.0
 - Initial release.

README

The most traditional way to do simple debugging in a program is to
insert printf() clauses in the middle of the program code to display
in stdout whatever information is required at the time. This is
actually quite effective but also very crude. The biggest trouble is
getting rid of those printouts when they are no longer needed. What's
worse is that every programmer also hates to destroy the work that has
been done to create all that debugging information. Sure, the program
works now, but what about the next time when modifications are being
done it. Then those printf() sentences would be required again!

Of course there is the preprocessor with its #if sentences. You can
always write like this:

#if DEBUG
				printf("Control has reached this point!n");
#endif
				i = 3;
#if DEBUG
				printf("i=%sn", i);
#endif
				i++;

which is just fine but it gets awfully tedious and also awfully ugly
because preprocessor commands must always lie at the beginning of the
line.

This is where SimpleDebug comes to help. With SimpleDebug the above
would look like this:

				SD_PRINT("Control has reached this point!n");
				i = 3;
				SD_APPEND("i=%sn", i);
				SD_PRINTBUFFER();
				i++;

SimpleDebug is activated with the preprocessor symbol SIMPLE_DEBUG.
For easy use, place it permanently in the makefile, or as in the
example below. When you want to finish the program, just remove the
SIMPLE_DEBUG symbol and all debug information is erased from the final
executable - but always remains at your disposal when you need it!

Please see the included test program TestSimpleDebug for examples.


SimpleDebug has the following macros:

SD_SETUP /*Use these macros without curly braces, i.e. characters ().*/
SD_SETUP_EXTERNAL

Use these to setup the SimpleDebug environment. SD_SETUP is for the
module (file) which contains the main() routine, SD_SETUP_EXTERNAL is
for other modules. Notice that these two are not actual macros and
therefore they don't have the characters '()' after them. Use them
only outside of any routine, preferably right after having included
the SimpleDebug.h. E.g.

#define SIMPLE_DEBUG
#include <SimpleDebug/SimpleDebug.h>
SD_SETUP

SD_BEGIN(str, len)
SD_END()

These two are to be used in the function body. str in the name of the
routine and len is the length for the internal buffer where to put the
strings when using SD_APPEND() or SD_PRINT(). E.g. 

int Initialize(void) { 
	int rval = 0;
	SD_BEGIN("Initialize", 256);
	...
	SD_END();
	return(rval);
}

SD_PRINT(str)
SD_PRINTBUFFER()
SD_APPEND(fmt, attr)

These are the conditional printing commands. Use SD_PRINT(str) to 
simply print a line (always use 'n' to end the line). With 
SD_APPEND(fmt, attr) you can create a longer string with many
components, like with printf(). You can use many SD_APPEND()s
consecutively and then print the line with SD_PRINTBUFFER().
This also empties the buffer which was loaded with SD_APPEND().

SD_DO(code)

Conditional code.

SD_SET_GLOBALS(fh, ptr, amount, str)
SD_SET_LOCALS(fh, ptr, str)

Set globally or locally (in a function's body) the filehandle where
the printing is done or a pointer to a routine to do the printing, if
you need to print the debug information somewhere else, for example,
if you are debugging process which has no stdio (or a task in
AmigaOS), see SimpleDebugServer, a tool for this purpose. Amount is
the amount of indent (spaces taken when entering a function. Str is 
the prefix for the debug string when it is printed.

SD_ON()
SD_OFF()

With these two commands you can turn the printing of debug on and off
as needed, e.g. for testing only a particular routine. Notice that
these work only when SimpleDebug is active, i.e. when preprocessor
symbol SIMPLE_DEBUG has been defined. If SIMPLE_DEBUG has not been
defined, the whole SimpleDebug framework is deactivated.


INSTALLATION

An installation script for Amiga (Install) is provided. 
It does the same as is listed below:

Copy Include/SimpleDebug all to INCLUDE:SimpleDebug

SPECIAL NOTES ON AMIGA IMPLEMENTATION

SimpleDebugServer is an additional tool (not included with this
archive) for AmigaOS. With it you can print debug information even
from tasks (not processes) which don't have stdio and can't 
or don't want to open a file, e.g. device handlers.

THANKS


CONTACT

The author (Mikko Koivunalho) can be contacted at the email address
mikko.koivunalho@kolumbus.fi. Suggestions, improvements and critique
are welcome.