Debugging macros with PyDev in Eclipse

I didn't find any resource explaining how to configure the Eclipse IDE with PyDev to work on Python scripts for FreeCAD. But it's not too hard to get it working. This gets you auto-completion (but still far from perfect) and a full-featured debugger (breakpoints, inspect variables, etc.)

Here is what I have found so far, in the hope it can help others. I will assume you know how to use an IDE and a debugger and will focus on the specifics of getting it to work. I have only tested this on a Debian 11 system so far.

Here are the steps I used:

1. Extract FreeCAD files if they are bundled in a package
   • Assuming you have installed the AppImage, from a command prompt, you can extract the files it contains with command "./FreeCAD.AppImage --appimage-extract"
   • This will create a directory "squashfs-root" which contains all the FreeCAD files
   • You can start FreeCAD from there (usr/bin/freecad), but it's not mandatory, we mostly only need those files for auto-completion
2. Install Eclipse
3. Install PyDev
   • Start eclipse
   • Menu Help -> Install new software
   • Click "Add..." and add a new site https://www.pydev.org/updates
   • You should see a new module "PyDev", tick it (untick "PyDev for Eclipse Developer Resources")
   • Click Next and follow the instructions
4. Configure a new Python interpreter
   • Menu Window -> Preferences
   • On the left pane, select PyDev -> Interpreters -> Python Interpreter
   • On the right, click "New..." -> "Browse for python/pypy exe"
   • A file explorer opens, browse to where FreeCAD is installed and choose executable "FreeCAD/usr/bin/python"
   • Give it a name, for example "FreeCAD-0.20" if that's the version of FreeCAD you have installed and click "OK"
   • Keep the default folders for Python path and click "OK"
   • Select your newly created interpreter in the list, and in the pane below click the "Libraries" tab
   • Add the following path: "FreeCAD/usr/lib" and "FreeCAD/usr/Mod"
   • Click "Apply and Close"
5. Create a new project
   • Menu File -> New -> Project
   • Select project type "PyDev Project"
   • Give it a name and specify the root directory
   • You should now be able to create Python files, import "FreeCAD" and "FreeCADGui", and auto-completion should work. However, don't expect everything to work, for example "FreeCADGui" will be mostly empty, it seems that FreeCAD adds everything at run-time.

Now the most interesting part I think is the debugger. I have used the PyDev remote debugger

1. Open the debug perspective: there is an "Open Perspective" button on the right of the Eclipse toolbar, select "Debug"
2. Then use menu Pydev -> Start debug server
3. Eclipse is now listening on localhost on the default port for incoming connections from any Python process
4. Install the "pydevd" module on your system ("pip install pydevd")
5. Locate where it is installed (start the system Python interpreter, then import pydevd, and see the value of pydevd.__file__)
6. You can have FreeCAD connect to the debugger, either by adding code in one of your Python files, or in the FreeCAD Python console
   • add the path to pydevd, for example sys.path.append('/usr/local/lib/python3.9/dist-packages/')
   • import pydevd
   • then run pydevd.settrace()
7. If everything went well, FreeCAD is now connected to the Eclipse debugger, and you can place breakpoints in your Python code
8. Note that by default PyDev will stop execution as soon as FreeCAD connects, so you need to resume execution to unfreeze FreeCAD (I would expect an option to disable this behavior but couldn't find one)

Original post on FreeCAD's forum from user youen.