Using HPX with CMake based projects

In Addition to the pkg-config support discussed on the previous pages, HPX comes with full CMake support. In order to integrate HPX into your existing, or new CMakeLists.txt you can leverage the find_package command integrated into CMake. Following is a Hello World component example using CMake.

Let's revisit what we have. We have three files which compose our example application:

The basic structure to include HPX into your CMakeLists.txt is shown here:

# Require a recent version of cmake
cmake_minimum_required(VERSION 2.8.4 FATAL_ERROR)

# This project is C++ based.
project(your_app CXX)

# Instruct cmake to find the HPX settings

In order to have CMake find HPX, it needs to be told where to look for the HPXConfig.cmake file that is generated when HPX is built or installed, it is used by find_package(HPX) to set up all the necessary macros needed to use HPX in your project. The ways to achieve this are

Additionally, if you wish to require HPX for your project, replace the find_package(HPX) line with find_package(HPX REQUIRED).

You can check if HPX was successfully found with the HPX_FOUND CMake variable.

The simplest way to add the HPX component is to use the add_hpx_component macro and add it to the CMakeLists.txt file:

# build your application using HPX
    SOURCES hello_world_component.cpp
    HEADERS hello_world_component.hpp

The available options to add_hpx_component are:

After adding the component, the way you add the executable is as follows:

# build your application using HPX
    SOURCES hello_world_client.cpp

When you configure your application, all you need to do is set the HPX_DIR variable to point to the installation of HPX!

[Note] Note

All library targets built with HPX are exported and readily available to be used as arguments to target_link_libraries in your targets. The HPX include directories are available with the HPX_INCLUDE_DIRS CMake variable

CMake macros to integrate HPX into existing Applications

In addition to the add_hpx_component and add_hpx_executable you can use the hpx_setup_target macro to have an already existing target to be used with the HPX libraries.


Optional Parameters are:

If you do not use CMake, you can still build against HPX but you should refer to the section on How to Build HPX Components with pkg-config.

[Note] Note

Since HPX relies on dynamic libraries, the dynamic linker needs to know where to look for them. If HPX isn't installed into a path which is configured as a linker search path, external projects need to either set RPATH or adapt LD_LIBRARY_PATH to point to where the hpx libraries reside. In order to set RPATHs, you can include HPX_SetFullRPATH in your project after all libraries you want to link against have been added. Please also consult the CMake documentation here