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