The Support Kit: Debugging Tools

Declared in: <support/Debug.h>

The Support Kit provides a set of macros that help you debug your application. These tools let you print information to standard output or to the serial port, and conditionally enter the debugger.

To enable the Support Kit's debugging tools you have to do two things:

  • Compile your code with the DEBUG compiler variable defined

  • Turn on the debug flag in your code through the SET_DEBUG_ENABLED() macro
  • These two acts represent, respectively, a compile time and a run time decision about the effectiveness of the debugging tools. The compile time decision overrides the run time decision: Turning on the debug flag (SET_DEBUG_ENABLED(TRUE) ) has no affect if the DEBUG variable isn't defined.


    The DEBUG Compiler Variable

    Defining the DEBUG compiler variable can be done by adding the following line to your makefile:

       USER_DEBUG_C_FLAGS := -DDEBUG

    (The MetroWerks IDE will undoubtedly supply a means for setting the DEBUG variable through its interface. Check your local papers.)

    When you're through debugging your application, simply remove the DEBUG definition and all of the debugging macros will be compiled away --you don't have to actually go into the code and remove the macros or comment them out.


    The Debug Flag

    The SET_DEBUG_ENABLED() macro turns on (or off) the debug flag. When you call a debugging tool, the state of the debugger flag is checked; if it's turned on, the tool does what it's designed to do (and, in with some tools, you could end up in the debugger). If the flag is off, the tool is ignored.

    Note: The debug flag is on by default. If you want to (initially, at least) turn it off, you should call SET_DEBUG_ENABLED(FALSE) as one of your first acts in main().

    The run time aspect of the debug flag is particularly convenient if your application is large and you want to concentrate on certain sections of the code. Note, however, that the scope of the flag is application-wide. You can't, for example, disable the debugging tools across an object's member functions by simply calling SET_DEBUG_ENABLED(FALSE ) in the object's constructor.


    Macros


    DEBUGGER(), ASSERT()

           DEBUGGER(var_args)
          ASSERT(condition)

    These macros cause your program to enter the debugger: DEBUGGER() always enters the debugger, ASSERT() enters if condition (which can be any normal C or C++ expression) evaluates to FALSE.

    DEBUGGER() takes a printf()-style variable-length argument that must be wrapped inside a second set of parentheses; for example:

       DEBUGGER(("What time is it?  %f\\n", system_time()));

    The argument is evaluated and printed in the debugger's shell.

    If ASSERT() enters the debugger, the following message is printed:

       Assert failed: File: filename, Line: number. condition

    Note that ASSERT()'s argument needn't be wrapped in a second set of parentheses.


    HEAP_STATS()

          HEAP_STATS()

    Prints, to standard out, a message that gives statistics about your application's memory heap. The message appears in this format:

       Heap Size: size bytes
       Used blocks: count (size bytes)
       Free blocks: count (size bytes)


    PRINT(), SERIAL_PRINT()

          PRINT(var_args)
          SERIAL_PRINT(var_args)

    These macros print the message given by var_args. The argument takes the variable argument form of a printf() call and must be wrapped inside a second set of parenthesis; for example:

       PRINT(("The time is %f\\n", system_time()));

    PRINT() sends the message to standard out; SERIAL_PRINT() to serial port 4 (the bottom-most serial port on the back of the computer).


    PRINT_OBJECT()

          PRINT_OBJECT(object)

    Prints information about the argument object (which must be a pointer to a C++ object) by calling the object's PrintToStream() function. The macro doesn't check to make sure that object actually implements the function, so you should use this macro with care.

    Object information is always printed to standard out (there isn't a serial port version of the call).


    SET_DEBUG_ENABLED(), IS_DEBUG_ENABLED()

          SET_DEBUG_ENABLED(flag)
          IS_DEBUG_ENABLED(void)

    The SET_DEBUG_ENABLED() macro sets the state of the run time debug flag: A TRUE argument turns it on, FALSE turns it off. The utility of the other debugging macros depends on the state of the debug flag: When the flag is on, the macros work; when it's off, they're ignored. The debug flag is set to TRUE by default.

    The debug flag is only meaningful if your code was compiled with the DEBUG compiler variable defined. Without the variable definition, the flag is always FALSE .

    IS_DEBUG_ENABLED() returns the current state of the debug flag.


    TRACE(), SERIAL_TRACE()

          TRACE(void)
          SERIAL_TRACE(void)

    These macros print the name of the source code file that contains the currently executing code (in other words, the file that contains the TRACE() call itself), the line number of the code, and the thread_id of the calling thread. The information is printed in this form:

         File: filename, Line: number, Thread: id

    TRACE() sends the message to standard out; SERIAL_TRACE() to serial port 4 (the bottom-most serial port on the back of the computer).






    The Be Book, HTML Edition, for Developer Release 8 of the Be Operating System.

    Copyright © 1996 Be, Inc. All rights reserved.

    Be, the Be logo, BeBox, BeOS, BeWare, and GeekPort are trademarks of Be, Inc.

    Last modified September 6, 1996.