Welcome to IKPdb’s documentation!

A hackable CPython remote debugger designed for the Web.

Features

IKPdb supports:

  • Debugging of multithreaded programs
  • Conditional breakpoints
  • Variables hot modifications
  • “Turbo” mode

IKPdb has no integrated GUI ; its only interface is a TCP protocol.

IKPdb client GUI reference implementation is Cloud9 Online IDE

IKPdb TCP protocol - based on JSON - is designed for easy integration with latest generation of Javascript editor / IDE (eg. Visual Studio Code, Cloud9, Atom).

Please note that IKPdb supports only CPython 2.7, CPython 3 support is the next step.

Getting started

Getting started with Cloud9

  1. Create a Workspace using the Python template
  2. Install the debugger
$ pip install ikpdb
  1. Create a new file with a few statements and save it as “debug_me.py”.

You can copy / paste this snippet.

#coding: utf-8
print "I want to try Python debugging with IKPdb in Cloud9."
print "I step over onto this line."

4. Set a breakpoint on the first line by clicking in the left margin until a red circle appears.

Ignore the red check button on line 1 ; as it is relevant only for Django development.

_images/index_pic1__py_snippet.png
  1. Click on the Run button at the Top menu right-hand side.
_images/index_pic2__run_button.png

The debugger is now open on the breakpoint you defined at step 3.

_images/index_pic3__debugger_opened.png

Now you can:

Getting started without Cloud9

IKPdb is a debug server. You need a client to use it. You can use Cloud9 client (see above) or develop your own.

For that, follow the instructions in Install IKPdb’s source code to install IKPdb from source code.

Now you can launch IKPdb.

IKPdb has a –help command that shows all available options.

$ python -m ikpdb --help

Start a debugging session with:

$ python -m ikpdb to_debug.py
[IKPdb-g] 05:04:40,690467 - INFO - IKPdb 1.0.0 - Inouk Python Debugger for CPython 2.7
[IKPdb-g] 05:04:40,690937 - INFO - IKPdb listening on 127.0.0.1:15470

This command starts debugging of the to_debug.py python file. IKPdb is then listening for commands on localhost port 15470 (15470 is default port).

Now you can start hacking on your own client. For that you can use this starting material:

Source files mapping

ILPdb relies on Python’s settrace() facility which requires file names with absolute paths.

In some situations, the absolute path of a given file may be different between IKPdb’s Client (Cloud9) and IKPdb’s debugged process.

That’s where “path mapping” comes into play.

Note that all we explain here is applies to Docker...

Let’s take an example.

Say you want to debug code in a file name archive_server.py running on a remote server.

This file is stored in different folders:

  • Cloud9: /home/ubuntu/workspace/archive-tools/archive_server.py
  • Debugged Process: /opt/servers/archive-tools/archive_server.py

When Cloud9 asks IKPdb to add a breakpoint to a file, it sends a path relative to workspace’s root: “archive-tool/archive_server.py”. To build an absolute path, IKPdb will use the value of the “–ikpdb-working-directory” parameter or will default to IKPDb’s current working directory. In our example –ikpdb-working-directory would be “/opt/servers/archive-tools/”. This is done by IKPdb::normalize_path_in() method.

When IKPdb reach a breakpoint, it will normalize the path by removing IKPdb’s current working directory then - if it’s defined - it will prepend the value of “–ikpdb-client-working-directory” so that the debugging client (Cloud9) will be able to display the breakpoint. In our example –ikpdb-client-working-directory will be “/archive-tools/”. This is done by IKPdb::normalize_path_out() method.

Summary

–ikpdb-working-directory is used to compute file’s path sent to IKPdb. –ikpdb-client-working-directory is used to compute file’s path sent to IKPdb client.

Debugging

To ask IKPdb to display its working directory add a –ikpdb-log=P command line parameter in the runner.

User’s Guide

You’ll find more information about IKPdb usage in the IKPdb User Guide for Cloud9. This guide covers the debugger and the Cloud9 client plugin.

Integration’s Guide

You can get a huge productivity boost by integrating IKPdb with the software of the framework you use. Once integrated, the debugger will automaticaly opens an gives you all information required to debug each time an exception occurs.

_images/index_pic4__demo_exception.png

Read the IKPdb Integration Guide here.

Developer’s Guide

The IKPdb Developer’s Guide describes how to modify the debugger or the IKPdb’s client Cloud9 plugin.

Documentation Writer’s Guide

The documentation is written using the Sphinx Documentation Generator

The Documentation Writer’s Guide describes how to enhance the documentation you are reading.

Source code

IKPdb is composed of these projects hosted on github:

Protocol description

You’ll find a high level overview of IKPdb’s protocol in the IKPdb Protocol

API

Find the complete documentation of IKPDb’s debugger source code in the API document.

Dependencies

IKPdb has no external dependencies (and we wish this to remain like that).

Issues / Suggestions

Please feel free to file an issue on the project’s Github bug tracker if you:

  • have found a bug
  • have some idea about improvements or optimizations
  • have some needs to build a new debugging client !

License

IKPdb is MIT licensed. All detail in the License page.

Indices and tables