docs/latex/wx/tdebug.tex

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