ClanLib includes a class called CL_CrashReporter that help doing post-mortem debugging of a ClanLib application. Post-mortem debugging is a method to debug an application that crashes at the customer site - or in general when its in production and not running on a developers computer with access to Just-In-Time (JIT) debugging.

Note: For the time being, this class only does anything on Windows with Microsoft Visual Studio.NET 2002 or later. If compiled with any other tool it will simply do nothing.

Microsoft originally introduced this form of debugging as part of NT 4. When an application crashes on this platform, a program calling itself "Dr Watson" appears and produces a memory dump of the application that crashed. This tool has then been further improved in Windows XP. Generally Microsoft discovered that a complete memory dump of an application could be huge, and in the majority of cases you'd be able to figure out the source of the problem by using a 'mini dump' instead. In Windows XP "Dr Watson" still exist, but now it appears far more integrated with Windows. Thanks to the now much smaller minidump files, "Dr Watson" is able to send dumps of applications for analysis at Microsoft. No doubt this have helped Microsoft find race conditions and other more rare and subtile bugs in their systems.

The good news is that Microsoft decided to make this possible for not only themselves, but for anyone else as well. Windows XP ships a redistributable dbghelp.dll library that contain functions that can produce a minidump of a running application. Such a produced minidump file can then be loaded into MSVC7's Visual Studio debugger for analysis. Combined with program database files (.pdb) built for the executable, it is able to point exactly at the source code line where the application crashed, show the call stack of all threads as it appeared when it crashed, local stack variables visible as well. Not every variable in the application is visible (its a mini dump, not a complete memory dump), but despite this it really narrows it down what could be causing the error in the first place.

To enable post-mortem debugging in your application, you must perform the following steps:

1. Create a CL_CrashReporter instance in every thread you wish to enable post-mortem debugging for. Avoid to destroying it until the shutdown of the thread, since the post-mortem debugging will only be enabled as long as there's an instance of the crash reporter.

2. Link up against clanCore.lib for release builds, and clanCored.lib for debug builds.

3. Enable debug information for release builds. This is enabled by entering the Project Settings dialogs for each project, going to the C++ tab and finding the Debug info, putting it to "Program Database". Don't set it to Program Database with Edit and Continue. Then go to the Linker tab and enable debug info there as well.

4. That's it!

Enabling debug information will not slow down the application, it just means it will produce program database files (pdb) files for release builds.

Note:: You can skip step 1 in any thread created by ClanLib: the main thread for CL_ClanApplication apps, and any thread created by CL_Thread. ClanLib internally constructs a crash reporter object for you.

After rebuilding your application and any libraries you might want to be able to have debug information about, you should get a set of pdb files (one for the exe, one for each library you enabled debug info in) along your application.

Send the exe to the customer, and save the pdb files locally somewhere.

When the application crashes, the crash reporter will generate a dump-1234.dmp file, where 1234 is the thread ID of the thread that crashed. Get the customer to send back this file to you.

You are now ready to debug the application from the point it crashed. Put the exe and its dll's and the pdb files generated when you built it into a common directory, along with the minidump (.dmp) file. Then doubleclick the dmp file as if it was a Visual Studio project. After Developer Studio has launched, hit F5 to start the debugging.

Make sure you ship the imagehlp.dll and dbghelp.dll that come with Windows XP along your application. Post-mortem debugging is only supported by the latest versions of those dlls, so any OS older than WinXP will need those updated dlls.