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¶
- Create a Workspace using the Python template
- Install the debugger
$ pip install ikpdb
- 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.
- Click on the Run button at the Top menu right-hand side.
The debugger is now open on the breakpoint you defined at step 3.
Now you can:
- Play with the debugger
- Read the Cloud9 debugging documentation to discover all Cloud9 features related to debugging.
- Read IKPdb User Guide for Cloud9 to get information about IKPdb and Python debugging.
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.
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
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 !