]>
Commit | Line | Data |
---|---|---|
15b6757b | 1 | ///////////////////////////////////////////////////////////////////////////// |
d54cf7ff | 2 | // Name: debugging.h |
15b6757b | 3 | // Purpose: topic overview |
7d9550df VZ |
4 | // Author: Vadim Zeitlin |
5 | // Copyright: (c) 2009 Vadim Zeitlin <vadim@wxwidgets.org> | |
526954c5 | 6 | // Licence: wxWindows licence |
15b6757b FM |
7 | ///////////////////////////////////////////////////////////////////////////// |
8 | ||
880efa2a | 9 | /** |
36c9828f | 10 | |
928f1a07 | 11 | @page overview_debugging Debugging |
36c9828f | 12 | |
ce154616 BP |
13 | @tableofcontents |
14 | ||
15 | Various classes, functions and macros are provided in wxWidgets to help you | |
16 | debug your application. Assertion macros allow you to insert various checks in | |
17 | your application which can be compiled out or disabled in release builds but | |
18 | are extremely useful while developing. Logging functions are also provided | |
19 | which are useful for inserting traces into your application code as well as | |
20 | debugging. Both assertions and debug logging are also used by wxWidgets itself | |
21 | so you may encounter them even if you don't use either of these features | |
22 | yourself. | |
23 | ||
24 | @see wxLog, @ref group_funcmacro_log, @ref group_funcmacro_debug | |
d54cf7ff | 25 | |
7d9550df VZ |
26 | |
27 | ||
ce154616 | 28 | @section overview_debugging_config Configuring Debug Support |
7d9550df VZ |
29 | |
30 | Starting with wxWidgets 2.9.1 debugging features are always available by | |
31 | default (and not only in a special "debug" build of the library) and you need | |
32 | to predefine wxDEBUG_LEVEL symbol as 0 when building both the library and your | |
33 | application to remove them completely from the generated object code. However | |
34 | the debugging features are disabled by default when the application itself is | |
35 | built with @c NDEBUG defined (i.e. in "release" or "production" mode) so there | |
36 | is no need to do this, unless the resources of the system your application will | |
37 | be running on are unusually constrained (notice that when asserts are disabled | |
38 | their condition is not even evaluated so the only run-time cost is a single | |
39 | condition check and the extra space taken by the asserts in the code). | |
40 | ||
41 | This automatic deactivation of debugging code is done by IMPLEMENT_APP() macro | |
42 | so if you don't use you may need to explicitly call wxDISABLE_DEBUG_SUPPORT() | |
43 | yourself. | |
44 | ||
45 | Also notice that it is possible to build your own application with a different | |
46 | value of wxDEBUG_LEVEL than the one which was used for wxWidgets itself. E.g. | |
ce154616 BP |
47 | you may be using an official binary version of the library which will have been |
48 | compiled with default @code wxDEBUG_LEVEL == 1 @endcode but still predefine | |
7d9550df VZ |
49 | wxDEBUG_LEVEL as 0 for your own code. |
50 | ||
51 | On the other hand, if you do want to keep the asserts even in production | |
52 | builds, you will probably want to override the handling of assertion failures | |
53 | as the default behaviour which pops up a message box notifying the user about | |
54 | the problem is usually inappropriate. Use wxSetAssertHandler() to set up your | |
55 | own custom function which should be called instead of the standard assertion | |
56 | failure handler. Such function could log an appropriate message in the | |
57 | application log file or maybe notify the user about the problem in some more | |
58 | user-friendly way. | |
59 | ||
60 | ||
ce154616 BP |
61 | |
62 | @section overview_debugging_dbgmacros Assertion Macros | |
7d9550df VZ |
63 | |
64 | wxASSERT(), wxFAIL(), wxCHECK() as well as their other variants (see @ref | |
65 | group_funcmacro_debug) are similar to the standard assert() macro but are more | |
66 | flexible and powerful. The first of them is equivalent to assert() itself, i.e. | |
67 | it simply checks a condition and does nothing if it is true. The second one is | |
68 | equivalent to checking an always false condition and is supposed to be used for | |
69 | code paths which are supposed to be inaccessible (e.g. @c default branch of a | |
70 | @c switch statement which should never be executed). Finally, the wxCHECK() | |
71 | family of macros verifies the condition just as wxASSERT() does and performs | |
72 | some action such returning from the function if it fails -- thus, it is useful | |
73 | for checking the functions preconditions. | |
74 | ||
75 | All of the above functions exist in @c _MSG variants which allow you to provide | |
76 | a custom message which will be shown (or, more generally, passed to the assert | |
77 | handler) if the assertion fails, in addition to the usual file and line number | |
78 | information and the condition itself. | |
79 | ||
80 | Example of using an assertion macro: | |
928f1a07 | 81 | @code |
7d9550df | 82 | void GetTheAnswer(int *p) |
928f1a07 | 83 | { |
7d9550df | 84 | wxCHECK_RET( p, "pointer can't be NULL in GetTheAnswer()" ); |
36c9828f | 85 | |
7d9550df | 86 | *p = 42; |
928f1a07 FM |
87 | }; |
88 | @endcode | |
36c9828f | 89 | |
7d9550df VZ |
90 | If the condition is false, i.e. @c p is @NULL, the assertion handler is called |
91 | and, in any case (even when wxDEBUG_LEVEL is 0), the function returns without | |
92 | dereferencing the NULL pointer on the next line thus avoiding a crash. | |
93 | ||
94 | The default assertion handler behaviour depends on whether the application | |
95 | using wxWidgets was compiled in release build (with @c NDEBUG defined) or debug | |
96 | one (without) but may be changed in either case as explained above. If it | |
97 | wasn't changed, then nothing will happen in the release build and a message box | |
98 | showing the information about the assert as well as allowing to stop the | |
99 | program, ignore future asserts or break into the debugger is shown. On the | |
100 | platforms where wxStackWalker is supported the message box will also show the | |
101 | stack trace at the moment when the assert failed often allowing you to diagnose | |
102 | the problem without using the debugger at all. You can see an example of such | |
103 | message box in the @ref page_samples_except. | |
36c9828f FM |
104 | |
105 | ||
36c9828f | 106 | |
ce154616 | 107 | @section overview_debugging_logging Logging Functions |
d54cf7ff | 108 | |
ce154616 BP |
109 | You can use the wxLogDebug and wxLogTrace functions to output debugging |
110 | information in debug mode; it will do nothing for non-debugging code. | |
d54cf7ff | 111 | |
d54cf7ff | 112 | */ |