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).
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.
58 There also are a [variety of standard cmake options](https:
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
66 -DCMAKE_INCLUDE_PATH="/usr/include/boost141;/usr/include/hdf518/" -DCMAKE_LIBRARY_PATH="/usr/lib/boost141;/usr/lib/hdf518"
68 - `CMAKE_INSTALL_PREFIX` should be set if you want to install %IMP in a
69 non-standard location.
71 # Workarounds for common CMake issues {#cmake_issues}
73 ## Python binary/header mismatch {#cmake_python}
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:
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
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`
92 ## CMake reports that it found a dependency but then reports failed {#cmake_compile}
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:
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"`
107 ## Wrong version of helper binaries found {#cmake_path}
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*