Debian Codegraph @

Documentation/Overview/crash_reporter.xml

raw
1 <xml>
2 <head>
3 <title>ClanLib Crash Reporter</title>
4 </head>
5 <body>
6
7 <p>ClanLib includes a class called CL_CrashReporter that help doing
8 post-mortem debugging of a ClanLib application. Post-mortem debugging is a
9 method to debug an application that crashes at the customer site - or in
10 general when its in production and not running on a developers computer with
11 access to Just-In-Time (JIT) debugging.</p>
12
13 <p><i>Note</i>: For the time being, this class only does anything on Windows with
14 Microsoft Visual Studio.NET 2002 or later. If compiled with any other tool
15 it will simply do nothing.</p>
16
17 <!--
18 <p>To compile CrashReporter on win32 using MSVC6 you need the "Debugging Tools"
19 library. Without this library while trying to compile clanCore the compiler
20 will spit out some errors similar to:</p>
21
22 <p>C:\ClanLib\Sources\Core\System\Win32\crash_reporter_win32.h(127) : error
23 +C2061: syntax error : identifier 'MINIDUMP_TYPE'</p>
24
25 <p>Download it from:<br/>
26 http://www.microsoft.com/whdc/ddk/debugging/installx86.mspx</p>
27
28 <p>The "Debugging Tools" are also part of the Microsoft Platform SDK, which
29 will be better to install if you dont mind the larger download (you will get
30 a much newer set of include files and libraries, making it possible to use
31 things Microsoft invented since 1998). </p>
32
33 <p>The Microsoft Platform SDK is available at:
34 http://www.microsoft.com/msdownload/platformsdk/sdkupdate/</p>
35
36 <p>IMPORTANT: After installing one of those two packages mentioned above, make
37 sure that the installed package is mentioned before the msvc6 header in the
38 include and library paths in the Tools->Options menu.</p>
39 -->
40
41 <p>Microsoft originally introduced this form of debugging as part of NT 4.
42 When an application crashes on this platform, a program calling itself "Dr
43 Watson" appears and produces a memory dump of the application that crashed.
44 This tool has then been further improved in Windows XP. Generally Microsoft
45 discovered that a complete memory dump of an application could be huge, and
46 in the majority of cases you'd be able to figure out the source of the
47 problem by using a 'mini dump' instead. In Windows XP "Dr Watson" still
48 exist, but now it appears far more integrated with Windows. Thanks to the
49 now much smaller minidump files, "Dr Watson" is able to send dumps of
50 applications for analysis at Microsoft. No doubt this have helped Microsoft
51 find race conditions and other more rare and subtile bugs in their
52 systems.</p>
53
54 <p>The good news is that Microsoft decided to make this possible for not
55 only themselves, but for anyone else as well. Windows XP ships a
56 redistributable dbghelp.dll library that contain functions that can produce
57 a minidump of a running application. Such a produced minidump file can then
58 be loaded into MSVC7's Visual Studio debugger for analysis. Combined with
59 program database files (.pdb) built for the executable, it is able to point
60 exactly at the source code line where the application crashed, show the call
61 stack of all threads as it appeared when it crashed, local stack variables
62 visible as well. Not every variable in the application is visible (its a
63 mini dump, not a complete memory dump), but despite this it really narrows
64 it down what could be causing the error in the first place.</p>
65
66 <p>To enable post-mortem debugging in your application, you must perform the
67 following steps:</p>
68
69 <ol>
70 <li>
71 <p>Create a CL_CrashReporter instance in every thread you wish to enable
72 post-mortem debugging for. Avoid to destroying it until the shutdown of
73 the thread, since the post-mortem debugging will only be enabled as long as
74 there's an instance of the crash reporter.</p>
75 </li>
76 <li>
77 <p>Link up against clanCore.lib for release builds, and clanCored.lib
78 for debug builds.</p>
79 </li>
80 <li>
81 <p>Enable debug information for release builds. This is enabled by entering
82 the Project Settings dialogs for each project, going to the C++ tab and
83 finding the Debug info, putting it to "Program Database". Don't set it to
84 Program Database with Edit and Continue. Then go to the Linker tab and
85 enable debug info there as well.</p>
86 </li>
87 <li>
88 <p>
89 That's it!
90 </p>
91 </li>
92 </ol>
93
94 <p>Enabling debug information will not slow down the application, it just
95 means it will produce program database files (pdb) files for release builds.</p>
96
97 <p><i>Note:</i>: You can skip step 1 in any thread created by ClanLib: the
98 main thread for CL_ClanApplication apps, and any thread created by
99 CL_Thread. ClanLib internally constructs a crash reporter object for
100 you.</p>
101
102 <p>After rebuilding your application and any libraries you might want to be
103 able to have debug information about, you should get a set of pdb files
104 (one for the exe, one for each library you enabled debug info in) along
105 your application.</p>
106
107 <p>Send the exe to the customer, and save the pdb files locally somewhere.</p>
108
109 <p>When the application crashes, the crash reporter will generate a
110 dump-1234.dmp file, where 1234 is the thread ID of the thread that crashed.
111 Get the customer to send back this file to you.</p>
112
113 <p>You are now ready to debug the application from the point it crashed. Put
114 the exe and its dll's and the pdb files generated when you built it into a
115 common directory, along with the minidump (.dmp) file. Then doubleclick the
116 dmp file as if it was a Visual Studio project. After Developer Studio has
117 launched, hit F5 to start the debugging.</p>
118
119 <p>Make sure you ship the imagehlp.dll and dbghelp.dll that come with
120 <i>Windows XP</i> along your application. Post-mortem debugging is only
121 supported by the latest versions of those dlls, so any OS older than WinXP
122 will need those updated dlls.</p>
123
124 </body>
125 </xml>