| 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 |
| 12 | |
| 13 | Classes, functions and macros: wxDebugContext, wxObject, wxLog, |
| 14 | @ref group_funcmacro_log, @ref group_funcmacro_debug |
| 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 group_funcmacro_debug 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 | |