Cmake

Why use CMake

IMP is now build using CMake. The key advantage of cmake over scons is that cmake separates the configure and build phases making edit, build, test loops much faster when you make small changes. When used with ninja compilation starts almost instantly.

Differences from SCons

CMake is a system for generating makefiles or config files for other build systems (e.g. XCode projects, VisualStudio project files, Ninja build files). All of the (expensive) configuration work is done when you run cmake, after that, you run make (or whatever other build command you use), to build IMP and then ctest to run tests.

Build files created by CMake will automatically rerun CMake when any of the CMake config files changes. You need to manually rerun cmake when

• your build environment changes (e.g. boost gets updated)
• you add or remove source files/tests
• you change the set of enabled modules
• your build configuration changes (e.g. from Debug to Release build)

The result is that build/test cycles are much faster than with SCons.

CMake stores the settings for this particular build in a CMakeCache.txt file in the build directory. Settings can be set either by passing arguments to cmake (eg cmake -DIMP_DISABLED_MODULES=isd:example) or by running ccmake (ccmake .) and setting the value in there. Ultimately, the CMakeCache.txt can be left around as an equivalent of the scons config.py file, but for now probably shouldn't be.

CMake does not support in source builds. They are a bad idea anyway.

Many compiler flags that were controlled by scons flags are things you should set directly with cmake. For example, for C++ 11, you should add

• -std=c++11 for clang++ or g++ > 4.7
• -std=gnu++0x for g++ 4.2 to 4.6

or -fcolor-diagnostics for clang++.

Also, instead of imppy.sh the file to set up the environment for running from the build directory is called setup_environment.sh.

Building IMP with CMake

There are two different ways to configure with cmake, one is to run cmake in a fresh directory passing some options on the command line and the other is to run ccmake and use its editor to change options. For both, assume you are in a directory called debug and the imp source is in a directory at ../imp. We are using the default of makefiles for the actual building.

Configuring with cmake

To simply configure and build as simply as possible do

1. cmake ../imp
2. make -j 8

To make a debug build of IMP with the cgal and membrane modules disabled and core compiled in per-cpp mode, and use Ninja as your build command do:

1. cmake ../imp -DCMAKE_BUILD_TYPE=Debug -G Ninja -DIMP_DISABLED_MODULES=cgal:membrane -DIMP_PER_CPP_COMPILATION=core
2. ninja -j 8

Configuring using ccmake

1. run ccmake ../imp
2. set CMAKE_BUILD_TYPE to Debug
3. set IMP_DISABLED_MODULES to em:isd
4. tell cmake to generate (hit g) and configure (hit c)
5. make -j 8

You can run ccmake after running cmake as above if you want, too. Running it never hurts.

Further configuration options

You can use ninja instead, if it is available by passing -G Ninja to the (c)cmake call. That is highly recommended when it is available.

Various aspects of IMP build behavior can be controlled via various 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:

• IMP_DISABLED_MODULES: A colon-separated list of disabled modules.
• IMP_MAX_CHECKS: One of NONE, USAGE, INTERNAL to control what check levels will be supported.
• IMP_MAX_LOG: One of SILENT, PROGRESS, TERSE, VERBOSE to control what log levels are supported.
• IMP_PER_CPP_COMPILATION: A colon-separated list of modules to build one .cpp at a time.
• CMAKE_BUILD_TYPE: one of Debug or Release.

An equivalent of the scons fast build is to set

• CMAKE_BUILD_TYPE=Release
• IMP_MAX_CHECKS=NONE
• IMP_MAX_LOG=SILENT

Testing IMP

Test are run using ctest. A good start is to run ctest --output-on-failure.

Note that things required by the tests are not built automatically; you have to build them first. We may change this, but we could never really get it right with scons.

Tests are labeled with the module name and are named after the file that is run, so to run just the expensive tests in the atom module, use ctest -L "^IMP.atom$" -R expensive.

Benchmarks are tests with an extra label benchmark; examples are tests with an extra label example.

CMake usage in IMP

CMake is configured in IMP using a CMakeLists.txt file in each application and module bin, src, test and example directory. These CMakeLists.txt are auto generated via build/tools/setup_cmake.py which is run automatically every time cmake is run. These files are stored in the repository so adding or removing files causes changes that get picked up by cmake when others check out your changes.

Modules that need to do custom configuration work (see base), can put CMake code in a Setup.cmake file in their module directory.