Version 13 (modified by matija, 3 years ago) (diff)

Migration to Mercurial.

Setting up Development Environment

The Bioinformatics Laboratory, which leads and hosts Orange development, employs a wide variety of researchers and developers. Each and every one of us has his/her own preference regarding the development environment. It is our intention on this page to present some of configurations we use that seem to work well.

At the moment, unfortunately, only one configuration is described: Eclipse under Linux, specifically Ubuntu.

Ubuntu & Eclipse

This procedure has been written for and tested on Ubuntu 11.10, but should also work for newer and older (down to 10.04) releases.

Package Installation

You need to install the following packages:

  • eclipse will be your IDE (Integrated Development Environment),
  • mercurial will be your VCS (Version Control System),
  • make, g++, python-dev, python-numpy, python-matplotlib, python-imaging and python-rpy2 are needed to build and use the Orange scripting environment, and
  • python-qwt5-qt4 is needed in order for the Orange Canvas (GUI) to work,
  • cmake, python-qt4-dev and python-qt4-gl are needed in order to build and use the new Qt and 3D visualization widgets,
  • python-sphinx, texlive-latex-base, texlive-latex-recommended, texlive-latex-extra and dvipng are needed to build the HTML documentation,
  • python-pip provides pip, which we need for numpydoc.

Beware that Sphinx has to be at least of version 1.0; Ubuntu 10.10 and older contain older versions of Sphinx, so you should not install the python-sphinx from apt repository, but find another way, such as easy_install sphinx.

This is the command to install all those packages in one shot:

sudo apt-get install eclipse mercurial make g++ python-dev python-numpy python-matplotlib python-imaging python-rpy2 python-qwt5-qt4 cmake python-qt4-dev python-qt4-gl python-sphinx texlive-latex-base texlive-latex-recommended texlive-latex-extra dvipng python-pip

To build the documentation, numpydoc is also needed:

sudo pip install numpydoc

If you wish to use Orange for network analysis, you also need a recent version of networkx; you can install it with:

sudo pip install networkx

Obtaining the Code

Open a terminal, get to the directory where you want the code to reside and clone our repository:

hg clone .

After a little while you'll notice you now have subdirectory orange containing, among other things, the following directories:

  • orange with Orange's Python source code,
  • source with Orange's C++ source code,
  • docs with Orange documentation.

There's also a file you can use to build and install Orange, although for development purposes we suggest you use make (within the source directory). We'll get to that later.

Path Settings

To be able to run Orange, you need to add some directories to the PYTHONPATH. Here, we will assume you only have one version of Orange on your system and you want to use it from within Eclipse and also outside it. If you have more than one version of Orange, we'll assume you also know the best way to deal with your paths.

Open a terminal and go to the directory where your clone of Orange repository resides (i.e. the directory that contains the orange and source subdirectories). Now invoke the following:

( echo -e "$PWD/orange\n$PWD/orange/OrangeCanvas\n$PWD/orange/OrangeWidgets" && find $PWD/orange/OrangeWidgets -maxdepth 1 -type d -regex '[^\.].*' ) | sudo tee `python -c "from distutils.sysconfig import get_python_lib; print get_python_lib()"`/orange.pth

You will need to provide your password, because sudo is used to write to a system directory. You may dissect the command to figure out what it does; it basically puts some paths in your repository clone to a file orange.pth in python's dist-packages directory.

Setting Up The Eclipse IDE

Next, you need to run Eclipse. As the workspace, choose the directory you used to clone our repository. (There are other possibilities; do it your own way if you know your way around.) Within Eclipse, install the needed plugins: CDT (C/C++ Development Tooling), PyDev (Python IDE for Eclipse) and MercurialEclipse (for Mercurial repository support). That is, choose Help->Install New Software... and add the following Update Sites:

Choose –All Available Sites– for the "Work with" option and install the following choices: MercurialEclipse->MercurialEclipse, PyDev and CDT Main Features.

Now let's set up the projects in Eclipse. We'll set up two projects: orange for Python code and source for C++ code.

Open the New Project dialog, select C/C++->C++ Project. Select Makefile project->Empty Project->Linux GCC for Project type and Toolchain. Use source as project name, disregarding the warning about project already existing.

Under project properties ("Advanced settings..." button), C/C++ Build->Environment, add the following environmental variables:

  • CXXFLAGS=-ggdb
  • LDFLAGS=-ggdb

(If you intend to invoke make on the commandline, you can add those properties into your ~/.pam_environment file or elsewhere you see fit.)

To accelerate the compilation process on a multi-processor or multi-core machine, you may instruct Eclipse to use parallel build (-j switch to the make): go to project properties for source project and under C/C++ Build->Behaviour check "Use parallel build". Manually enter a desired parallel jobs count, for example the number of processor cores in your computer; do NOT use "optimal jobs number": Eclipse likes to run all possible compilations at once and you'll probably run out of RAM.

Fire up the New Project dialog once more, select Pydev->Pydev Project and name the project orange. Use the "Add project directory to PYTHONPATH" option, and in no case the "Create 'src' folder and add it to PYTHONPATH". Configure the interpreter if Eclipse requests so; you may use the Auto Config button with default settings. Select source as a referenced project.

Enabling Running and Debugging

For debugging, it's best to set up three debug configurations: one for Python code, one for C++ code with Orange Canvas being invoked and one without Canvas to debug in python scripting environment. Choose Run->Debug Configurations and set up the following configurations.

Add a new "Python Run" configuration, name it orange-canvas-python (or otherwise, if you will), select orange as the project and select OrangeCanvas/orngCanvas.pyw as the main module. Click apply.

Now add a new "C/C++ Application" configuration, name it orange-cpp, select source as the project and /usr/bin/python as the C/C++ Application. In the Debugger tab, uncheck the "Stop on startup at main". You may now apply the configuration.

Now clone the last configuration, name it orange-canvas-cpp and add, in the Arguments tab, enter ${workspace_loc}/orange/OrangeCanvas/orngCanvas.pyw as program arguments.

You can now test those three configurations. Beware that without setting -ggdb flags (as described higher up in this document) you will not be able to debug C++ code. Note also that on the first run (and after heavy modifications of C++ code) it will take some time for your computer to build the C++ code of Orange.

Building the Documentation

To build the documentation, open a terminal and go to docs/reference directory under your workspace. Invoke make html (preceded by make clean if you want to force a rebuild of all documentation). You should now have a html/index.html file with documentation index.