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