claude-skills/engineering/boost-asio-pro/references/build.md

Build Configuration

Boost.Asio (header-only since Boost 1.74+)

find_package(Boost REQUIRED)
find_package(OpenSSL REQUIRED)          # if using SSL
find_package(Threads REQUIRED)

target_link_libraries(myapp PRIVATE
    Boost::headers                       # header-only Asio
    OpenSSL::SSL OpenSSL::Crypto         # if using SSL
    Threads::Threads
)

target_compile_features(myapp PRIVATE cxx_std_20)

# REQUIRED for GCC coroutine support — build will fail without this
target_compile_options(myapp PRIVATE
    $<$<CXX_COMPILER_ID:GNU>:-fcoroutines>
)

# Optional: truly header-only (no Boost.System link needed)
target_compile_definitions(myapp PRIVATE BOOST_ERROR_CODE_HEADER_ONLY)

Standalone Asio (always header-only)

# Standalone Asio has no CMake config — use pkg-config or manual path
find_package(OpenSSL REQUIRED)
find_package(Threads REQUIRED)

# If installed via brew:
find_path(ASIO_INCLUDE_DIR asio.hpp HINTS /opt/homebrew/include)

target_include_directories(myapp PRIVATE ${ASIO_INCLUDE_DIR})
target_link_libraries(myapp PRIVATE OpenSSL::SSL OpenSSL::Crypto Threads::Threads)
target_compile_features(myapp PRIVATE cxx_std_20)
target_compile_definitions(myapp PRIVATE ASIO_STANDALONE)

target_compile_options(myapp PRIVATE
    $<$<CXX_COMPILER_ID:GNU>:-fcoroutines>
)

Dual-mode CMake (supports both)

option(USE_STANDALONE_ASIO "Use standalone Asio instead of Boost.Asio" OFF)

find_package(OpenSSL REQUIRED)
find_package(Threads REQUIRED)

if(USE_STANDALONE_ASIO)
    find_path(ASIO_INCLUDE_DIR asio.hpp HINTS /opt/homebrew/include)
    target_include_directories(myapp PRIVATE ${ASIO_INCLUDE_DIR})
    target_compile_definitions(myapp PRIVATE USE_STANDALONE_ASIO ASIO_STANDALONE)
else()
    find_package(Boost REQUIRED)
    target_link_libraries(myapp PRIVATE Boost::headers)
    target_compile_definitions(myapp PRIVATE BOOST_ERROR_CODE_HEADER_ONLY)
endif()

target_link_libraries(myapp PRIVATE OpenSSL::SSL OpenSSL::Crypto Threads::Threads)
target_compile_features(myapp PRIVATE cxx_std_20)
target_compile_options(myapp PRIVATE $<$<CXX_COMPILER_ID:GNU>:-fcoroutines>)

Header-Only Usage

Boost.Asio: Asio is header-only by default. The only thing that pulls in a Boost library to link is boost::system::error_code's out-of-line symbols, so for a truly link-free build define BOOST_ERROR_CODE_HEADER_ONLY. BOOST_ASIO_HEADER_ONLY is rarely needed and only relevant if separate compilation was previously enabled; you do not normally need both.

Define BOOST_ERROR_CODE_HEADER_ONLY in exactly ONE place — prefer CMake (target_compile_definitions, as shown above). Defining it in CMake and with a source #define triggers -Wmacro-redefined. So in source, just include — no #define:

#include <boost/asio.hpp>
#include <boost/asio/ssl.hpp>
#include <boost/asio/experimental/awaitable_operators.hpp>

Standalone Asio:

#include <asio.hpp>
#include <asio/ssl.hpp>
#include <asio/experimental/awaitable_operators.hpp>
// No macros needed — always header-only