Debugging and Profiling
General Setup
DEBUG.ini
To enable debugging or profiling copy DEBUG_template.ini
to DEBUG.ini
and edit it.
Create bash script for offline debugging from console
- in
DEBUG.ini
setcreate_bash_script = True
- call
inkstitch.py
extension from inkscape to create bash script named bybash_file_base
inDEBUG.ini
- run bash script from console
Enable debugging
- set
debug_type
to one of -vscode
,pycharm
,pydev
- debug_type = vscode - ‘debugpy’ for vscode editor
- debug_type = pycharm - ‘pydevd-pycharm’ for pycharm editor
- debug_type = pydev - ‘pydevd’ for eclipse editor
- set
debug_enable = True
inDEBUG.ini
- or use command line argument
-d
in bash script - or set environment variable
INKSTITCH_DEBUG_ENABLE = True
or 1 or yes or y
- or use command line argument
With debugging enabled Ink/Stitch will also generate an SVG file for debugging graphs.
Enable profiling
- set
profiler_type
to one of -cprofile
,profile
,pyinstrument
- profiler_type = cprofile - ‘cProfile’ profiler
- profiler_type = profile - ‘profile’ profiler
- profiler_type = pyinstrument - ‘pyinstrument’ profiler
- set
profile_enable = True
inDEBUG.ini
- or use command line argument
-p
in bash script - or set environment variable
INKSTITCH_PROFILE_ENABLE = True
or 1 or yes or y
- or use command line argument
Miscelaneous notes
- to disable debugger when running from inkscape set
disable_from_inkscape = True
inDEBUG.ini
- to write debug output to file set
debug_to_file = True
inDEBUG.ini
- to change various output file names see
DEBUG.ini
- to disable waiting for debugger to attach (vscode editor) set
wait_attach = False
inDEBUG.ini
- to prefer inkscape version of inkex module over pip version set
prefer_pip_inkex = False
inDEBUG.ini
Debuggers
LiClipse
- Install LiClipse (https://liclipse.com) – no need to install Eclipse first
- Start debug server as described here: http://www.pydev.org/manual_adv_remote_debugger.html
- follow the “Note:” to enable the debug server menu item
- Enable debug as descriped above (set
debug_type = pydev
inDEBUG.ini
) - Run any extension and PyDev will start debugging.
PyCharm
You must use the PyCharm Professional Edition and not the Community Edition. Jetbrains has chosen to make remote debugging a Pro feature.
To debug Inkscape python extensions, the extension code and Inkscape run independently of PyCharm, and only communicate with the debugger via a TCP socket. Thus, debugging is “remote,” even if it’s on the same machine, connected via the loopback interface.
-
pip install pydev_pycharm
pydev_pycharm is versioned frequently. Jetbrains suggests installing a version at least compatible with the current build. For example, if your PyCharm build, as found in menu
PyCharm > About
is 223.8617.48, you could do:pip install pydevd-pycharm~=223.8617.48
- From the Pycharm “Run” menu, choose “Edit Configurations…” and create a new configuration. Set “IDE host name:” to “localhost” and “Port:” to 5678. You can leave the default settings for all other choices.
- Touch a file named “DEBUG.ini” at the top of your git repo, as above
set
debug_type = pycharm
-
If not already happened, create a symbolic link in the Inkscape extensions directory to the top-level directory of your git repo. On a
mac
, for example:cd ~/Library/Application\ Support/org.inkscape.Inkscape/config/inkscape/extensions/ ln -s <full path to the top level of your Ink/Stitch git repo>
On other architectures it may be:
cd ~/.config/inkscape/extensions ln -s <full path to the top level of your Ink/Stitch git repo>
Remove any other Ink/Stitch files or references to Ink/Stitch from the extensions directory, or you’ll see duplicate entries in the Ink/Stitch extensions menu in Inkscape.
- In Pycharm, either click on the green “bug” icon if visible in the upper right or press Ctrl-D to start debugging.The PyCharm debugger pane will display the message “Waiting for process connection…”
- Do some action in Inkscape which invokes Ink/Stitch extension code, and the debugger will be triggered. If you’ve left “Suspend after connect” checked in the Run configuration, PyCharm will pause in the “self.log(“Enabled PyDev debugger.)” statement, below. Uncheck the box to have it continue automatically to your first set breakpoint.
VS Code
Helpful Links:
- https://code.visualstudio.com/docs/python/debugging#_command-line-debugging
- https://code.visualstudio.com/docs/python/debugging#_debugging-by-attaching-over-a-network-connection
-
Install the Python extension for VS Code
pip install debugpy
-
create
.vscode/launch.json
containing:"configurations": [ ... { "name": "Python: Attach", "type": "python", "request": "attach", "connect": { "host": "localhost", "port": 5678 } } ]
- Set
debug_type = vscode
inDEBUG.ini
- Start the debug server in VS Code by clicking on the debug icon in the left pane select “Python: Attach” from the dropdown menu and click on the green arrow. The debug server will start and connect to already running python processes, but immediately exit if no python processes are running.
Notes To see flask server url routes comment out the line self.disable_logging() in run() of lib/api/server.py
Profilers
Profile
Enable profiling as described above using profile. Ink/Stitch will then run under a profiler and dump the result to profile_stats. It will tell you what functions take how long to run.
Install snakeviz with pip install snakeviz
.
Open the statistics with snakeviz profile_stats.prof
.
This will display a really useful interactive graph in your browser.