IMP  2.3.1
The Integrative Modeling Platform
installation.md
1 Installation {#installation}
2 ============
3 
4 # Building and installing basics #
5 
6 [TOC]
7 
8 IMP is available in a variety of different ways. If you are just planning on using
9 existing IMP code and run on a standard platform, you may be able to install
10 a pre-built binary. See the [download](http://integrativemodeling.org/download.html) page.
11 
12 If you are planning on contributing to IMP, you should download and build the source.
13 See the next section for more information.
14 
15 
16 
17 Building IMP from source is straightforward if the [prerequisites](#prereqs)
18 are already installed.
19 
20  git clone git://github.com/salilab/imp.git
21  cd imp
22  ./setup_git.py
23  mkdir ../imp_release
24  cd ../imp_release
25  cmake ../imp -DCMAKE_BUILD_TYPE=Release
26  make -j 8
27 
28 See [Building IMP with CMake](https://github.com/salilab/imp/wiki/Cmake)
29 for more information.
30 
31 
32 # Prerequisites # {#installation_prereqs}
33 In order to obtain and compile IMP, you will need:
34 
35 - [cmake](http://www.cmake.org) (2.8 or later)
36 - [Boost](http://www.boost.org) (1.40 or later)
37 - [HDF5](http://www.hdfgroup.org/HDF5/) (1.8 or later)
38 - [Python](http://www.python.org) (2.6 or later)
39 - [SWIG](http://www.swig.org) (1.3.40 or later)
40 - Developers will also need a [git](http://git-scm.com/) client
41  to access the repository
42 
43 ## Getting prerequisites on a Mac ## {#installation_prereqs_mac}
44 
45 Mac users must first install Xcode (previously known as Developer Tools)
46 which is not installed by default with OS X, but is available from the App store
47 (or from the Mac OS install DVD for old versions of Mac OS). They will also
48 need the Xcode command line tools (install by going to Xcode Preferences, then
49 Downloads, then Components, and select "Command Line Tools").
50 
51 Then Mac users should use one of the available collections of Unix tools,
52 either
53 - [Homebrew](http://brew.sh) (_recommended_) Once you installed `homebrew`
54  do
55 
56  `brew tap homebrew/science`
57 
58  `brew tap salilab/salilab`
59 
60  `brew install boost gmp google-perftools cgal graphviz gsl cmake doxygen hdf5 swig fftw mpfr libtau`
61 
62  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).
63 - [Macports](http://www.macports.org/) If you use MacPorts, you must add `/opt/local/bin` to your path (either by modifying your shell's
64  config file or by making an `environment.plist` file) and then do
65 
66  `sudo port install boost cmake swig-python`
67 
68  to install the needed libraries and tools. When installing HDF5 with MacPorts, be sure to install `hdf5-18`
69  (version 1.8), rather than the older `hdf5` (version 1.6.9).
70 - or [Fink](http://www.finkproject.org/)
71 
72 ### Mac OS X 10.5 and 10.6
73 These versions of Mac OS X include a 'swig' binary, but it is too old to use
74 with IMP. You need to make sure that the newer version of `swig` is found first
75 in your `PATH`.
76 
77 
78 ## Getting prerequisites on Windows ## {#installation_prereqs_windows}
79 
80 We recommend Linux or Mac for developing with IMP, as obtaining the
81 prerequisites on Windows is much more involved. However, we do test IMP on
82 Windows, built with the Microsoft Visual Studio compilers (we use Visual Studio
83 Express 2010 SP1 for 32-bit Windows, and VS Express 2012 for 64-bit).
84 One complication is that different packages are compiled
85 with different versions of Visual Studio, and mixing the different runtimes
86 (msvc*.dll) can cause odd behavior; therefore, we recommend building most
87 of the dependencies from source code using the same version of Visual Studio
88 that you're going to use to build IMP. The basic procedure is as follows:
89 
90  - Install Microsoft Visual Studio Express (it is free, but registration with
91  Microsoft is required).
92  - Get and install [cmake](http://www.cmake.org).
93  - Get [Python 2](http://www.python.org) (not Python 3)
94  (make sure you get the
95  32-bit version if you're going to build IMP for 32-bit Windows).
96  - Get and install the
97  [zlib package](http://gnuwin32.sourceforge.net/packages/zlib.htm)
98  (both the "complete package, except sources" and the "sources" installers).
99  - The package without sources can be installed anywhere; we chose the
100  default location of `C:\Program Files\GnuWin32`. The sources, however,
101  must be installed in a path that doesn't contain spaces (otherwise the
102  Boost build will fail). We chose `C:\zlib`.
103  - We found that the zconf.h header included with zlib erroneously includes
104  unistd.h, which doesn't exist on Windows, so we commented out that line
105  (in both packages).
106  - Download the [Boost source code](http://www.boost.org)
107  (we extracted it into `C:\Program Files\boost_1_53_0`), then
108  - Open a Visual Studio Command Prompt, and cd into the directory where
109  Boost was extracted
110  - Run bootstrap.bat
111  - You may need to help the compiler find the zlib header file with
112  `set INCLUDE=C:\Program Files\GnuWin32\include`
113  - Run `bjam link=shared runtime-link=shared -sNO_ZLIB=0 -sZLIB_SOURCE=C:\zlib\1.2.3\zlib-1.2.3`
114  - Get and install [SWIG for Windows](http://www.swig.org)
115  - Get the [HDF5 source code](http://www.hdfgroup.org)
116  - Make a 'build' subdirectory, then run from a command prompt in
117  that subdirectory something similar to
118  `cmake.exe -G "Visual Studio 10" -DHDF5_ENABLE_SZIP_SUPPORT:BOOL=OFF -DHDF5_ENABLE_Z_LIB_SUPPORT:BOOL=ON -DHDF5_BUILD_HL_LIB:BOOL=ON -DZLIB_INCLUDE_DIR="C:\Program Files\GnuWin32\include" -DZLIB_LIBRARY="C:\Program Files\GnuWin32\lib\zlib.lib" -DBUILD_SHARED_LIBS:BOOL=ON ..`
119  - Open the resulting HDF5 solution file in Visual Studio, change to
120  Release configuration, then build the hdf5 project.
121  - (Optional) [Build CGAL from source code](http://www.cgal.org/windows_installation.html).
122  - (Optional) Download the
123  [FFTW DLLs](http://www.fftw.org/install/windows.html) and follow the
124  instructions at that website to make .lib import libraries needed for
125  Visual Studio.
126  - Copy `libfftw3-3.lib` to `fftw3.lib` to help cmake find it
127  - (Optional) Get the
128  [GSL source code](http://gnuwin32.sourceforge.net/packages/gsl.htm)
129  and build it:
130  - Open the libgsl project file in the `src\gsl\1.8\gsl-1.8\VC8`
131  subdirectory
132  - Build in Release-DLL configuration
133  - Copy the generated `libgsl.dll` and `libgslcblas.dll` to a suitable
134  location (we used `C:\Program Files\gsl-1.8\lib`)
135  - Copy the corresponding .lib files, libgsl_dll.lib and libgslcblas_dll.lib
136  (we recommend removing the _dll suffix and the lib prefix when you do
137  this so that cmake has an easier time finding them, i.e. call them
138  gsl.lib and gslcblas.lib).
139  - (Optional) Get [numpy and scipy](http://www.scipy.org) to match your
140  Python version.
141  - (Optional) Get and install
142  [libTAU](http://integrativemodeling.org/libTAU.html)
143  - Copy `libTAU.lib` to `TAU.lib` to help cmake find it.
144  - (Optional) Get the [OpenCV source code](http://opencv.org/)
145  and build it by [following these instructions](http://docs.opencv.org/doc/tutorials/introduction/windows_install/windows_install.html)
146  - Copy each `opencv_*.lib` to a similar file without the version extension
147  (e.g. copy `opencv_ml244.lib` to `opencv_ml.lib`) to help cmake find it
148  - Set PATH, INCLUDE, and/or LIB environment variables so that the compiler
149  can find all of the dependencies. (We wrote a little batch file.)
150  - Set up IMP by running something similar to
151 
152  `cmake <imp_source_directory> -DCMAKE_BUILD_TYPE=Release -DCMAKE_CXX_FLAGS="/DBOOST_ALL_DYN_LINK /EHsc /D_HDF5USEDLL_ /DWIN32 /DGSL_DLL" -G "NMake Makefiles"`
153 
154  - Note: if building for 64-bit Windows, you may need to add `/bigobj` to `CMAKE_CXX_CFLAGS`.
155  - Then use simply 'nmake' (instead of 'make', as on Linux or Mac) to
156  build IMP. (cmake can also generate Visual Studio project files, but
157  we recommend nmake.)
158  - To use IMP or run tests, first run the setup_environment.bat file to set
159  up the environment so all the programs and Python modules can be found.
160  (This batch file needs to be run only once, not for each test.)
161 
162 ## Getting prerequisites on Linux
163 All of the prerequisites should be available as pre-built packages for
164 your Linux distribution of choice.
165 
166 # Optional prerequisites # {#installation_preqs_optional}
167 
168 IMP can make use of a variety of external tools to provide more or
169 better functionality.
170 
171 - [Doxygen](http://www.doxygen.org/) and [Graphviz](http://www.graphviz.org/): Required for building documentation. They are available as
172 part of most Unix tool sets (HomeBrew, all Linux distributions etc.).
173 - [Modeller](\ref modeller)
174 - [CGAL](\ref CGAL)
175 - [Google perf tools](\ref perf)
176 - [ANN](\ref ANN)
177 - [GSL](\ref GSL)
178 - [OpenCV](\ref OpenCV) is needed for IMP.em2d
179 - [libTAU](http://integrativemodeling.org/libTAU.html) is needed for IMP.cnmultifit
180 - [MPI](\ref impmpi)
181 
182 # Where to go next # {#installation_next}
183 
184 You are now ready to use IMP within Python and C++.
185 
186 Everyone should read the [introduction](\ref introduction) and developers should
187 then move on to the [Developer Guide](\ref devguide).