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