Troubleshooting#

Common issues#

This section contains commonly encountered problems when compiling or using HPX.

See also the closed issues on GitHub to find out how other people resolved a similar problem. If nothing of that works, you can also open a new issue on GitHub or contact us using one the options found in Support for deploying and using HPX.

Undefined reference to hpx::cout#

You may see a linker error message that looks a bit like this:

hello_world.cpp:(.text+0x5aa): undefined reference to `hpx::cout'

This usually happens if you are trying to use HPX iostreams functionality such as hpx::cout but are not linking against it. The iostreams functionality is not part of the core HPX library, and must be linked to explicitly. Typically this can be solved by adding COMPONENT_DEPENDENCIES iostreams to a call to add_hpx_library/add_hpx_executable/hpx_setup_target if using CMake. See Creating HPX projects for more details.

Fail compiling for examples with hpx::future and co_await#

You may see an error message that looks a bit like this:

error: coroutines require a traits template; cannot find 'std::coroutine_traits'

This can be resolved by using -DHPX_WITH_CXX_STANDARD=20 to the cmake command line. Note that a compiler that supports C++20 is needed.

See also the corresponding closed Issue #5784.

Build fails with ASIO error#

You may see an error message that looks a bit like this:

Cannot open include file asio/io_context.hpp

This can be resolved by using -DHPX_WITH_FETCH_ASIO=ON to the cmake command line.

See also the corresponding closed Issue #5404 for more information.

Build fails with TCMalloc error#

You may see an error message that looks a bit like this:

Could NOT find TCMalloc (missing: TCMALLOC_LIBRARY TCMALLOC_INCLUDE_DIR)
ERROR: HPX_WITH_MALLOC was set to tcmalloc, but tcmalloc could not be
found.  Valid options for HPX_WITH_MALLOC are: system, tcmalloc, jemalloc,
mimalloc, tbbmalloc, and custom

This can be resolved either by defining HPX_WITH_MALLOC=system or by installing TCMalloc. This error occurs when users don’t specify an option for HPX_WITH_MALLOC; in that case, HPX will be looking tcmalloc, which is the default value.

Useful suggestions#

Reducing compilation time#

If you want to significantly reduce compilation time, you can just use the local part of HPX for parallelism by disabling the distributed functionality. Moreover, you can avoid compiling examples. These can be done with the following flags:

-DHPX_WITH_NETWORKING=OFF
-DHPX_WITH_DISTRIBUTED_RUNTIME=OFF
-DHPX_WITH_EXAMPLES=OFF
-DHPX_WITH_TESTS=OFF

Linking HPX to your application#

If you want to avoid installing and linking HPX, you can just build HPX and then use the following flag on your HPX application CMake configuration:

-DHPX_DIR=<build_dir>/lib/cmake/HPX

Note

For this to work you need not to specify -DCMAKE_INSTALL_PREFIX when building HPX.

HPX-application build type conformance#

Your application’s build type should align with the HPX build type. For example, if you specified -DCMAKE_BUILD_TYPE=Debug during the HPX compilation, then your application needs to be compiled with the same flag. We recommend keeping a separate build folder for different build types and just point accordingly to the type you want by using -DHPX_DIR=<build_dir>/lib/cmake/HPX.