Building HPX

CMake Variables used to configure HPX
CMake Toolchains shipped with HPX
Build recipes
Setting up the HPX Documentation Tool Chain
Basic Information

Once CMake has been run, the build process can be started. The HPX build process is highly configurable through CMake and various CMake variables influence the build process. The build process consists of the following parts:

For a complete list of available CMake variables that influence the build of HPX see CMake Variables used to configure HPX.

The variables can be used to refine the recipes that can be found here which show some basic steps on how to build HPX for a specific platform

In order to use HPX, only the core libraries are required (the ones marked as optional above are truly optional). When building against HPX, the CMake variable HPX_LIBRARIES will contain hpx and hpx_init (for pkgconfig, those are added to the Libs sections). In order to use the optional libraries, you need to specify them as link dependencies in your build (See Building Projects using HPX.

As HPX is a modern C++ Library we require a certain minimal set of features from the C++11 standard. In addition, we make use of certain C++14 features if the used compiler supports them. This means that the HPX build system will try to determine the highest support C++ standard flavor and check for availability of those features. That is, the default will be the highest C++ standard version available. If you want to force HPX to use a specific C++ standard version you can use the following CMake variables:

Build Types

CMake can be configured to generate project files suitable for builds that have enabled debugging support or for an optimized build (without debugging support). The CMake variable used to set the build type is CMAKE_BUILD_TYPE (for more information see the CMake Documentation). Available build types are:

[Important] Important

We currently don't guarantee ABI compatibility between Debug and Release builds. Please make sure that applications built against HPX use the same build type as you used to build HPX. For CMake builds, this means that the CMAKE_BUILD_TYPE variables have to match and for projects not using CMake, the HPX_DEBUG macro has to be set in debug mode.

Platform specific notes

Some Platforms require to have special link and/or compiler flags specified to build HPX. This is handled via CMake's support for different toolchains (see cmake-toolchains(7) for more information). This is also used for cross compilation.

HPX ships with a set of toolchains that can be used for compilation of HPX itself and applications depending on HPX. Please see CMake Toolchains shipped with HPX for more information.

In order to enable full static linking with the __libraries, the CMake variable HPX_WITH_STATIC_LINKING has to be set to On.

Debugging applications using core files

For HPX to generate useful core files, HPX has to be compiled without signal and exception handlers (HPX_WITH_DISABLED_SIGNAL_EXCEPTION_HANDLERS). If this option is not specified, the signal handlers change the application state. For example, after a segmentation fault the stack trace will show the signal handler. Similarly, unhandled exceptions are also caught by the these handlers and the stack trace will not point to the location where the unhandled exception was thrown.

In general, core files are a helpful tool to inspect the state of the application at the moment of the crash (post-mortem debugging), without the need of attaching a debugger beforehand. This approach to debugging is especially useful if the error cannot be reliably reproduced, as only a single crashed application run is required to gain potentially helpful information like a stacktrace.

To debug with core files, the operating system first has to be told to actually write them. On most unix systems this can be done by calling

ulimit -c unlimited

in the shell. Now the debugger can be started up with:

gdb <application> <core file name>

The debugger should now display the last state of the application. The default file name for core files is core.