docs/latex/wx/tdebug.tex

   1 \section{Debugging overview}\label{debuggingoverview}
   2
   3 Classes: \helpref{wxDebugContext}{wxdebugcontext}, \helpref{wxDebugStreamBuf}{wxdebugstreambuf},
   4 \rtfsp\helpref{wxObject}{wxobject}
   5
   6 Various classes, functions and macros are provided in wxWindows to help you debug
   7 your application. Most of these are only available if you compile both wxWindows,
   8 your application and {\it all} libraries that use wxWindows with the DEBUG flag
   9 set to 1 or more.
  10
  11 wxDebugContext is a class that never gets instantiated, but ties together
  12 various functions and variables. It allows you to set the debugging stream, dump
  13 all objects to that stream, write statistics about object allocation, and
  14 check memory for errors.
  15
  16 You can use the \helpref{WXTRACE}{trace} macro to output debugging information in DEBUG mode;
  17 it will be defined to nothing for non-debugging code.
  18
  19 It is good practice to define a Dump member function for each class you derive
  20 from a wxWindows class, so that wxDebugContext::Dump can call it and
  21 give valuable information about the state of the application.
  22
  23 For wxDebugContext to do its work, the {\it new} and {\it delete}\rtfsp
  24 operators for wxObject have been redefined to store extra information
  25 about dynamically allocated objects (but not statically declared
  26 objects). This slows down a debugging version of an application, but can
  27 in theory find difficult-to-detect memory leaks (objects are not
  28 deallocated), overwrites (writing past the end of your object) and
  29 underwrites (writing to memory in front of the object).
  30
  31 If you have difficulty tracking down a memory leak, recompile
  32 in debugging mode and call wxDebugContext::Dump and wxDebugContext::Statistics
  33 at appropriate places. They will tell you what objects have not yet been
  34 deleted, and what kinds of object they are.
  35
  36 If you use the macro WXDEBUG\_NEW instead of the normal 'new', the debugging
  37 output (and error messages reporting memory problems) will also tell you what
  38 file and on what line you allocated the object.
  39
  40 To avoid the need for replacing existing new operators with WXDEBUG\_NEW, you
  41 can write this at the top of each application file:
  42
  43 \begin{verbatim}
  44 #define new WXDEBUG\_NEW
  45 \end{verbatim}
  46
  47 In non-debugging mode, this will revert to the usual interpretation
  48 of new. Note that for this not to mess up new-based allocation of non-wxObject derived classes and
  49 built-in types, there are global definitions of new and delete which match
  50 the syntax required for storing filename and line numbers. These merely
  51 call malloc and free, and so do not do anything interesting. The definitions
  52 may possibly cause multiple symbol problems for some compilers and so might
  53 need to be omitted by setting the USE\_GLOBAL\_MEMORY\_OPERATORS to 0 in wx\_setup.h
  54
  55 \subsection{wxDebugContext overview}\label{wxdebugcontextoverview}
  56
  57 \overview{Debugging overview}{debuggingoverview}
  58
  59 Class: \helpref{wxDebugContext}{wxdebugcontext}
  60
  61 wxDebugContext is a class for performing various debugging and memory tracing
  62 operations. wxDebugContext, and the related macros and function WXTRACE and
  63 wxTrace, are only present if USE\_DEBUG\_CONTEXT is used.
  64
  65 This class has only static data and function members, and there should be
  66 no instances. Probably the most useful members are SetFile (for directing output
  67 to a file, instead of the default standard error or debugger output);
  68 Dump (for dumping the dynamically allocated objects) and PrintStatistics
  69 (for dumping information about allocation of objects). You can also call
  70 Check to check memory blocks for integrity.
  71
  72 Here's an example of use. The SetCheckpoint ensures that only the
  73 allocations done after the checkpoint will be dumped. Unfortunately
  74 the define of new to WXDEBUG\_NEW does not work for Borland C++ (and
  75 perhaps other compilers) because it fails to find the correct overloaded
  76 operator for non-object usage of new. Instead, you need to use WXDEBUG\_NEW
  77 explicitly if there are any examples of non-object new usage in the file.
  78
  79 \begin{verbatim}
  80 #define new WXDEBUG_NEW
  81
  82   wxDebugContext::SetCheckpoint();
  83
  84   wxDebugContext::SetFile("c:\\temp\\debug.log");
  85
  86   wxString *thing = new wxString;
  87
  88   // Proves that defining 'new' to be 'WXDEBUG_NEW' doesn't mess up
  89   // non-object allocation. Doesn't work for Borland C++.
  90   char *ordinaryNonObject = new char[1000];
  91
  92   wxDebugContext::Dump();
  93   wxDebugContext::PrintStatistics();
  94 \end{verbatim}
  95
  96 You can use wxDebugContext if DEBUG is 1 or more, or you can use it
  97 at any other time (if USE\_DEBUG\_CONTEXT is 1). It is not disabled
  98 for DEBUG = 1 (as in earlier versions of wxWindows) because you
  99 may not wish to recompile wxWindows and your entire application
 100 just to make use of the error logging facility. This is especially
 101 true in a Windows NT or Windows 95 environment, where you cannot
 102 easily output to a debug window: wxDebugContext can be used to
 103 write to log files instead.
 104