Table of contents

• 1. Introduction
  • 1.1 General information
  • 1.2 Quick start
  • 1.3 Building from source

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