[Build System] UX Gap: -Wl,-wrap=main does not propagate to non-CMake consumers

[shivansh023023]

TITLE
[Build System] UX Gap: -Wl,-wrap=main does not propagate to non-CMake consumers

Summary

When linking HPX statically on Linux without CMake (e.g., via Makefiles, Godbolt/Compiler Explorer, or direct compiler invocations), users who include <hpx/hpx_main.hpp> hit a runtime crash because the required -Wl,-wrap=main linker flag is not discoverable outside of CMake's target property system.

Root Cause

The -Wl,-wrap=main flag is correctly set as an INTERFACE link library on both hpx_wrap and hpx_auto_wrap targets in wrap/CMakeLists.txt:126-129:

if(HPX_WITH_DYNAMIC_HPX_MAIN)
  if("${CMAKE_SYSTEM_NAME}" STREQUAL "Linux")
    target_link_libraries(hpx_wrap INTERFACE "-Wl,-wrap=main")
    target_link_libraries(hpx_auto_wrap INTERFACE "-Wl,-wrap=main")

This propagates correctly to downstream CMake consumers via the exported target chain:

HPX::auto_wrap_main → hpx_interface_auto_wrap_main → HPXInternal::hpx_auto_wrap → INTERFACE "-Wl,-wrap=main"

However, the hpx_interface_auto_wrap_main target uses a generator expression that only activates for CMake EXECUTABLE targets:

target_link_libraries(
  hpx_interface_auto_wrap_main
  INTERFACE $<$<STREQUAL:$<TARGET_PROPERTY:TYPE>,EXECUTABLE>:HPXInternal::hpx_auto_wrap>
)

This means non-CMake consumers never see the flag. They must know to pass -Wl,-wrap=main manually, but there is no prominent documentation of this requirement.

Symptoms

Users encounter this runtime error:

Attempting to use hpx_main.hpp functionality without linking to libhpx_wrap.
If you're using CMakeLists, make sure to add HPX::wrap_main to target_link_libraries.
If you're using Makefile, make sure to link to libhpx_wrap when generating the executable.

The error message mentions CMake and Makefiles but does not specify the actual linker flag (-Wl,-wrap=main) required to resolve the issue.

Who Is Affected

• Users linking HPX manually via Makefiles or shell scripts
• Browser-based compiler services (Compiler Explorer / Godbolt) that invoke g++ directly
• CI/CD pipelines that don't use CMake for the final link step
• Educational materials and tutorials that show manual compilation

Discoverability

The flag is documented in the pkgconfig file (hpx_application_release.pc), but many users do not use pkg-config. The flag is invisible in the installed CMake targets unless the user inspects the HPXInternalTargets.cmake export file.

Workaround

Users must manually add the flag to their link command:

g++ ... -lhpx_wrap -Wl,-wrap=main -lhpx_init -lhpx -lhpx_core ...

Resolution

This issue is partially addressed by:

1. PR cmake: remove HPX_WITH_CXX20_STD_EXECUTION_POLICES feature test #7068 — Adds a godbolt-minimal CMake preset that documents the required build configuration for sandboxed environments.
2. PR Feat/local convenience header #7070 — Improves the runtime error message in get_default_pool.cpp to explicitly mention -Wl,-wrap=main (Linux) and -Wl,-e,_initialize_main (macOS), giving non-CMake users an actionable fix.

Suggestions for Full Resolution

• Add a section to the HPX documentation (e.g., "Linking HPX Without CMake") that clearly lists the required linker flags per platform.
• Consider adding -Wl,-wrap=main to any future "HPX Quick Start" or "Try HPX Online" documentation.

Environment

• HPX 2.0.0 (master)
• GCC 13.3.0, C++20
• Linux (Ubuntu/Pop!_OS)
• Static linking (HPX_WITH_STATIC_LINKING=ON)

[sainathmanda7]

Hi i would like to work on this issue. I'll be tackling this alongside #7070 to ensure the convenience header and manual linking documentation are aligned.

[shivansh023023]

Hi i would like to work on this issue. I'll be tackling this alongside #7070 to ensure the convenience header and manual linking documentation are aligned.

Hi! Thank you for the interest in this issue.

Just to clarify, I have actually already submitted PR #7070 (to enhance the diagnostic error messages) and PR #7072 (the hpx/local.hpp convenience header) to address the gaps identified here.

These are currently under review by @hkaiser. I'm also working on the documentation side as part of my GSoC 2026 proposal for the Compiler Explorer integration. If there are specific edge cases you've found, I’d be happy to collaborate or incorporate them into the existing PRs!