IMP logo
IMP Manual  for IMP version 2.5.0
installation.md
1 Installation {#installation}
2 ============
3 
4 [TOC]
5 
6 # Binary installation {#installation_binary}
7 
8 Binary installation is strongly recommended for new users of IMP. It is
9 much faster than building from source code, requires a smaller download,
10 and all the necessary prerequisites are handled for you automatically.
11 
12 We recommend you use a stable release. These are available for
13 Windows, Mac and Linux from our [download page](http://integrativemodeling.org/download.html#stable).
14 
15 Binaries are [also available for our latest nightly builds](http://integrativemodeling.org/download.html#develop). If you do decide to use a nightly build,
16 please check out the [nightly builds results page](http://integrativemodeling.org/nightly/results/)
17 to see if the code is currently stable enough for your purposes.
18 
19 # Source code installation {#installation_source}
20 
21 ## Prerequisites {#installation_prereqs}
22 
23 In order to build IMP from source, you will need:
24 
25 - [CMake](http://www.cmake.org) (2.8 or later)
26 - [Boost](http://www.boost.org) (1.40 or later)
27 - [HDF5](http://www.hdfgroup.org/HDF5/) (1.8 or later)
28 - [Python](http://www.python.org) (2.6 or later, or any version of Python 3)
29 - [SWIG](http://www.swig.org) (1.3.40 or later; 2.0.4 or later is needed
30  if you want to use Python 3)
31 
32 The following prerequisites are _optional_; without them some parts of IMP
33 will not build, and some will not function optimally.
34 
35 - [Doxygen](http://www.doxygen.org/) (only exactly version 1.8.6 is supported)
36  and [Graphviz](http://www.graphviz.org/): Required for building
37  documentation.
38 - [Modeller](\ref modeller): needed to use the IMP.modeller module
39 - [CGAL](\ref CGAL): enables faster geometric operations, such as
40  nonbonded lists.
41 - [Google perf tools](\ref perf): needed only for profiling IMP code.
42 - [ANN](\ref ANN): certain data structures will be faster if it is available.
43 - [GSL](\ref GSL): needed to use the IMP.gsl module
44 - [OpenCV](\ref OpenCV): needed to use the IMP.em2d module or the
45  [idock](@ref idock_pcsk9) and [emagefit](@ref emagefit_3sfd) command
46  line tools.
47 - [FFTW](http://www.fftw.org): need to use the IMP.em2d or IMP.multifit modules
48  or the [multifit](@ref multifit_3sfd) command line tool.
49 - [libTAU](http://integrativemodeling.org/libTAU.html): needed to use the
50  IMP.cnmultifit module or the [cnmultifit](@ref cnmultifit_groel) command
51  line tool.
52 - An [MPI](@ref IMP::mpi) library is needed to use the IMP.mpi module.
53 - The [numpy, scipy](http://www.scipy.org/scipylib/download.html),
54  [scikit-learn](http://scikit-learn.org/stable/install.html),
55  [matplotlib](http://matplotlib.org/downloads.html) and
56  [biopython](http://biopython.org/wiki/Download) Python libraries are also
57  recommended.
58 - [Chimera](https://www.cgl.ucsf.edu/chimera/download.html) is recommended
59  for visualization of results
60 
61 ### Getting prerequisites on Linux {#installation_prereqs_linux}
62 All of the prerequisites should be available as pre-built packages for
63 your Linux distribution of choice.
64 
65 ### Getting prerequisites on a Mac {#installation_prereqs_mac}
66 
67 Mac users must first install Xcode (previously known as Developer Tools)
68 which is not installed by default with OS X, but is available from the App store
69 (or from the Mac OS install DVD for old versions of Mac OS). They will also
70 need the Xcode command line tools (install by going to Xcode Preferences, then
71 Downloads, then Components, and select "Command Line Tools").
72 
73 Then Mac users should use one of the available collections of Unix tools,
74 such as
75 - [Homebrew](http://brew.sh) (_recommended_) Once you installed `homebrew`
76  do
77 
78  brew tap homebrew/science
79  brew tap salilab/salilab
80  brew install boost gmp google-perftools cgal graphviz gsl cmake doxygen hdf5 swig fftw mpfr libtau
81 
82  to install everything IMP finds useful (or that you will want for installing various useful Python libs that IMP finds useful). On older Macs, you may also need to `brew install git` if you want to use git (newer Macs include git).
83 - [Macports](http://www.macports.org/) If you use MacPorts, you must add `/opt/local/bin` to your path (either by modifying your shell's
84  config file or by making an `environment.plist` file) and then do
85 
86  sudo port install boost cmake swig-python
87 
88  to install the needed libraries and tools. When installing HDF5 with MacPorts, be sure to install `hdf5-18`
89  (version 1.8), rather than the older `hdf5` (version 1.6.9).
90 - or [Fink](http://www.finkproject.org/) (not supported)
91 
92 ### Getting prerequisites on Windows {#installation_prereqs_windows}
93 
94 We recommend Linux or Mac for developing with IMP, as obtaining the
95 prerequisites on Windows is much more involved. However, if you really want
96 to build on Windows, see the
97 [building from source code on Windows](@ref install_windows) page for the
98 procedure we use.
99 
100 
101 ## Download {#installation_download}
102 
103 - Download the source code tarball from [our download page](http://integrativemodeling.org/download.html#source), then extract it with something like:
104 
105  tar -xvzf ../imp-<version>.tar.gz
106 
107 - Alternatively you can use [git](http://git-scm.com/) to get the code
108  directly from our [GitHub repository](https://github.com/salilab/imp)
109  with something like:
110 
111  git clone -b master https://github.com/salilab/imp.git
112  (cd imp && ./setup_git.py)
113 
114  (the `master` branch tracks the most recent stable
115  release; alternatively you can use `develop` to get the most recent code,
116  but please check out the [nightly builds results page](http://integrativemodeling.org/nightly/results/)
117  to see if the code is currently stable enough for your purposes).
118 
119 ## Compilation {#installation_compilation}
120 
121 Make a separate directory to keep the compiled version of IMP in (it's tidier
122 to keep this separate from the source code, and if you need to later you can
123 just delete this directory without affecting the source). Set up the build
124 with [CMake](@ref cmake_config), then finally compile it, with something
125 like:
126 
127  mkdir imp_release
128  cd imp_release
129  cmake <path to IMP source>
130  make -j8
131 
132 There are a number of ways in which IMP can be configured.
133 See [the configuration options page](@ref cmake_config) for more details.
134 
135 ## Testing {#installation_testing}
136 Once the compilation is complete, you can optionally run the test suite.
137 Test are run using `ctest`. A good start is to run `ctest --output-on-failure`.
138 
139 Tests are labeled with the module name and the type and cost of the test, so to run just the expensive tests in the `atom` module, use `ctest -L "^IMP\.atom\-test\-.*EXPENSIVE"`.
140 
141 Benchmarks are simply tests labeled as `benchmark`; examples are tests labeled as `example`.
142 
143 Note that some test failures are to be expected; compare the failures with
144 those at our own [nightly builds page](http://integrativemodeling.org/nightly/results/)
145 if you are concerned.
146 
147 ## Installation {#installation_install}
148 
149 Once everything is compiled (and optionally tested) you can install IMP
150 by simply running `make install`. If you opted to install in a non-standard
151 location, it is up to you to set up your environment variables so that IMP
152 can be found (you may need to set `PATH`, `PYTHONPATH`, and `LD_LIBRARY_PATH`).
153 
154 Alternatively, you can run IMP directly from the build directory by using
155 the `setup_environment.sh` script. This sets the necessary environment
156 variables and then runs the rest of the command line with this modified
157 environment. For example, to run the `ligand_score` command line tool you
158 can either run
159 
160  ./setup_environment.sh ligand_score <arguments>
161 
162 or create a new shell with
163 
164  ./setup_environment.sh $SHELL
165 
166 and then run
167 
168  ligand_score <arguments>
169 
170 in that shell.