1\section{Debugging overview}\label{debuggingoverview} 2 3Classes, functions and macros: \helpref{wxDebugContext}{wxdebugcontext}, \helpref{wxObject}{wxobject}, \helpref{wxLog}{wxlog}, 4\rtfsp\helpref{Log functions}{logfunctions}, \helpref{Debug macros}{debugmacros} 5 6Various classes, functions and macros are provided in wxWidgets to help you debug 7your application. Most of these are only available if you compile both wxWidgets, 8your application and {\it all} libraries that use wxWidgets with the \_\_WXDEBUG\_\_ symbol 9defined. You can also test the \_\_WXDEBUG\_\_ symbol in your own applications to execute 10code 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 15various static functions and variables. It allows you to dump all objects to that stream, write statistics about object allocation, and 16check memory for errors. 17 18It is good practice to define a \helpref{wxObject::Dump}{wxobjectdump} member function for each class you derive 19from a wxWidgets class, so that \helpref{wxDebugContext::Dump}{wxdebugcontextdump} can call it and 20give valuable information about the state of the application. 21 22If you have difficulty tracking down a memory leak, recompile 23in debugging mode and call \helpref{wxDebugContext::Dump}{wxdebugcontextdump} and \helpref{wxDebugContext::PrintStatistics}{wxdebugcontextprintstatistics} at 24appropriate places. They will tell you what objects have not yet been 25deleted, and what kinds of object they are. In fact, in debug mode wxWidgets will automatically 26detect memory leaks when your application is about to exit, and if there are any leaks, 27will give you information about the problem. (How much information depends on the operating system 28and compiler -- some systems don't allow all memory logging to be enabled). See the 29memcheck sample for example of usage. 30 31For wxDebugContext to do its work, the {\it new} and {\it delete}\rtfsp 32operators for wxObject have been redefined to store extra information 33about dynamically allocated objects (but not statically declared 34objects). This slows down a debugging version of an application, but can 35find difficult-to-detect memory leaks (objects are not 36deallocated), overwrites (writing past the end of your object) and 37underwrites (writing to memory in front of the object). 38 39If debugging mode is on and the symbols wxUSE\_GLOBAL\_MEMORY\_OPERATORS and 40wxUSE\_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 48All occurrences of 'new' in wxWidgets and your own application will use 49the overridden form of the operator with two extra arguments. This means that the debugging 50output (and error messages reporting memory problems) will tell you what 51file and on what line you allocated the object. Unfortunately not all 52compilers allow this definition to work properly, but most do. 53 54\wxheading{Debug macros} 55 56You should also use \helpref{debug macros}{debugmacros} as part of a `defensive programming' strategy, 57scattering wxASSERTs liberally to test for problems in your code as early as possible. Forward thinking 58will 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 61is not true. You can also use \helpref{wxASSERT\_MSG}{wxassertmsg} to supply your 62own 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 75The message box allows you to continue execution or abort the program. If you are running 76the application inside a debugger, you will be able to see exactly where the problem was. 77 78\wxheading{Logging functions} 79 80You can use the \helpref{wxLogDebug}{wxlogdebug} and \helpref{wxLogTrace}{wxlogtrace} functions to output debugging information in debug mode; 81it will do nothing for non-debugging code. 82 83\subsection{wxDebugContext overview}\label{wxdebugcontextoverview} 84 85\overview{Debugging overview}{debuggingoverview} 86 87Class: \helpref{wxDebugContext}{wxdebugcontext} 88 89wxDebugContext is a class for performing various debugging and memory tracing 90operations. 91 92This class has only static data and function members, and there should be 93no instances. Probably the most useful members are SetFile (for directing output 94to a file, instead of the default standard error or debugger output); 95Dump (for dumping the dynamically allocated objects) and PrintStatistics 96(for dumping information about allocation of objects). You can also call 97Check to check memory blocks for integrity. 98 99Here's an example of use. The SetCheckpoint ensures that only the 100allocations 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 115You can use wxDebugContext if \_\_WXDEBUG\_\_ is defined, or you can use it 116at any other time (if wxUSE\_DEBUG\_CONTEXT is set to 1 in setup.h). It is not disabled 117in non-debug mode because you may not wish to recompile wxWidgets and your entire application 118just to make use of the error logging facility. 119 120Note: wxDebugContext::SetFile has a problem at present, so use the default stream instead. 121Eventually the logging will be done through the wxLog facilities instead. 122 123