1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<title>wxWidgets: Debugging</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
<link href="extra_stylesheet.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<div id="page_container">
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0" style="width: 100%;">
<tbody>
<tr>
<td id="projectlogo">
<a href="http://www.wxwidgets.org/" target="_new">
<img alt="wxWidgets" src="logo.png"/>
</a>
</td>
<td style="padding-left: 0.5em; text-align: right;">
<span id="projectnumber">Version: 3.0.2</span>
</td>
</tr>
</tbody>
</table>
</div>
<!-- Generated by Doxygen 1.8.2 -->
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Categories</span></a></li>
<li><a href="annotated.html"><span>Classes</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="index.html">Documentation</a></li><li class="navelem"><a class="el" href="page_topics.html">Programming Guides</a></li> </ul>
</div>
</div><!-- top -->
<div class="header">
<div class="headertitle">
<div class="title">Debugging </div> </div>
</div><!--header-->
<div class="contents">
<div class="toc"><h3>Table of Contents</h3>
<ul><li class="level1"><a href="#overview_debugging_config">Configuring Debug Support</a></li>
<li class="level1"><a href="#overview_debugging_dbgmacros">Assertion Macros</a></li>
<li class="level1"><a href="#overview_debugging_logging">Logging Functions</a></li>
</ul>
</div>
<div class="textblock"><p>Various classes, functions and macros are provided in wxWidgets to help you debug your application.</p>
<p>Assertion macros allow you to insert various checks in your application which can be compiled out or disabled in release builds but are extremely useful while developing. Logging functions are also provided which are useful for inserting traces into your application code as well as debugging. Both assertions and debug logging are also used by wxWidgets itself so you may encounter them even if you don't use either of these features yourself.</p>
<dl class="section see"><dt>See Also</dt><dd><a class="el" href="classwx_log.html" title="wxLog class defines the interface for the log targets used by wxWidgets logging functions as explaine...">wxLog</a>, <a class="el" href="group__group__funcmacro__log.html">Logging</a>, <a class="el" href="group__group__funcmacro__debug.html">Debugging macros</a></dd></dl>
<h1><a class="anchor" id="overview_debugging_config"></a>
Configuring Debug Support</h1>
<p>Starting with wxWidgets 2.9.1 debugging features are always available by default (and not only in a special "debug" build of the library) and you need to predefine wxDEBUG_LEVEL symbol as 0 when building both the library and your application to remove them completely from the generated object code. However the debugging features are disabled by default when the application itself is built with <code>NDEBUG</code> defined (i.e. in "release" or "production" mode) so there is no need to do this, unless the resources of the system your application will be running on are unusually constrained (notice that when asserts are disabled their condition is not even evaluated so the only run-time cost is a single condition check and the extra space taken by the asserts in the code).</p>
<p>This automatic deactivation of debugging code is done by IMPLEMENT_APP() macro so if you don't use you may need to explicitly call <a class="el" href="group__group__funcmacro__debug.html#ga8db18cbe95b3b42c3017a8bf048b0839" title="Use this macro to disable all debugging code in release build when not using wxIMPLEMENT_APP().">wxDISABLE_DEBUG_SUPPORT()</a> yourself.</p>
<p>Also notice that it is possible to build your own application with a different value of wxDEBUG_LEVEL than the one which was used for wxWidgets itself. E.g. you may be using an official binary version of the library which will have been compiled with default </p>
<div class="fragment"><div class="line"><a class="code" href="group__group__funcmacro__debug.html#ga7ce424d27d39bb92c26c80b6a1903725" title="Preprocessor symbol defining the level of debug support available.">wxDEBUG_LEVEL</a> == 1 </div>
</div><!-- fragment --><p> but still predefine wxDEBUG_LEVEL as 0 for your own code.</p>
<p>On the other hand, if you do want to keep the asserts even in production builds, you will probably want to override the handling of assertion failures as the default behaviour which pops up a message box notifying the user about the problem is usually inappropriate. Use <a class="el" href="group__group__funcmacro__debug.html#ga7a8443c97e45d2943f03769aaa787376" title="Sets the function to be called in case of assertion failure.">wxSetAssertHandler()</a> to set up your own custom function which should be called instead of the standard assertion failure handler. Such function could log an appropriate message in the application log file or maybe notify the user about the problem in some more user-friendly way.</p>
<h1><a class="anchor" id="overview_debugging_dbgmacros"></a>
Assertion Macros</h1>
<p><a class="el" href="group__group__funcmacro__debug.html#ga204cc264ee560b67e6c6467ba8ffee5f" title="Assert macro.">wxASSERT()</a>, <a class="el" href="group__group__funcmacro__debug.html#gaa5b456751cd8c71e9a787fba16ecbd68" title="Will always generate an assert error if this code is reached (in debug mode).">wxFAIL()</a>, <a class="el" href="group__group__funcmacro__debug.html#gacce4d688e56d4de1bbef692e7df2e3e3" title="Checks that the condition is true, returns with the given return value if not (stops execution in deb...">wxCHECK()</a> as well as their other variants (see <a class="el" href="group__group__funcmacro__debug.html">Debugging macros</a>) are similar to the standard assert() macro but are more flexible and powerful. The first of them is equivalent to assert() itself, i.e. it simply checks a condition and does nothing if it is true. The second one is equivalent to checking an always false condition and is supposed to be used for code paths which are supposed to be inaccessible (e.g. <code>default</code> branch of a <code>switch</code> statement which should never be executed). Finally, the <a class="el" href="group__group__funcmacro__debug.html#gacce4d688e56d4de1bbef692e7df2e3e3" title="Checks that the condition is true, returns with the given return value if not (stops execution in deb...">wxCHECK()</a> family of macros verifies the condition just as <a class="el" href="group__group__funcmacro__debug.html#ga204cc264ee560b67e6c6467ba8ffee5f" title="Assert macro.">wxASSERT()</a> does and performs some action such returning from the function if it fails – thus, it is useful for checking the functions preconditions.</p>
<p>All of the above functions exist in <code>_MSG</code> variants which allow you to provide a custom message which will be shown (or, more generally, passed to the assert handler) if the assertion fails, in addition to the usual file and line number information and the condition itself.</p>
<p>Example of using an assertion macro: </p>
<div class="fragment"><div class="line"><span class="keywordtype">void</span> GetTheAnswer(<span class="keywordtype">int</span> *p)</div>
<div class="line">{</div>
<div class="line"> <a class="code" href="group__group__funcmacro__debug.html#ga0cf2ca7d7ff0107197e51e6b434fd0bd" title="Checks that the condition is true, and returns if not (stops execution with the given error message i...">wxCHECK_RET</a>( p, <span class="stringliteral">"pointer can't be NULL in GetTheAnswer()"</span> );</div>
<div class="line"></div>
<div class="line"> *p = 42;</div>
<div class="line">};</div>
</div><!-- fragment --><p>If the condition is false, i.e. <code>p</code> is <span class="literal">NULL</span>, the assertion handler is called and, in any case (even when wxDEBUG_LEVEL is 0), the function returns without dereferencing the NULL pointer on the next line thus avoiding a crash.</p>
<p>The default assertion handler behaviour depends on whether the application using wxWidgets was compiled in release build (with <code>NDEBUG</code> defined) or debug one (without) but may be changed in either case as explained above. If it wasn't changed, then nothing will happen in the release build and a message box showing the information about the assert as well as allowing to stop the program, ignore future asserts or break into the debugger is shown. On the platforms where <a class="el" href="classwx_stack_walker.html" title="wxStackWalker allows an application to enumerate, or walk, the stack frames (the function callstack)...">wxStackWalker</a> is supported the message box will also show the stack trace at the moment when the assert failed often allowing you to diagnose the problem without using the debugger at all. You can see an example of such message box in the <a class="el" href="page_samples.html#page_samples_except">Exception Sample</a>.</p>
<h1><a class="anchor" id="overview_debugging_logging"></a>
Logging Functions</h1>
<p>You can use the wxLogDebug and wxLogTrace functions to output debugging information in debug mode; it will do nothing for non-debugging code. </p>
</div></div><!-- contents -->
<address class="footer">
<small>
Generated on Thu Nov 27 2014 13:46:42 for wxWidgets by <a href="http://www.doxygen.org/index.html" target="_new">Doxygen</a> 1.8.2
</small>
</address>
<script src="wxwidgets.js" type="text/javascript"></script>
</div><!-- #page_container -->
</body>
</html>
|
