docs/doxygen/overviews/debugging.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        debugging
   3 // Purpose:     topic overview
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /*!
  10
  11  @page debugging_overview Debugging overview
  12
  13  Classes, functions and macros: #wxDebugContext, #wxObject, #wxLog,
  14  @ref logfunctions_overview, @ref debugmacros_overview
  15  Various classes, functions and macros are provided in wxWidgets to help you debug
  16  your application. Most of these are only available if you compile both wxWidgets,
  17  your application and @e all libraries that use wxWidgets with the __WXDEBUG__ symbol
  18  defined. You can also test the __WXDEBUG__ symbol in your own applications to execute
  19  code that should be active only in debug mode.
  20  @b wxDebugContext
  21  #wxDebugContext is a class that never gets instantiated, but ties together
  22  various static functions and variables. It allows you to dump all objects to that stream, write statistics about object allocation, and
  23  check memory for errors.
  24  It is good practice to define a wxObject::Dump member function for each class you derive
  25  from a wxWidgets class, so that wxDebugContext::Dump can call it and
  26  give valuable information about the state of the application.
  27  If you have difficulty tracking down a memory leak, recompile
  28  in debugging mode and call wxDebugContext::Dump and wxDebugContext::PrintStatistics at
  29  appropriate places. They will tell you what objects have not yet been
  30  deleted, and what kinds of object they are. In fact, in debug mode wxWidgets will automatically
  31  detect memory leaks when your application is about to exit, and if there are any leaks,
  32  will give you information about the problem. (How much information depends on the operating system
  33  and compiler -- some systems don't allow all memory logging to be enabled). See the
  34  memcheck sample for example of usage.
  35  For wxDebugContext to do its work, the @e new and @e delete
  36  operators for wxObject have been redefined to store extra information
  37  about dynamically allocated objects (but not statically declared
  38  objects). This slows down a debugging version of an application, but can
  39  find difficult-to-detect memory leaks (objects are not
  40  deallocated), overwrites (writing past the end of your object) and
  41  underwrites (writing to memory in front of the object).
  42  If debugging mode is on and the symbols wxUSE_GLOBAL_MEMORY_OPERATORS and
  43  wxUSE_DEBUG_NEW_ALWAYS are set to 1 in setup.h, 'new' is defined to be:
  44
  45
  46  @code
  47  #define new new(__FILE__,__LINE__)
  48  @endcode
  49
  50  All occurrences of 'new' in wxWidgets and your own application will use
  51  the overridden form of the operator with two extra arguments. This means that the debugging
  52  output (and error messages reporting memory problems) will tell you what
  53  file and on what line you allocated the object. Unfortunately not all
  54  compilers allow this definition to work properly, but most do.
  55  @b Debug macros
  56  You should also use @ref debugmacros_overview as part of a 'defensive programming' strategy,
  57  scattering wxASSERTs liberally to test for problems in your code as early as possible. Forward thinking
  58  will save a surprising amount of time in the long run.
  59  #wxASSERT is used to pop up an error message box when a condition
  60  is not @true. You can also use #wxASSERT_MSG to supply your
  61  own helpful error message. For example:
  62
  63
  64  @code
  65  void MyClass::MyFunction(wxObject* object)
  66    {
  67        wxASSERT_MSG( (object != @NULL), "object should not be @NULL in MyFunction!" );
  68
  69        ...
  70    };
  71  @endcode
  72
  73
  74  The message box allows you to continue execution or abort the program. If you are running
  75  the application inside a debugger, you will be able to see exactly where the problem was.
  76  @b Logging functions
  77  You can use the #wxLogDebug and #wxLogTrace functions to output debugging information in debug mode;
  78  it will do nothing for non-debugging code.
  79  @ref debugcontext_overview
  80
  81
  82  @section wxdebugcontextoverview wxDebugContext overview
  83
  84  @ref debugging_overview
  85  Class: #wxDebugContext
  86  wxDebugContext is a class for performing various debugging and memory tracing
  87  operations.
  88  This class has only static data and function members, and there should be
  89  no instances. Probably the most useful members are SetFile (for directing output
  90  to a file, instead of the default standard error or debugger output);
  91  Dump (for dumping the dynamically allocated objects) and PrintStatistics
  92  (for dumping information about allocation of objects). You can also call
  93  Check to check memory blocks for integrity.
  94  Here's an example of use. The SetCheckpoint ensures that only the
  95  allocations done after the checkpoint will be dumped.
  96
  97  @code
  98  wxDebugContext::SetCheckpoint();
  99
 100    wxDebugContext::SetFile("c:\\temp\\debug.log");
 101
 102    wxString *thing = new wxString;
 103
 104    char *ordinaryNonObject = new char[1000];
 105
 106    wxDebugContext::Dump();
 107    wxDebugContext::PrintStatistics();
 108  @endcode
 109
 110  You can use wxDebugContext if __WXDEBUG__ is defined, or you can use it
 111  at any other time (if wxUSE_DEBUG_CONTEXT is set to 1 in setup.h). It is not disabled
 112  in non-debug mode because you may not wish to recompile wxWidgets and your entire application
 113  just to make use of the error logging facility.
 114  Note: wxDebugContext::SetFile has a problem at present, so use the default stream instead.
 115  Eventually the logging will be done through the wxLog facilities instead.
 116
 117  */
 118
 119