Table of contents

• 1. Introduction
  • 1.1 General information
  • 1.2 Quick start
  • 1.3 Building from source
  • 1.4 Manual installation
  • 1.5 API changes

1. Introduction

1.1 General information

The Pykd project started in 2010. The main reason was the inconvenience of scripting debugging with the built-in tools for WinDbg. Python language was chosen as an alternative scripting engine for many reasons: ease of learning of the language itself, the presence of a huge standard library and the presence of the powerful framework for creating extensions. Pykd is a module for the CPython interpreter. Pykd itself is written in C++ and uses Boost.Python to export functions and classes to Python. Pykd controls debugging on the Windows platform through he Debug Engine library and receives symbolic information through the MS DIA library. Note that pykd does not give direct access to the COM interfaces of Debug Engine and MS DIA. Instead, it implements its own interface which makes the development process faster and more convenient (we hope).

Pykd can operate in two modes:

• as a plugin for WinDbg, in which case it provides commands to run scripts in the context of debugging sessions
• as a separate module for the Python interpreter. This mode can be useful for creating automatic tools that parse crash dumps, for example.

←Table of contents

1.2 Quick start

For a quick start, best download the automatic installer. It will install all necessary components (including Python if not already installed). To verify that the installation was successful, run WinDbg, start debugging an application or dump file, then load pykd:

.load pykd.pyd

If there was no error message, everything is fine. But anyway, let's make sure that everything really works:

0:000> !pycmd
Python 2.6.5 (r265: 79096 , Mar 19 2010 , 18:02:59) [MSC v.1500 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
(InteractiveConsole)
>>> print "Hello world!"
Hello world!
>>> quit ()
0:000>

Try to run some example scripts:

0:000> !py help
0:000> !py samples

If everything worked, you can start writing your own scripts.
←Table of contents

1.3 Building from source

1. Take the source code from the repository.
2. Install Python.
3. Install and configure Boost. There is also a manual installation and assembly.
4. Set the environment variables:

$(DIA_SDK_ROOT) - path to the MS DIA library. It is installed with Visual Studio and the path should look similar to C:\Program Files (x86)\Microsoft Visual Studio 9.0\DIA SDK.

$(DBG_SDK_ROOT) - path to the Debug Engine SDK. It is installed with the Debugging Tools for Windows and the path should look like C:\Program Files (x86)\Debugging Tools for Windows (x86)\SDK.

$(BOOST_ROOT) - path to the directory where you installed Boost.

$(PYTHON_ROOT) - path to the installation directory of Python. It is assumed that the system has both, x86 and x64, versions of Python in a directory structure like this: C:\Python26\x86\... and C:\Python26\x64\... in this case, $(PYTHON_ROOT) should be equal to C:\Python26. If the installation path is missing Python and does not indicate the platform, it is necessary to tweak the project file.

1. Build the Boost.Python library

To assemble the required static Boost.Python libraries, the following paths point to the library:

$(BOOST_ROOT)\stage - for x86 assembly

$(BOOST_ROOT)\stage64 - for x64 assembly

You can collect them with the following commands:

bjam --stagedir=stage --with-python stage
bjam address-model=64 --stagedir=stage64 --with-python stage

If you have not installed yet, download bjam.
←Table of contents

1.4 Manual installation

To manually install pykd.pyd, you have to install the C++ runtime from Visual Studio (vcredist). If you compile it yourself, this shouldn't be a problem. If you downloaded pykd from the website, it also shouldn't be a problem since the ZIP file contains the desired redistributable (as long as we didn't mess with the release :-)).

Where to copy pykd.pyd?
It depends on the scenario. If pykd shall be used as a plugin to WinDbg, it makes sense to copy it into the winext subdirectory of your WinDbg installation. In this case you can rename it to pykd.dll so that you can omit the file extension when loading the extension:

0:000> .load pykd

If pykd shall be used to write a Python program,it must be put in a place where it can find a Python interpreter. These are the three options:

• in the lib subdirectory of the Python installation.
• any directory. In this case, the $(PYTHONPATH) environment variable must be set.
• any directory, if you start Python from the directory where pykd.pyd is located.

Installing Visual C++ redistributable
Of course you need to install VCRedist. Otherwise, why would we ask you to download it?

Registering MS DIA
The MS DIA library will be installed during the installation of VCRedist. In order to work properly, it must also be registered. To do this, find the directory where msdia90.dll was installed an run the command

regsvr32 msdia90.dll

If you compiled pykd yourself using Visual Studio, no action needs to be considered regarding VCRedist. It's already installed on your machine and MS DIA is also in place.

←Table of contents

1.5 API changes

loadModule
The function loadModule was removed. Use the module class instead.

# mod = loadModule("mymodule")
mod = module("mymodule")

←Table of contents