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 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.