Building HAL’s MD package

Compilation and Installation

HALMD uses CMake to generate its make files, which is similar to the more commonly used Autotools suite recognisable by the configure script accompanying a software package, but much faster and much easier to develop with.

With cmake, out-of-tree compilation is preferred, so we generate the compilation or build tree in a separate directory. This allows one to have multiple builds of the same software at the same time, for example a release build with aggressive optimisation and a debug build including debugging symbols. Note that the build directory may be a subdirectory in the source tree.

Setting up the build tree

In the cloned HALMD repository, switch to a new build directory:

mkdir -p build/release && cd build/release

If the third-party packages are installed in standard locations, run

cmake ../..

This will detect all necessary software, and then generate the make files. If third-party packages are not found in standard locations, make sure to correctly set the environment variable CMAKE_PREFIX_PATH, see Software prerequisites.

Note

CMake ≤ 3.0 may have problems locating a CUDA host compiler (especially if you use nvcc.profile to specify a compiler directory). If you experience errors like “-m64: No such file or directory” when compiling cuda sources, the problem can be solved by manually setting the CMake variable CUDA_HOST_COMPILER to the full path of the desired host compiler. CMake ≥ 3.1 fixes this problem.

The problem does not occur for builds without GPU acceleration.

Compilation

Compilation is done using make, which supports parallel builds:

nice make -j4

The default installation directory is /usr/local, which may be adjusted by invoking

cmake -DCMAKE_INSTALL_PREFIX=$HOME/opt/halmd-version ../..

For compilation and subsequent installation type:

nice make -j4 install

Further CMake configuration

Compilation flags may be configured via CMake’s text mode interface:

ccmake .

To finish configuration, hit “c” and “g” to apply and recompile with make. Alternatively, you may use CMake’s graphical interface:

cmake-gui .

The following switch displays the actual commands invoked by make:

CMAKE_VERBOSE_MAKEFILE        ON

An installation prefix may be specified as following:

CMAKE_INSTALL_PREFIX          /your/home/directory/usr

The compiled program is then installed into this tree by

nice make -j4 install

Updating the build tree

After checking out to a different version (or more recent Git commit), switch to the build directory (e.g., build/release) and run:

cmake .

This instructs CMake to regenerate the build tree using the configuration from the previous run of CMake. Then compile with make as usual.

Setting build parameters

Parameters may be passed to cmake as environment variables or cache variables.

Environment variables are prepended to the cmake command:

CXXFLAGS="-fPIC -Wall" cmake ../..

Useful environment variables for CMake

Cache variables are appended using the -D option:

cmake -DCMAKE_BUILD_TYPE=Release ../..

Useful CMake cache variables

The following example demonstrates how to compile separate, dynamically linked executables for each backend, which are statically linked to all libraries except the standard C and C++ libraries:

CXXFLAGS="-fPIC -Wall"
NVCCFLAGS="-Xcompiler -fPIC -Xptxas -v -arch sm_61" \
cmake \
    -DCMAKE_BUILD_TYPE=Release \
    ../..

The options given here correspond to the default values.

Testing

HALMD includes an extensive, preliminary test suite, which may be started in the build tree by

ctest

Supported compilers

HALMD requires a C++ compiler with sufficient C++14 support. Building has been tested with the following compilers:

  • GCC
    • GCC 10.2.1 on Debian 11 (x86_64)
    • GCC 8.3.0 on Debian 10 (x86_64)
    • GCC 5.3.0 and 9.3.0 (upstream) on Debian 10 (x86_64)
  • Clang
    • Clang 7.0.1 on Debian 10 (x86_64)
    • Clang 3.9.1 on Debian 10 (x86_64)