docs/doxygen/overviews/debugging.h

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