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. We recommend you get IMP from Subversion by

 svn checkout http://svn.salilab.org/imp/nightly/latest imp 

This will create directory called imp, containing a directory trunk. Go in to that directory and do

 scons prefix=place_to_install_imp install 

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.

1.1 Install IMP from a tarball

First, obtain the source code tarball from the download page. code there

1. Extract the tarball

    tar -xvzf imp-version.tar.gz 

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

    scons prefix=place_to_install_imp install 

1.2 Using the IMP 1.0 release

One can, instead, use the IMP 1.0 release. We don't recommend it as it is very old and are likely to respond to any problems by asking you to upgrade to the current Subversion version. But, if you still want to do this: First, obtain the source code tarball from the download page.

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/)

3. Building and installing for developers

To get started, if you have curl installed, you can do:

 curl -fsSLk http://svn.salilab.org/imp/trunk/tools/maintenance/make-developer-setup-read-only.sh | csh 

or, if you have write access,

 curl -fsSLk http://svn.salilab.org/imp/trunk/tools/maintenance/make-developer-setup.sh | csh 

Otherwise, just run the script by copying, doing

 cat | csh 

and pasting it into the terminal.

You can inspect the scripts before running by looking at make-developer-setup-read-only.sh or make-developer-setup.sh.

This creates a directory structure like

• imp
  • svn
    • trunk: the IMP source
  • debug: a directory for building IMP to use with the debugger
  • release: a directory for a release build of IMP which has checks turned on, but is faster than debug. Use this for testing scripts.
  • fast: a directory to build IMP with all checks disabled. Use this build for running large jobs.
  • update-to-nightly: run this script to update your source to the latest nightly build
  • update-to-head: run this script if you need a patch that someone just commited to the repository
  • show-changes: run this script to show what has changed in IMP since you last updated.
  • global_config.py: a configuration file (see next section) that is shared by the debug, fast and release builds.

To get started using IMP go into the release directory and do

 scons -j number_of_processors_on_your_machine -k 

In each build there is a script that sets up the environment to use that build eg debug/tools/imppy.sh. So to run a python script myscript.py using your debug build, do

 path/to/debug/tools/imppy.sh python myscript.py 

Note:

When you upgrade your system (eg get a new version of boost, or install a prerequisite), scons may not detect the package automatically. To force it to recheck, add the –config=force option when you run scons. In certain rare cases, scons may get really confused, and you may need to manually clear out the scons state. To do this, in the source directory do

 rm -rf .scon* 

3. Config files

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 top-level IMP directory (the one containing the SConstruct file). For example one of ours looks like

import os
import os.path

## for convenience
extra_roots=[]
if os.path.exists(os.path.join(os.environ['HOME'],"fs")):
    extra_roots.append(os.path.join(os.environ['HOME'],"fs"))
# for macports
if os.path.exists('/opt/local'):
    extra_roots.append('/opt/local')

## Where to install IMP
prefix=os.path.join(os.environ['HOME'], "imp")


pythonpath=""
includepath=""
libpath=""
swigpath=""
path=""
## Add my local environment to that used by scons and tools/imppy.sh
try:
    pythonpath=os.environ['PYTHONPATH']
except:
    pass
try:
    ldlibpath=os.environ['LD_LIBRARY_PATH']
except:
    pass

def add(old, root, dir):
    import os.path
    path=os.path.join(root, dir)
    if os.path.exists(path):
        return ":".join([old,path])
    else:
        return old

for r in extra_roots:
    includepath=add(includepath, r, "include")
    libpath=add(libpath, r, "lib")
    swigpath=add(swigpath, r, "share/imp/swig")
    path=add(path, r, "bin")

# uncomment if you are building an isolated module/application
#imp_build="/Users/drussel/src/IMP/imp/debug
#includepath=add(includepath, imp_build, "include")
#libpath=add(libpath, imp_build, "lib")
#swigpath=add(swigpath, imp_build, "swig")
#pythonpath=add(pythonpath, imp_build, "lib")

# You can add to the compiler flags directly, to, for example,
# add debuging symbols to a fast build.
# cxxflags= "-g -Wall"


## The build more can be one of 'debug', 'release' or 'fast'.
## It is recommended that you use a 'debug' build for testing and development
## and a 'fast' build for running the final code.
build='debug'

## It is recommented that you build in a different directory than the sources
## to do this, have your config.py and a link to the SConscruct files and scons_tools
## directories in the build directory and set 'repository' to a path to the source
## directory.
repository="path_to_source"

# Run all tests with valgrind
#precommand="valgrind --gen-suppressions=yes --db-attach=yes --undef-value-errors=no --suppressions=../svn/tools/valgrind-python.supp"

## Get modeller's location from an environment variable
#modeller=os.environ['MODINSTALLSVN']

For simple setups (such as a Linux build with no dependencies installed in odd places) the following would suffice.

repository="../svn"
includepath=""
libpath=""
path=""
ldlibpath=""
build="debug"

When building a module or biological system externally to the main IMP directory (but still using an svn copy of IMP, something like the following will do:

repository="../svn"
includepath="path_to_imp_build/include"
libpath="path_to_imp_build/lib"
path="path_to_imp_build/bin"
swigpath="path_to_imp_build/swig"
datapath="path_to_imp_build/data"
pythonpath="path_to_imp_build/lib"
ldlibpath="path_to_imp_build/lib"
build="debug"

An example configuration for a Windows system might look like

cxxflags="/DWIN32 /DGSL_DLL /D_HDF5USEDLL_"  # Needed to link with
                                             # GSL and HDF5 DLLs
boost_autolink="dynamic"        # Needed to link with Boost DLLs
fftw3="yes"
fftw3libs="libfftw3-3.lib"      # Needed to link with FFTW3 DLL

Finally, when building in a complicated environment, such as with the google native client, a config file might look like

root='/Users/drussel/fs-nacl/'
toolpath='/Users/drussel/src/naclports-mine/bin/'

boostversion='104300'
boostlibsuffix='-mt'
boost_filesystem='no'
boost_programoptions='no'
fftw3='no'
endian='little'
netcdfcpp='yes'
netcdfcpplibs='netcdf_c++:netcdf'
netcdflibpath='/Users/drussel/fs-nacl/lib'
netcdfincludepath='/Users/drussel/fs-nacl/include'
cgal='no'
ann='no'
annlibs='ANN'
gsl='yes'
gsllibs='gsl:gslcblas:m'
opencv21='no'
opencv22='no'
bullet='yes'
bulletlibs='BulletSoftBody:BulletDynamics:BulletCollision:LinearMath'
openmm='no'
build='debug'
repository='../svn'
prefix='/Users/drussel/fs-nacl/imp'
platformflags=False
cxxcompiler=toolpath+'g++'
ar=toolpath+'ar'
ranlib=toolpath+'ranlib'
cxxflags=' -fno-common -Wall -Wno-deprecated -Woverloaded-virtual -g'
includepath=root+'include
arliblinkflags=''
binlinkflags='-g -L'+root+'lib -lnosys'
python='False'
rpath='False'
static='True'
dynamic='False'
pkgconfig='False'
path=""
disabledmodules="saxs:em:em2d"

4. 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 must first install Xcode (previously known as Developer Tools) which is not installed by default with OS X, but is available from the App store (or from the Mac OS install DVD for old versions of Mac OS).

Then Mac users should use one of the available collections of Unix tools, either

• Homebrew: (recommended) Once you installed homebrew by running

   /usr/bin/ruby -e "$(curl -fsSL https://raw.github.com/gist/323731)" 

  do

   brew install boost gmp bullet google-perftools cgal graphviz scons gsl subversion doxygen hdf5 swig eigen llvm fftw mpfr gfortran 

  to install everything IMP finds useful (or that you will want for installing various useful python libs that IMP finds useful).
• MacPorts: 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. When installing HDF5 with MacPorts, be sure to install hdf5-18 (version 1.8), rather than the older hdf5 (version 1.6.9).
• or Fink

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 we have not been able to get it to work (but haven't tried very hard either). (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

IMP can make use of a variety of external tools to provide more or better functionality.

doxygen

Building the documentation requires Doxygen. In addition the documentation will look prettier if you have graphviz installed. It is available as part of most Unix tool sets (MacPorts, all Linux distributions etc.).

modeller

If you want to use IMP with MODELLER, you should use version 9v7 or later. If you installed the MODELLER Linux RPM or Mac package, it should be detected automatically. Otherwise, tell scons where you installed MODELLER using the following argument:

 scons modeller=path/to/modeller 

HDF5

Much IO support requires HDF5, at least version 1.8. It is available as a prebuilt package on all supported platforms.

CGAL

A wide variety of geometric computations will be faster, better or more reliable if CGAL is installed. CGAL is available as part of most Linux distributions and can be built from source on Mac OS or Linux. It is free for academic use, but commercial use requires a license.

ANN

ANN is a library implementing fast nearest neighbor searches. Certain data structures will be faster if it is installed. While compilation of the library from source is quite straight forward, it is not avaible as a package for common platforms. In addition, ANN must be built as a shared library rather than a static library. See the FAQ.

GSL

The IMP.gsl module requires GSL. It is available as a prebuilt package on all supported platforms. Note that GSL is distributed under the GPL and so cannot be used in C++ applications with certain other dependencies such as CGAL.

10. 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.