Debugging WinDBG

Debugging Pharo with WinDBG (Windows)

Pharo can be debugged using the native Windows debugger, WinDBG as an alternative to GDB. It is better to use WinDBG as it is more robust and easy to use in Windows that using GDB from the command line through cygwin.

Requirements

• WinDBG, you can get it from https://learn.microsoft.com/en-us/windows-hardware/drivers/debugger/#install-windbg-directly or as part of the SDK of Windows.

• CV2PDB to convert the symbols from COFF to PDB, you can get it at https://github.com/rainers/cv2pdb/releases You should unzip the app somewhere in your machine. We will refer it as CV2PDBPath

• [Optional] The source code of the Pharo VM that you are using. You can get them from https://files.pharo.org/vm/pharo-spur64-headless/Windows-x86_64/source/ . Please check to download the correct one for your VM. You can get the correct one by using the hash of the commit in the file name of the zip. The commit hash is reported by the version of the vm.

Converting Symbols to PDB

The first step to be able to use WinDBG is to convert the symbols in the executable to the PDB format. The VM that we are shipping includes the debugging information, this helps a lot to recover errors and generate nice dumps. However, WinDBG uses a different format for storing the symbols, so we need to convert them. We have to open a PowerShell or CMD in the directory where the VM is located and run:

  [CV2PDBPath]\cv2pdb Pharo.exe
  [CV2PDBPath]\cv2pdb PharoConsole.exe 
  [CV2PDBPath]\cv2pdb PharoVMCore.dll

You can convert the other DLL with the plugins, but for most of the cases it will not be needed.

Debugging your Application

As with any other debugger, with WinDBG you can launch a new process to debug or attach to a running process. When opening the main window of WinDBG, we can click on the File option in the menu and different options will appear to launch/connect to the debugger. The easiest way is to attach to a running process.

Once the debugger launches or attaches to an existing process, the process will be suspended and the debugger will have control and we can start using it directly.

Setting Source Path (Optional)

If you have downloaded the zip file with the sources, please unzip it somewhere in your system. We are going to instruct WinDBG to use the source code from this location with the command:

.srcpath [ThePathToTheUnzippedSourceCode]

For example

.srcpath C:\cygwin64\home\pablo\dev\pharo-vm-dc93\

Debugging the State of the VM

When the VM is paused in the debugger we can try to get some runtime information about it. The VM includes a series of debugging functions that we can invoke from the debugger. They will generate the output in the console of the PharoVM. The console is open when you run the PharoConsole.exe application, or it is generated in a file that is in your temp directory. The name of the file will be %temp%\pharo-PID.log where PID is the PID of the instance of pharo, for example %temp%\pharo-1234.log.

Some of the available functions are:

• printCallStack: prints the active Pharo process (green thread).

  .call printCallStack()

• printAllStacks: prints all Pharo processes.

  .call printAllStacks()