Getting started

IMP is available in a variety of different ways. If you are just planning on using existing IMP code and run on a standard platform, you may be able to install a pre-built binary. See the download page.

If you are planning on contributing to IMP, you should download and build the source. See the next section for more information.

If you are building IMP from source, read the following sections, otherwise skip to the last one.

1. Building and installing
2. Building IMP for developers
3. Prerequisites
4. Where to go next

1. Building and installing basics

Building IMP from source is straightforward if the prerequisites are already installed. First, obtain the source code tarball from the download page. code there

1. Extract the tarball

    tar -xvzf imp-1.0.tar.gz 
   

   This will create a directory called imp-1.0 containing all the source.
2. change into that directory and build by doing

    scons prefix=place_to_install_imp all 
   

3. install IMP by doing

    scons prefix=place_to_install_imp install 
   

(If you are familiar with Subversion, you can also use an SVN client to check out the same code from our Subversion repository at http://svn.salilab.org/imp/tags/release-1.0/)

If there are build errors

1. make sure all prerequisites are installed
2. read the scons help (scons -h) to figure out any more arguments you need to pass to scons in order to make sure it finds needed external libraries.

If you cannot figure things out, feel free to post on the imp-users list.

If you are likely to be building IMP repeatedly, it can be useful to put the arguments to scons into a config file. This is a file called config.py located in the IMP directory (the one containing the SConscript file). For example one of ours looks like

import os

modeller=os.environ['MODINSTALLSVN']
prefix=os.environ['HOME']+"/fs"
path='/opt/local/bin'
includepath='/opt/local/include:'+os.environ['HOME']+"/fs/include"
libpath=os.environ['HOME']+"/fs/lib"
build='debug'
deprecated=False

2. Building and installing for developers

To get the latest development version of IMP, it is necessary to check it out from our IMP repository using an Subversion client:

 svn co http://svn.salilab.org/imp/trunk imp 

This will create a directory called imp containing all the source at the SVN trunk. We recommend you use use this. Since this is the place that people commit changes to, one should consult the nightly build logs before updating to make sure things are working. In addition, consult the ChangeLog file to see what has changed since your last update.

When developing code for IMP, it is useful to be able to run it without installing everything. To aid this, we provide a script located at tools/imppy.sh which runs a command after setting up the environment so that dynamically linked libraries and python modules can be found. For example, to run Python such that it can use IMP do

 ./tools/imppy.sh python 

In addition, we recommend doing out of source builds (building IMP in a directory other than the one containing the source files). Doing this allows several different versions of IMP to be built using the same source files. For example, an optimized one (using build='fast') and a debug one (build='debug').

To set this up

1. make a clean checkout of the source code

    svn co http://svn.salilab.org/imp/trunk src 
   

2. make a directory for your debug build

    mkdir imp-debug 
   

3. setup the debug directory

    src/tools/setup-out-of-source-build imp-debug 
   

4. edit imp-debug/config.py as desired
5. change into imp-debug

    cd imp-debug 
   

6. build

    scons -j 2 
   

   Note that this probably doesn't work on Windows.

You can update your copy of IMP, by typing

 svn update 

3. Prerequisites

In order to obtain and compile IMP, you will need:

• scons (0.98 or later)
• Boost (1.33 or later)
• Developers will also need a Subversion (svn) client to access the repository

If you wish to build the Python interfaces, you will also need:

• Python (2.3 or later)
• SWIG (1.3.40 or later)

If you install headers, libraries or tools anywhere other than the standard locations (i.e. /usr/lib and friends) then you need to tell SCons where to find them. This is done using the `includepath`, `libpath`, and `path` options (paths are colon-separated). These can either be passed to scons as command line arguments or put in the config.py file. For example

 scons includepath=/usr/local/include:/opt/local/include libpath=/usr/local/lib path=/usr/local/bin 

Tells IMP to search to headers and libraries in the provided locations in addition to the standard ones.

Notes on how to work around various platform issues can be found at the Build Notes page in the wiki.

Getting prerequisites on a Mac

Mac users should use one of the available collections of Unix tools, either MacPorts or Fink. If you use MacPorts, you must add /opt/local/bin to your path (either by modifying your shell's config file or by making an environment.plist file-see the FAQ) and then do

 sudo port install boost scons swig-python 

to install the needed libraries and tools. Alternatively, you can build the packages yourself from source code, but really, why bother.

Note:

Mac OS X 10.5 and 10.6 include a 'swig' binary, but it is too old to use with IMP. If you install SWIG with MacPorts above, you will need to make sure SCons picks up your SWIG rather than Apple's by setting the `path` option when running `scons`.

Do not install any C++ headers in `/usr/include` on your Mac as the compiler assumes any such headers are C headers.

Getting prerequisites on Windows

The SCons build system should work on Windows with the command line Microsoft Visual Studio compiler (`cl`) but it has not yet been tested; some of the subsidiary scripts may assume a Unix environment. (In the Sali lab, you can build a Windows version on `synth` by running `scons` in the usual way, giving the `wine=true` command line option.)

Getting prerequisites on Linux

All of the prerequisites should be available as pre-built packages for your Linux distribution of choice.

Optional dependencies

Locally built documentation will look prettier if you have graphviz installed. It is available as part of most unix tool sets (MacPorts, all linux distributions etc.).

If you want to use IMP with MODELLER, you should use version 9v7 or later and use the following argument to scons

 scons modeller=path/to/modeller 

(The Linux Modeller RPM installs in /usr/, while the Mac installer installs in /Library/modeller9v7/.)

Certain geometric computations will be faster, better or more reliable if CGAL is installed.

Where to go next

You are now ready to use IMP within Python and C++.

Everyone should read the Introduction and developers should then move on to the Developer guide.