Building ProMod3¶

Dependencies¶

ProMod3 is build on top of OpenStructure (OST), requiring at least version 2.4.0. OST must be configured and compiled with ENABLE_MM=1 to use OpenMM. To create the build system, CMake is required. The same versions of Python and Boost are needed as used in OST. For Eigen 3 we need at least version 3.3.0. To build the documentation, Sphinx is required. We do not provide backwards compatibility to Python 2.7. The last release supporting Python 2.7 is 2.1.0 which also requires OST to be compiled with Python 2.7.

The currently preferred versions are:

• OST 2.4.0
• OpenMM 7.1.1
• CMake 3.12.1
• Python 3.6.0
• Boost 1.68.0
• Eigen 3 3.3.1
• Sphinx 1.4.9

Using CMake¶

CMake is used to configure the build system and in the end produces makefiles and certain directories needed for building ProMod3. Basically it is called right from a shell with the directory containing the top-level CMakeLists.txt as an argument. The preferred approach is to generate a build folder and configure and compile in there:

# execute this in the ProMod3 root folder
$ mkdir build
$ cd build
$ cmake .. -DOST_ROOT=<PATH TO OST>

For us, at least pointer to the OST installation directory is needed, handed over to CMake by -D into the variable OST_ROOT (e.g. OST headers would be located in OST_ROOT/include/ost).

Similarly, one can specify folders for Boost, Python and Eigen 3 if multiple versions exist and/or they are not installed in a default location. These are set with the BOOST_ROOT (make sure that’s the same as for OST), Python_ROOT_DIR and EIGEN3_INCLUDE_DIR.

Here is a list of more options used within ProMod3:

• DISABLE_DOCUMENTATION Don’t build documentation, don’t search for Sphinx
• DISABLE_DOCTEST Don’t run example code from documentation on make check (implicit by DISABLE_DOCUMENTATION)
• DISABLE_LINKCHECK Don’t test links from documentation on make check (implicit by DISABLE_DOCUMENTATION)
• ENABLE_SSE Allow for more agressive optimization by adding -msse4 flag to the compiler. At some places within the code, we use SSE intrinsics explicitely. This is only enabled if OST has been compiled with single precision. (OST_DOUBLE_PRECISION flag)

Since we use OST in the background, some of its options for CMake are also relevant, here. Basically they need to be set to exactly the same value. Even if ProMod3 builds with different settings, it may start producing funny results at an unexpected point. If you do not know the values, grep the option in the CMakeCache.txt of OST:

• OPTIMIZE
• OST_DOUBLE_PRECISION

Instead of calling CMake by yourself, there is the conf-scripts directory, providing smallish scripts to invoke CMake the right way for various systems. Usually those scripts just need the OST path and the location of the top-level CMakeLists.txt.

As mentioned earlier, we highly recommend to use out-of-source builds. This way, you can have several builds with different configurations. Also if anything goes wrong, just remove the build directory to get to a clean state again. No searching for CMake cache files or checking if certain files really got rebuild and similar things required.

Running Make¶

After configuring, you want to build ProMod3 by

$ make

to populate the stage directory with a ready-to-go version of the latest code.

Beside the usual make all and other default targets, there are a few special targets:

• check make check Runs unit tests and if CMake was invoked in its standard configuration also documentation examples (doctest) and links in the doc. (linkcheck) are checked
• html make html Creates documentation as web page using the Sphinx html builder
• man make man Creates a manual page using the Sphinx man builder
• doc make doc Creates documentation using the html and man targets
• help make help Prints a list of targets available

Installing ProMod3¶

If you wish to install ProMod3 (note that you can also safely keep it all in the stage directory), you can use

$ make install

By default, this will copy the stage directory to /usr/local. To override this, you can add the -DCMAKE_INSTALL_PREFIX=<INSTALL PATH> flag to your cmake call.

After the installation, you should be able to delete the whole source folder. To ensure that everything works, you can use a set of automated “sanity checks”. Please follow the instructions in extras/sanity_checks/README to setup and run those tests after moving the source folder. If everything works, you can safely delete the whole source folder.