Using Eclipse

Eclipse is an Integrated Development Environment (IDE) that can be used to write and debug code. To set up Eclipse to work on an OPS development Virtual Machine, see Installing and Configuring Eclipse.

In addition to this page, please consult the PyDev and [Eclipse] (http://help.eclipse.org/luna/index.jsp) documentation for how to use eclipse with Python code.

Getting started with eclipse

• Use the command eclipse& as root to start eclipse from a terminal.
• The standard 'PyDev' perspective is useful for browsing and writing code.
• Use Window -> Open Perspective -> Other -> Debug to open the standard debugging perspective.
• Eclipse is highly customizable and includes many features out of the box. Use Window -> Preferences to adjust settings.
• New plugins for Eclipse can be installed using the Help -> Install New Software wizard.

Using Eclipse with the OPS Django project

• In the PyDev Package Explorer, one can right-click the OPS project and use Django -> Shell with django environment to start a Django shell. This is the equivalent of doing the following in a terminal:

cd /var/django/ops
source /usr/bin/venv/bin/activate
python manage.py shell

• One can save custom manage.py commands by right clicking the OPS project in the PyDev package Explorer and using the Django -> Custom command interface. This makes executing frequent manage.py commands a snap. Here are the Django manage.py commands.

Debugging in Eclipse

Use the Debug perspective for debugging.

• The 'Console' View in the Debug perspective shows output, notices and warnings/errors. One can add a new console by pressing the 'Open Console' button at the upper left side of the Console view. The PyDev console can be used to enter python code (use of the Django shell is recommended - see above). A Debug console can be opened during a debugging session. This will allow one to enter commands within the context of the currently running process.

• The other Debug perspective views provide important information on the status of a debugging session. The 'Variables' view, for example, shows what variables have been initialized and the values they have at any given time. Use Window -> Show View to customize what views are shown in a perspective.

• Since the OPS Django application is comprised of a series of functions that take http requests as arguments, it is not possible to simply run/debug a Django view. One should use the debugView.py script found at /var/django/ops/ops/debugView.py to debug a Django view line-by-line in Eclipse. See the debugView.py docstring shown below for information on how to do so.

# =========================================================================================
# SCRIPT FOR STARTING A LINE-BY-LINE DEBUGGING OF A DJANGO VIEW.
#
# Used to call a django view for debugging in an IDE (Eclipse).  
# The user should fill in the 'USER INPUT' fields below and debug this script with 
# breakpoint(s) placed in the view. The IDE should halt exectuion at breakpoint(s) and 
# allow the user to inspect variables and step through the code. See the IDE's specific 
# documention on debugging to learn more.
#
# Inputs required:
#	viewName: (string) the name of the view being debugged
#	app: (string) the name of the app for which the view will be debugged with
#	jsonStr: (string) the json string containing the properties used by the view.
#
# =========================================================================================

Using the Remote Debugger in Eclipse

Useful page on how to set up remote debugging.

• The PyDev plugin for Eclipse includes a Python module called pydevd. The pydevd module provides a means of debugging a script running on a server (known as remote debugging). In this case, one can use calls to pydevd in the OPS django application to do line-by-line debugging of code initiated by an external http request from MATLAB. This is especially useful in cases where a MATLAB script makes multiple calls to the OPS and debugging with the debugView.py method requires frequent, new, and potentially long json strings.

• NOTE: Remote debugging is not considered safe for production environments and should therefore only be used on the OPS development VMs. If debugging must occur in a development environment, the use of debugView.py should be used with caution.

• Remote debugging requires some setup before debugging can occur and cleanup after debugging is complete. The manageRemoteDebugger.sh tool can be used to aid in this process and can be found in the /vagrant/conf/tools/ directory. One should run the manageRemoteDebugger tool before and after a remote debugging session.

To start remote debugging in eclipse, the following steps should be taken:

1. Run the following script, choosing the 'Start Remote Debugger' option and following the instructions provided: sh manageRemoteDebugger.sh

2. Add import pydevd to whatever file is to be debugged.

3. Add pydevd.settrace() before the line you wish to have the debugger stop (sets a breakpoint).

4. Send a request to the server from MATLAB or other external application. The process will hang wherever the pydevd.settrace() call is placed.

5. Debug within the Eclipse debug perspective!

More coming soon!