1 CMake configuration options {#cmake_config}
2 ===========================
6 # Building with CMake {#cmake_building}
9 [building from source](@ref installation_compilation).
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.
17 # Configuring with cmake command line options {#cmake_cmdline}
19 To configure and build as simply as possible
do
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
29 cmake ../imp -DCMAKE_BUILD_TYPE=Debug -G Ninja -DIMP_DISABLED_MODULES=cgal:membrane -DIMP_PER_CPP_COMPILATION=core
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`)
39 You can run `ccmake` after running `cmake` as above
if you want, too.
40 Running it never hurts.
42 # Further configuration options {#cmake_further}
44 You can use [Ninja](https:
45 instead
if it is available by passing `-G Ninja` to the `(c)cmake` call.
46 That is highly recommended when it is available.
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).
56 There also are a [variety of standard cmake options](https:
57 which control the build. For example:
58 - `CMAKE_INCLUDE_PATH` and `CMAKE_LIBRARY_PATH` control the paths CMake searches
59 in to locate %IMP prerequisite libraries. If your libraries are installed in
60 non-standard locations, you can set these variables to help CMake find them.
61 For example, on a 32-bit RHEL5 system, which has both Boost and HDF5 in
62 non-standard locations, we use
64 -DCMAKE_INCLUDE_PATH=
"/usr/include/boost141;/usr/include/hdf518/" -DCMAKE_LIBRARY_PATH=
"/usr/lib/boost141;/usr/lib/hdf518"
66 - `CMAKE_INSTALL_PREFIX` should be set
if you want to install %IMP in a
67 non-standard location.
69 # Workarounds
for common CMake issues {#cmake_issues}
71 ## Python binary/header mismatch {#cmake_python}
73 In order to build %IMP Python extensions, CMake needs to find the Python header
74 and library files that match the `python3` or `python` binary. If
using a
75 recent version of CMake (3.14 or later) it should have no issues in doing so.
76 However, old versions of CMake might
get confused
if you have multiple versions
77 of Python installed (
for example on a Mac with [Homebrew](https:
78 and find the headers
for one version and the binary
for another. This can
79 be worked around by explicitly telling CMake where your Python library and
80 headers are by setting the `PYTHON_LIBRARY` and `PYTHON_INCLUDE_DIR` CMake
83 For example, on a Mac with Homebrew, where `python` is Homebrew
's
84 `/usr/local/bin/python`, old versions of CMake will often find Apple's Python
85 headers. This can be resolved (
if you cannot upgrade CMake to 3.14 or later)
86 by telling CMake where the Homebrew Python headers and library
87 are, by addinng to your CMake invocation something like
88 `-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`
90 ## CMake reports that it found a dependency but then reports failed {#cmake_compile}
92 For each dependency CMake will first
try to find the header and library
93 files
for that dependency, reporting success
if it finds them. Next, it will
94 often
try to build a small C or C++ test program that uses those headers
95 and libraries. If
this fails the dependency cannot be used (and CMake will,
96 somewhat confusing, report that the dependency was first found and then not
97 found). To fix issues like
this, check the CMake error log in
98 `CMakeFiles/CMakeError.log` to see what failed. In some cases
this can be
99 fixed by modifying the flags passed to the C or C++ compiler. For example,
100 recent versions of [Protobuf](https:
101 fail on some systems because they require C++11 support, and
this can be
102 fixed by adding to your CMake invocation
103 `-DCMAKE_CXX_FLAGS=
"-std=c++11"`
105 ## Wrong version of helper binaries found {#cmake_path}
107 Note also that CMake searches in the system path (`PATH` environment variable)
108 for command line tools such as `python` and `swig`. Thus,
if you have multiple
109 versions of tools (e.g. `/usr/bin/swig` and `/usr/local/bin/swig`) make sure
110 the `PATH` variable is set correctly so that the right tool is found *before*
111 you run CMake. You may need to make symlinks or copies to help it out if your
112 binaries are named oddly; for example on a RHEL5 system we need to force CMake
113 to use `/usr/bin/python2.6` rather than `/usr/bin/python` (which is Python 2.4,
114 which is too old to work with %IMP) by doing something like:
117 ln -sf /usr/bin/python26 bin/python