Configuring Eclipse to work with Opus/UrbanSim

This section provides instructions for configuring the Eclipse IDE for use with Opus.

Eclipse is a free, open-source IDE (Integrated Development Environment) with a large and growing set of plugins. Eclipse provide a great interface to svn repositories and it's free. In addition to the basic Eclipse framework itself, the PyDev plugin provides a decent Python editing environment within Eclipse. There are directions for installing and configuring it on the PyDev FAQ page http://pydev.sourceforge.net/faq.html.

Installing Eclipse

SuSe Linux contains an Eclipse package. For Windows and the Mac, or Linux if you are using a distribution that doesn’t already have Eclipse, download the tar file for your platform from http://www.eclipse.org/downloads. Double-click on the downloaded file to expand it. There is no further install procedure - just put the ‘eclipse’ folder in a convenient place (for example, on the ‘C:’ drive on Windows, or in your home directory on Linux or the Mac). Then double-click on the Eclipse app to start it.

Directions for installing and configuring PyDev are on the PyDev FAQ page.

You will also want a subversion client -- we recommend subversive. Direct your Eclipse to the subversive update site and install it. (See the directions on the subversive download page for information on how to do this.)

The Eclipse Workspace

Eclipse has a 'workspace' in which it keeps the source code and configuration information. You can put this anywhere you want -- just make sure your PYTHONPATH is set to find the code. If you want to keep your source code in the opus/src directory as suggested in OpusDirectoryTree, set your workspace to be the opus/src directory.

Configuring Eclipse

The following are suggestions for configuring Eclipse to work with Opus (these directions were tested with Eclipse version 3.1.1 and PyDev? version 0.9.8.5, but as usual later versions will probably work as well.):

1. Configure Eclipse to use spaces rather than tabs in Python code and to 4 spaces for indentation:
   1. Open Window > Preferences... > Pydev (on Mac: File > Preferences... > Pydev)
   2. Set Tab length to 4
   3. Make sure Substitute spaces for tabs? is checked
   4. Uncheck Assume tab spacing when files contain tabs? so that you detect tabs in files that should not have them
2. Configure Eclipse to make it easy to run a Python program:
   1. Open Eclipse
   2. Select Run > External Tools > External Tools...
   3. Click on Program in the Configurations pane
   4. Click the New button to create a new configuration
   5. Fill in the following values:
      • Name: Python
      • Location: C:\Python25\python.exe (a common path for Windows)
        or browse to your Python location via the Browse File System… button.
        On the Macintosh, you can find the path by typing ‘which python’ at a terminal window. (If you're using the system version, the path is probably ‘/usr/bin/python’; if you've installed your own version of Python, ‘/usr/local/bin/python’ will probably be right.)
      • Arguments: -u ${resource_loc}
   6. Click Apply and close the External Tools dialog box
3. Configure Eclipse/PyDev to use automatic code completion:
   1. Open Eclipse
   2. Select Window > Preferences > PyDev > Code Completion
   3. Make sure that 'Use Code Completion?' is checked
   4. Switch to Interpreter - Python
   5. Next to the 'Python Interpreters' box click 'Add'
   6. Browse to your python.exe (e.g. c:\python25\python.exe)

Checking out the Source Code

Assuming you've set your Eclipse workspace to the opus/src directory, you want to check out code so that the packages are directly under this directory, e.g. opus/src/opus_core, opus/src/urbansim, etc. Using subversive, you can either check out the desired packages one at a time, or use multiple select to get the lot of them.

For advanced users only: you can also select the next-level-up node in subversion, e.g. trunk or a specific version e.g. tags/4.2.0 -- but in this case be careful! You'll end up with an extra layer of directories underopus/src, such as opus/src/trunk -- in this case adjust your PYTHONPATH appropriately.

Using Eclipse

To run a Python program:

1. Select the corresponding .py file in your project (e.g., via the Resources pane, or by selecting an opened file)
2. Select Run > External Tools menu
3. If Python appears in the list, select select it to and Eclipse will run your Python program.
4. If this is the first time you have run this eclipse run configuration, Python won't be in this list. In this case:
   1. Select the menu item Run > External Tools > External Tools...
   2. Select Python in the Configurations pane
   3. Press Run to run your Python program
   4. (The next time you open Run > External Tools, Python will be in the list)

To run a unit test:

1. Open the file (for example) ‘opus_core.tests.test_sampling_toolbox.py’
2. Select Run > External Tools > Python to run this file as a Python program.
3. The output will be shown in the Eclipse console window.

Debugging with Eclipse and pyDev

See DebuggingWithEclipse for a tutorial of setting up Eclipse and pyDev for debugging.

-- AlanBorning - 16 Aug 2009