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 license
   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