IMP logo
IMP Manual  for IMP version 2.16.0
cmake_config.md
1 CMake configuration options {#cmake_config}
2 ===========================
3 
4 [TOC]
5 
6 # Building with CMake {#cmake_building}
7 
8 We use [CMake](https://cmake.org) to configure the %IMP build when
9 [building from source](@ref installation_compilation).
10 
11 There are two different ways to configure with `cmake`; one is to run `cmake`
12 in a fresh directory passing some options on the command line, and the other
13 is to run `ccmake` and use its editor to change options. For both, assume you
14 are in a directory called `debug` and the %IMP source is in a directory at
15 `../imp`. We are using the default of makefiles for the actual building.
16 
17 # Configuring with cmake command line options {#cmake_cmdline}
18 
19 To configure and build as simply as possible do
20 
21  cmake ../imp
22  make -j8
23 
24 To make a debug build of %IMP with the `cgal` and `membrane` modules disabled
25 and `core` compiled in per-cpp mode, and to use
26 [Ninja](https://ninja-build.org/) instead of `make` as your build
27 command do:
28 
29  cmake ../imp -DCMAKE_BUILD_TYPE=Debug -G Ninja -DIMP_DISABLED_MODULES=cgal:membrane -DIMP_PER_CPP_COMPILATION=core
30  ninja -j8
31 
32 # Configuring using ccmake {#ccmake_config}
33 1. Run `ccmake ../imp`
34 You can then look through the various options available.
35 2. If you want a debug build, set `CMAKE_BUILD_TYPE` to `Debug`
36 3. Tell cmake to configure (hit `c`) and generate (hit `g`)
37 4. `make -j8`
38 
39 You can run `ccmake` after running `cmake` as above if you want, too.
40 Running it never hurts.
41 
42 # Further configuration options {#cmake_further}
43 
44 You can use [Ninja](https://ninja-build.org/)
45 instead if it is available by passing `-G Ninja` to the `(c)cmake` call.
46 That is highly recommended when it is available.
47 
48 Various aspects of %IMP build behavior can be controlled via variables. These can be set interactively using `ccmake` (eg `ccmake ../imp`) or by passing them with `-D` in a call to `cmake`. Key ones include:
49 - `CMAKE_BUILD_TYPE`: one of `Debug` or `Release`.
50 - `IMP_DISABLED_MODULES`: A colon-separated list of disabled modules.
51 - `IMP_MAX_CHECKS`: One of `NONE`, `USAGE`, `INTERNAL` to control what check levels will be supported. The default is `USAGE` for release builds and `INTERNAL` for debug builds (setting this to `INTERNAL` will impact performance; `NONE` is not recommended as all sanity checks will be skipped).
52 - `IMP_MAX_LOG`: One of `SILENT`, `PROGRESS`, `TERSE`, `VERBOSE` to control what log levels are supported.
53 - `IMP_PER_CPP_COMPILATION`: A colon-separated list of modules to build one .cpp at a time.
54 - `USE_PYTHON2`: Set to `on` to have CMake build %IMP with Python 2 (by default it will use Python 3 if available).
55 - `IMP_USE_SYSTEM_RMF`: Set to `on` to build %IMP using an external (system) copy of the RMF library, instead of that bundled with IMP itself.
56 - `IMP_USE_SYSTEM_IHM`: Set to `on` to build %IMP using an external (system) copy of the python-ihm library, instead of that bundled with IMP itself.
57 
58 There also are a [variety of standard cmake options](https://gitlab.kitware.com/cmake/community/wikis/doc/cmake/Useful-Variables)
59 which control the build. For example:
60 - `CMAKE_INCLUDE_PATH` and `CMAKE_LIBRARY_PATH` control the paths CMake searches
61  in to locate %IMP prerequisite libraries. If your libraries are installed in
62  non-standard locations, you can set these variables to help CMake find them.
63  For example, on a 32-bit RHEL5 system, which has both Boost and HDF5 in
64  non-standard locations, we use
65 
66  -DCMAKE_INCLUDE_PATH="/usr/include/boost141;/usr/include/hdf518/" -DCMAKE_LIBRARY_PATH="/usr/lib/boost141;/usr/lib/hdf518"
67 
68 - `CMAKE_INSTALL_PREFIX` should be set if you want to install %IMP in a
69  non-standard location.
70 
71 # Workarounds for common CMake issues {#cmake_issues}
72 
73 ## Python binary/header mismatch {#cmake_python}
74 
75 In order to build %IMP Python extensions, CMake needs to find the Python header
76 and library files that match the `python3`, `python2` or `python` binary. If using a
77 recent version of CMake (3.14 or later) it should have no issues in doing so.
78 However, old versions of CMake might get confused if you have multiple versions
79 of Python installed (for example on a Mac with [Homebrew](https://brew.sh/)),
80 and find the headers for one version and the binary for another. This can
81 be worked around by explicitly telling CMake where your Python library and
82 headers are by setting the `PYTHON_LIBRARY` and `PYTHON_INCLUDE_DIR` CMake
83 variables.
84 
85 For example, on a Mac with Homebrew, where `python` is Homebrew's
86 `/usr/local/bin/python`, old versions of CMake will often find Apple's Python
87 headers. This can be resolved (if you cannot upgrade CMake to 3.14 or later)
88 by telling CMake where the Homebrew Python headers and library
89 are, by adding to your CMake invocation something like
90 `-DPYTHON_LIBRARY=/usr/local/opt/python@2/Frameworks/Python.framework/Versions/Current/lib/libpython2.7.dylib -DPYTHON_INCLUDE_DIR=/usr/local/opt/python@2/Frameworks/Python.framework/Versions/Current/Headers`
91 
92 ## CMake reports that it found a dependency but then reports failed {#cmake_compile}
93 
94 For each dependency CMake will first try to find the header and library
95 files for that dependency, reporting success if it finds them. Next, it will
96 often try to build a small C or C++ test program that uses those headers
97 and libraries. If this fails the dependency cannot be used (and CMake will,
98 somewhat confusing, report that the dependency was first found and then not
99 found). To fix issues like this, check the CMake error log in
100 `CMakeFiles/CMakeError.log` to see what failed. In some cases this can be
101 fixed by modifying the flags passed to the C or C++ compiler. For example,
102 recent versions of [Protobuf](https://developers.google.com/protocol-buffers/)
103 fail on some systems because they require C++11 support, and this can be
104 fixed by adding to your CMake invocation
105 `-DCMAKE_CXX_FLAGS="-std=c++11"`
106 
107 ## Wrong version of helper binaries found {#cmake_path}
108 
109 Note also that CMake searches in the system path (`PATH` environment variable)
110 for command line tools such as `python` and `swig`. Thus, if you have multiple
111 versions of tools (e.g. `/usr/bin/swig` and `/usr/local/bin/swig`) make sure
112 the `PATH` variable is set correctly so that the right tool is found *before*
113 you run CMake.