Debugging overview

Classes, functions and macros: wxDebugContext, wxObject, wxLog, Log functions, Debug macros

Various classes, functions and macros are provided in wxWidgets to help you debug your application. Most of these are only available if you compile both wxWidgets, your application and all libraries that use wxWidgets with the __WXDEBUG__ symbol defined. You can also test the __WXDEBUG__ symbol in your own applications to execute code that should be active only in debug mode.

wxDebugContext

wxDebugContext is a class that never gets instantiated, but ties together various static functions and variables. It allows you to dump all objects to that stream, write statistics about object allocation, and check memory for errors.

It is good practice to define a wxObject::Dump member function for each class you derive from a wxWidgets class, so that wxDebugContext::Dump can call it and give valuable information about the state of the application.

If you have difficulty tracking down a memory leak, recompile in debugging mode and call wxDebugContext::Dump and wxDebugContext::PrintStatistics at appropriate places. They will tell you what objects have not yet been deleted, and what kinds of object they are. In fact, in debug mode wxWidgets will automatically detect memory leaks when your application is about to exit, and if there are any leaks, will give you information about the problem. (How much information depends on the operating system and compiler -- some systems don't allow all memory logging to be enabled). See the memcheck sample for example of usage.

For wxDebugContext to do its work, the new and delete operators for wxObject have been redefined to store extra information about dynamically allocated objects (but not statically declared objects). This slows down a debugging version of an application, but can find difficult-to-detect memory leaks (objects are not deallocated), overwrites (writing past the end of your object) and underwrites (writing to memory in front of the object).

If debugging mode is on and the symbols wxUSE_GLOBAL_MEMORY_OPERATORS and wxUSE_DEBUG_NEW_ALWAYS are set to 1 in setup.h, 'new' is defined to be:

#define new new(__FILE__,__LINE__)

Debug macros

You should also use debug macros as part of a 'defensive programming' strategy, scattering wxASSERTs liberally to test for problems in your code as early as possible. Forward thinking will save a surprising amount of time in the long run.

wxASSERT is used to pop up an error message box when a condition is not true. You can also use wxASSERT_MSG to supply your own helpful error message. For example:

  void MyClass::MyFunction(wxObject* object)
  {
      wxASSERT_MSG( (object != NULL), "object should not be NULL in MyFunction!" );

      ...
  };

The message box allows you to continue execution or abort the program. If you are running the application inside a debugger, you will be able to see exactly where the problem was.

Logging functions

You can use the wxLogDebug and wxLogTrace functions to output debugging information in debug mode; it will do nothing for non-debugging code.

wxDebugContext overview

wxDebugContext overview

Debugging overview

Class: wxDebugContext

wxDebugContext is a class for performing various debugging and memory tracing operations.

This class has only static data and function members, and there should be no instances. Probably the most useful members are SetFile (for directing output to a file, instead of the default standard error or debugger output); Dump (for dumping the dynamically allocated objects) and PrintStatistics (for dumping information about allocation of objects). You can also call Check to check memory blocks for integrity.

Here's an example of use. The SetCheckpoint ensures that only the allocations done after the checkpoint will be dumped.

  wxDebugContext::SetCheckpoint();

  wxDebugContext::SetFile("c:\\temp\\debug.log");

  wxString *thing = new wxString;

  char *ordinaryNonObject = new char[1000];

  wxDebugContext::Dump();
  wxDebugContext::PrintStatistics();

Note: wxDebugContext::SetFile has a problem at present, so use the default stream instead. Eventually the logging will be done through the wxLog facilities instead.