The following instructions don't require you to be a software developer, but not all of you may want to go through the details and modify their systems as required for providing detailed debug infos to David Harris. Anyway, if you encounter debug errors (like described in Pegasus 4.5. beta bugs) or crashes, especially if nobody else can duplicate them due to whatever custom environment(s) you're using, it may be very helpful if you can provide a "call stack trace" like described below:
1. Go to <http://www.microsoft.com/whdc/devtools/debugging/installx86.mspx>, check the system requirements (a broadband Internet connection maybe useful as well), download the appropriate setup package and install it on your machine.
2. Launch WinDbg and select either of two ways to start debugging Pegasus Mail:
- If it doesn't already run use the "Open Executable ..." command from the "File" menu, enter any command line parameters you'd like to use in the "Arguments" box and select "winpm-32.exe" in Pegasus Mail's program directory which will launch Pegasus Mail immediately.
- If Pegasus Mail is already running you may simply "connect" to it using the "Attach to a Process ..." command from the "File" menu and selecting "winpm-32.exe" from the list of running processes.
- Pegasus Mail will be halted after loading the statically linked libraries it uses, which enables us to adjust our "workspace" (Pegasus Mail appears to be hanging, see below).
3. While watching the "Command" window you may already have noticed some errors related to loading symbols (if not you're very likely to encounter them while proceeding). To "fix" this you should create an additional (arbitrary) folder on your machine which will be used for downloading on demand and caching required symbol files ("C:\WebDebugSymbols", e.g.). Now select "Symbol File Path ..." from the "File" menu, enter the following command line in the "Symbol Search Path" window, check "Reload" and click "OK" ("C:\WebDebugSymbols" is the path to the directory created previously):
SRV*C:\WebDebugSymbols*http://msdl.microsoft.com/download/symbols
After reloading Pegasus Mail you should save your workspace using the respective "File" menu entry for the first time (if not having been prompted for doing so anyway).
4. You may now design the workspace you would like to use for debugging: Via "View" menu open a "Call stack" window, and - for the more experienced users - maybe a "Disassembly" window. You may create whatever layout you prefer and "dock" all windows like shown in the WinDbg screenshot. Select "Source" and "Source args" on the "Calls" toolbar and save your workspace.
5. Now take a look at the "Command" window again: It shows a "Break instruction exception - code 80000003" ending with an "int 3" assembly command which simply indicates that the process has been halted by the debugger (if no other exception occurred on startup, that is). To continue Pegasus Mail's program execution you may use the [F5] shortcut or type a "g" followed by a [Return] into the bottom line of the "Command" window (the one preceded by the "0:000>" prompt). Attention: If the debugger restarted Pegasus Mail it acts as if it had crashed, i.e. you will have to deal with it's "Mailbox locked" dialog before being able to continue normal program execution.
6. Now you can just "forget" about the debugger and do whatever you want with Pegasus Mail. Once an exception or crash occurs you will notice that Pegasus Mail appears to hang - which is when it's time to switch to the debugger again: You'll now see some new output in the "Calls" window showing information about where the actual "event" occurred (and the corresponding assembly line if you're keeping the "Disassembly" window open as well). This is the most useful information for David if a matching "winpm-32.pdb" file is located in Pegasus Mail's program directory. To extract this information from WinDbg you may use the "Copy stack to clipboard" command from the menu popping up when clicking the extra icon on the "Calls" window's title bar next to the close button. After doing so you may try to continue program execution like before using the [F5] command - which will only work, though, if the exception is a non-fatal one: Otherwise you'll have to restart Pegasus Mail [Ctrl + Shift + F5].
7. If you terminate Pegasus Mail outside of WinDbg you need to stop debugging using [Shift + F5] or the respective "Debug" menu entry, otherwise you won't be able to finish debugging properly and start a new debugging session.
8.It may be easier for you to just create a (desktop or start menu) shortcut for launching Pegasus Mail directly without setting WinDbg's initial and final breakpoints (the parts in square brackets and the application paths need to be customized according to your installation paths) for simplifying its day-to-day use:
"[Program Files]\Debugging Tools for Windows\windbg.exe" -g -G "[Program Files]\Pegasus Mail\winpm-32.exe" -I [YourID]
The "Debuggee not connected" message at the bottom of the "Command" window after starting WinDbg this way can be ignored, WinDbg will automatically "connect" whenever an exception, crash or debug error occurs. If you prefer to connect manually switch to the WinDbg window and press [Ctrl + Break] followed by [F5] after WinDbg finished its breakpoint processing.
9. You may also install WinDbg as your default "postmortem debugger" which will cause it to launch automatically instead of "Dr. Watson" so you don't need to run it as a backgound task when using Pegasus Mail. It may also be more convenient if you frequently encounter so called "first chance" exceptions which aren't fatal but may bother you by constantly interrupting you workflow. Just launch WinDbg once with the following commandline parameter(s) according to its online help for doing so:
-I
Installs WinDbg as the postmortem debugger. For details, see Enabling Postmortem Debugging. After this action is attempted, a success or failure message is displayed. If S is included, this procedure is done silently if it is successful; only failure messages are displayed.
10. To add debug symbols for debugging Martin Ireland's BearHtml library you just need to copy the file BearHtml.dbg (shipping with the BearHtml library in its recent releases, check his homepage) into Pegasus Mail's executable directory: WinDbg will automatically load them when tracing the library.
11. For a sample call stack trace associated with a reproducable crash see the Crash in Beta w/Spell Check thread.
Michael
--
PGP Key ID (RSA 2048): 0xC45D831B
PGP Plugin for Pegasus Mail: <http://www.pmpgp.de/pmpgp/>
S/MIME Certificate Fingerprint: 94 c6 b4 71 0c 62 30 88 a5 b2 77 01 74 2b 86 66 3b 7e 65 7c