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¶
IKPdb exchanges file names with his debugger clients. When it sends a file name, IKPdb always uses full path. But some debuggers client sends relative paths (when setting breakpoints for example). In that case, IKPdb tries to resolve the file’s full path using its “working directory” as a base folder. If it fails, IKPdb sends a “FileMappingError:”.
IKPdb’s working directory can be defined:
- Implicitly ; working directory is set to the debugged program’s current directory.
- Explictly ; using the –ikpdb-working-directory command line parameter
To ask IKPdb to display its working directory add a –ikpdb-log=G 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 !