There is a set of possible tools to debug the Python code, but we'll focus only on PyDev, which reduces the number of installation steps and allows remote debugging without modification of the plugin code.

PyDev is an Eclipse plugin, where Eclipse is a free software programmable framework used to develop almost everything. PyDev can be added to a local installation of Eclipse, adding it from the marketplace, but to reduce the number of installation steps, it's suggested that you install Aptana Studio 3, an Eclipse customization with PyDev already installed.

Aptana Studio 3 can be downloaded from the project homepage at http://aptana.com/. Just unzip the folder and execute the executable file, AptanaStudio3, inside the unzipped folder.

The installation version of Aptana Studio 3 should be at least version 3.6.1, because some previous versions have bugs that don't facilitate code writing. If a version greater than 3.6 is not available, then it's necessary to upgrade to the beta version. To upgrade, follow the instructions mentioned at http://preview.appcelerator.com/aptana/studio3/standalone/update/beta/.

To allow QGIS to be connected with the PyDev daemon, it's necessary that the PyDev daemon path be added to the PYTHONPATH environment variable.

To find the path to add, look for the pydevd.py file; it will be in the AptanaStudio installation path. If you find more than one version, get the path that has the highest version number.

For example, in my Linux installation there are the following paths:

/users/ginetto/Aptana_Studio_3.6/plugins/org.python.pydev_3.0.0.1388187472/pysrc/pydevd.py
/users/ginetto/Aptana_Studio_3.6/plugins/org.python.pydev_3.8.0.201409251235/pysrc/pydevd.pyc

In this case, we should use the following path:

/users/ginetto/Aptana_Studio_3.6/plugins/org.python.pydev_3.8.0.201409251235/pysrc

This path can be added in the session, PYTHONPATH, or directly in the QGIS environment by modifying PYTHONPATH by navigating to Options | System in the Environment section, as shown in the following screenshot:

This way it will be possible to import the pydevd Python module into the QGIS Python Console and set the connection to the PyDev debug server, as described in the next section.

To test whether the path is set correctly, try to type the following code in the QGIS Python Console:

import pydevd

If it generates an error, it means that PYTHONPATH is not set correctly with the path of the pydevd module.

The first step to connect to PyDev server is to start the server in the Aptana environment. This can be achieved by opening the Debug perspective of Aptana and then starting the server with the relative start/stop buttons. The buttons and Debug perspective are shown here:

The Debug perspective can be opened by clicking on the right-hand side button circled in red. If the Debug perspective button is not available, it can be added to the Aptana menu. Navigate to Window | Open Perspective | Other.

The start/stop server button is shown by the red circle on the left.

While starting the server, some messages will appear in the Debug window highlighted by the red box in the upper-left section; this means that the server is running. In the Debug window, all connected clients will be listed.

In the red box at the bottom, the Aptana console window shows that the server answers to the port, 5678; this is the information that we'll use to connect from QGIS.

After running the PyDev server we'll connect to it from QGIS. In the QGIS Python Console, type the following code:

import pydevd
try:
    pydevd.settrace(port=5678, suspend=False)
except:
    pass

The preceding code first imports the pydevd module and then connects to the server with the settrace method. The connection is inside try/catch to allow catching an exception raised in case settrace cannot connect. The connection will take some seconds to connect. If the connection fails, the Python Console will show a message similar to the following one:

Could not connect to 127.0.0.1: 5678
Traceback (most recent call last):
File "/mnt/data/PROGRAMMING/IDE/Aptana_Studio_3/plugins/org.python.pydev_3.8.0.201409251235/pysrc/pydevd_comm.py", line 484, in StartClient
s.connect((host, port))
File "/usr/lib/python2.7/socket.py", line 224, in meth
return getattr(self._sock,name)(*args)
error: [Errno 111] Connection refused

If the connection is successful, the Aptana Debug perspective will change, showing the connected clients.

The simplest way to set up PYTHONPATH and connect to the PyDev server is using the Remote Debugger experimental plugin that can be installed as usual. The main interface is shown in the following screenshot:

The Remote Debugger plugin is in charge of setting up PYTHONPATH, writing it in the pydevd path textbox.