IMP Tutorial
|
IMP is most commonly used as a Python library, controlled by writing Python scripts. To add additional functionality to IMP, usually a new IMP module is added.
However, IMP can also be used in other C++ code as a C++ library. This can be useful, for example, in writing command line tools that use IMP functionality.
In this tutorial, we will demonstrate how to compile and link a simple C++ program against the IMP library using the CMake build system. (CMake is not required to build C++ code - the C++ compiler can be run directly if desired - but CMake takes care of adding the various search paths for headers and libraries that the C++ compiler requires.)
First, download the files for this tutorial by using the "Clone or download" link at the tutorial's GitHub page.
First, let's look at the C++ program that will use IMP functionality, simple.cpp:
This is a very simple C++ program that uses IMP to create an IMP::Model, make two particles in that model, and set their XYZ coordinates using the IMP::core::XYZ decorator. It is essentially identical to the first part of the simple Python example in the IMP manual.
The FindIMP.cmake file, in the tools
subdirectory, is a script that helps CMake find your IMP installation. When IMP is built or installed, it creates a file called IMPConfig.cmake
which contains information about how IMP was configured and where all the parts of IMP can be found.
setup_environment.sh
is)./usr/lib64/cmake/IMP/
.The FindIMP.cmake
file searches common locations for the IMPConfig.cmake
file. It can be copied verbatim into your own CMake projects.
We don't use RMF in this tutorial, but if it is needed, there is a separate FindRMF.cmake file to help CMake find it. See the npctransport repository for an example of its use.
The main control script for CMake is CMakeLists.txt. This is a very simple file that instructs CMake to find IMP, and build an executable from our input file simple.cpp
. If you have not used CMake before, the CMake tutorial is a good introduction. Let's look at the parts in turn:
This uses CMake's standard find_package command to locate IMP. It relies on the FindIMP.cmake
file from above, so first we need to set CMAKE_MODULE_PATH
so that it can find that file.
Once IMP is found, the IMP_USE_FILE
CMake variable is set to the path of a file that is part of the IMP installation containing IMP-related CMake functions. We can use this file with the standard CMake include command.
We can now add the IMP header files to the compiler's search path using CMake's include_directories command. The SYSTEM
option here tells the compiler not to warn about any issues in the IMP headers (these should be addressed in IMP itself, not in this project). Since IMP also uses the Eigen and Boost packages we also need to add the directories these headers are stored in, as these may not be the same.
Next, we tell CMake that we want to make a single executable, simple
, by compiling the simple.cpp
C++ file.
Finally, we tell CMake that when we link the simple
executable, we need to link it against the IMP kernel and the IMP::core module.
We can now configure this project from the top-level directory (the one containing simple.cpp
and CMakeLists.txt
) by making a build directory and running CMake in it:
If this fails to find IMP, you can set the IMP_DIR
environment variable or CMake variable to the path containing IMPConfig.cmake
to help it out:
Once CMake completes successfully, we can build and run our program in the normal way, for example using
On Linux and Mac systems CMake will typically generate makefiles. You can have it generate files for other build systems using the
-G
option. For example,cmake -G Ninja
will generate files for the Ninja build tool, which is typically faster than traditional make for larger projects.