| 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 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 \_\_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 wxWindows 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 wxWindows 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 symbol wxUSE\_GLOBAL\_MEMORY\_OPERATORS is set |
| 40 | 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 wxWindows 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 wxWindows 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 | |