Skip to content

# ASIO Setup for Glaze Networking

Glaze's networking features (HTTP server/client, WebSocket client, REPE RPC) require ASIO for async I/O. This guide covers how to configure ASIO for use with Glaze.

## Which Features Require ASIO?

Feature | Header | ASIO Required
--- | --- | ---
JSON/BEVE serialization | `glaze/glaze.hpp` | No
CSV/TOML parsing | `glaze/csv.hpp`, `glaze/toml.hpp` | No
HTTP Server | `glaze/net/http_server.hpp` | Yes
HTTP Client | `glaze/net/http_client.hpp` | Yes
WebSocket Client | `glaze/net/websocket_client.hpp` | Yes
REPE RPC (asio_server/client) | `glaze/ext/glaze_asio.hpp` | Yes

The core Glaze serialization library has no external dependencies. ASIO is only required for networking features.

## ASIO Detection

Glaze automatically detects which ASIO implementation is available using `__has_include`:

1. Standalone ASIO (`<asio.hpp>`) - Preferred, used by default
2. Boost.Asio (`<boost/asio.hpp>`) - Used as fallback if standalone not found

No configuration is needed if ASIO headers are in your include path - Glaze will find them automatically.

## Installation Methods

### Option 1: Standalone ASIO (Recommended)

Standalone ASIO is a header-only library with no dependencies (except OpenSSL for TLS).

#### Via Package Manager

    # macOS (Homebrew)
    brew install asio

    # Ubuntu/Debian
    sudo apt-get install libasio-dev

    # Arch Linux
    sudo pacman -S asio

    # vcpkg
    vcpkg install asio

    # Conan
    conan install asio/1.28.0@

#### Via CMake FetchContent

    include(FetchContent)

    FetchContent_Declare(
      asio
      GIT_REPOSITORY https://github.com/chriskohlhoff/asio.git
      GIT_TAG asio-1-36-0
      GIT_SHALLOW TRUE
    )
    FetchContent_MakeAvailable(asio)

    # Add include path
    target_include_directories(your_target PRIVATE ${asio_SOURCE_DIR}/asio/include)

#### Manual Download

Download from think-async.com and add the `include` directory to your compiler's include path.

### Option 2: Boost.Asio

If you're already using Boost in your project, you can use Boost.Asio instead.

#### Via Package Manager

    # macOS (Homebrew)
    brew install boost

    # Ubuntu/Debian
    sudo apt-get install libboost-system-dev

    # Arch Linux
    sudo pacman -S boost

    # vcpkg
    vcpkg install boost-asio

    # Conan
    conan install boost/1.83.0@

#### CMake Integration

    find_package(Boost REQUIRED COMPONENTS system)
    target_link_libraries(your_target PRIVATE Boost::system)

## CMake Configuration

### Complete Example with ASIO

    cmake_minimum_required(VERSION 3.20)
    project(MyNetworkingApp LANGUAGES CXX)

    set(CMAKE_CXX_STANDARD 23)
    set(CMAKE_CXX_STANDARD_REQUIRED ON)

    include(FetchContent)

    # Fetch Glaze
    FetchContent_Declare(
      glaze
      GIT_REPOSITORY https://github.com/stephenberry/glaze.git
      GIT_TAG main
      GIT_SHALLOW TRUE
    )
    FetchContent_MakeAvailable(glaze)

    # Fetch standalone ASIO
    FetchContent_Declare(
      asio
      GIT_REPOSITORY https://github.com/chriskohlhoff/asio.git
      GIT_TAG asio-1-36-0
      GIT_SHALLOW TRUE
    )
    FetchContent_MakeAvailable(asio)

    add_executable(myapp main.cpp)
    target_link_libraries(myapp PRIVATE glaze::glaze)
    target_include_directories(myapp PRIVATE ${asio_SOURCE_DIR}/asio/include)

    # MSVC specific
    if(MSVC)
        target_compile_options(myapp PRIVATE /Zc:preprocessor)
    endif()

### Using System ASIO

    # Try to find system ASIO
    find_package(asio CONFIG QUIET)

    if(asio_FOUND)
        target_link_libraries(myapp PRIVATE asio::asio)
    else()
        # Fallback: try pkg-config or manual path
        find_path(ASIO_INCLUDE_DIR asio.hpp)
        if(ASIO_INCLUDE_DIR)
            target_include_directories(myapp PRIVATE ${ASIO_INCLUDE_DIR})
        else()
            message(FATAL_ERROR "ASIO not found. Install it or use FetchContent.")
        endif()
    endif()

### Using Boost.Asio

    find_package(Boost REQUIRED COMPONENTS system)
    target_link_libraries(myapp PRIVATE glaze::glaze Boost::system)

## Configuration Options

### Force Boost.Asio

If both standalone ASIO and Boost.Asio are available, Glaze prefers standalone ASIO. To force Boost.Asio:

    #define GLZ_USE_BOOST_ASIO
    #include "glaze/net/http_server.hpp"

Or via CMake:

    target_compile_definitions(myapp PRIVATE GLZ_USE_BOOST_ASIO)

### Detecting Which ASIO is Used

After including Glaze networking headers, you can check which implementation is active:

    #include "glaze/ext/glaze_asio.hpp"

    #ifdef GLZ_USING_BOOST_ASIO
        // Using Boost.Asio
    #else
        // Using standalone ASIO
    #endif

## SSL/TLS Support

For HTTPS and secure WebSocket connections (wss://), you need OpenSSL.

### Installing OpenSSL

    # macOS (Homebrew)
    brew install openssl

    # Ubuntu/Debian
    sudo apt-get install libssl-dev

    # Arch Linux
    sudo pacman -S openssl

    # vcpkg
    vcpkg install openssl

### CMake with OpenSSL

    find_package(OpenSSL REQUIRED)
    target_link_libraries(myapp PRIVATE OpenSSL::SSL OpenSSL::Crypto)

    # Enable SSL in Glaze
    target_compile_definitions(myapp PRIVATE GLZ_ENABLE_SSL)

### macOS OpenSSL Path

On macOS with Homebrew, you may need to specify the OpenSSL path:

    if(APPLE)
        execute_process(
            COMMAND brew --prefix openssl
            OUTPUT_VARIABLE OPENSSL_ROOT_DIR
            OUTPUT_STRIP_TRAILING_WHITESPACE
        )
        set(OPENSSL_ROOT_DIR ${OPENSSL_ROOT_DIR})
    endif()

    find_package(OpenSSL REQUIRED)

## Platform-Specific Notes

### Windows

On Windows, ASIO requires linking against `ws2_32` (Winsock):

    if(WIN32)
        target_link_libraries(myapp PRIVATE ws2_32)
    endif()

With MSVC, you also need the conformant preprocessor:

    if(MSVC)
        target_compile_options(myapp PRIVATE /Zc:preprocessor)
    endif()

### macOS

No special configuration needed beyond OpenSSL path for TLS support.

### Linux

No special configuration needed. Ensure `pthread` is linked if using threads:

    find_package(Threads REQUIRED)
    target_link_libraries(myapp PRIVATE Threads::Threads)

## Troubleshooting

### "asio.hpp not found"

ASIO headers are not in your include path. Either: - Install ASIO via your package manager - Add the ASIO include directory to your build - Use FetchContent to download ASIO

### "standalone or boost asio must be included"

This static assertion fires when neither ASIO implementation is found. Ensure ASIO is properly installed and the include path is set.

### Linker errors with Boost.Asio

Boost.Asio requires linking against `Boost::system`:

    find_package(Boost REQUIRED COMPONENTS system)
    target_link_libraries(myapp PRIVATE Boost::system)

### SSL handshake failures

Ensure OpenSSL is properly installed and linked. On macOS, verify you're using Homebrew's OpenSSL, not the system LibreSSL.

### "undefined reference to pthread" on Linux

Add threading support:

    find_package(Threads REQUIRED)
    target_link_libraries(myapp PRIVATE Threads::Threads)

## Complete Working Example

    // main.cpp
    #include "glaze/net/http_server.hpp"
    #include <iostream>

    int main() {
        glz::http_server server;

        server.get("/hello", [](const glz::request&, glz::response& res) {
            res.json({{"message", "Hello from Glaze!"}});
        });

        server.bind("127.0.0.1", 8080).with_signals();

        std::cout << "Server running on http://127.0.0.1:8080\n";

        server.start();
        server.wait_for_signal();

        return 0;
    }

    # CMakeLists.txt
    cmake_minimum_required(VERSION 3.20)
    project(hello_server LANGUAGES CXX)

    set(CMAKE_CXX_STANDARD 23)
    set(CMAKE_CXX_STANDARD_REQUIRED ON)

    include(FetchContent)

    FetchContent_Declare(
      glaze
      GIT_REPOSITORY https://github.com/stephenberry/glaze.git
      GIT_TAG main
      GIT_SHALLOW TRUE
    )

    FetchContent_Declare(
      asio
      GIT_REPOSITORY https://github.com/chriskohlhoff/asio.git
      GIT_TAG asio-1-36-0
      GIT_SHALLOW TRUE
    )

    FetchContent_MakeAvailable(glaze asio)

    add_executable(hello_server main.cpp)
    target_link_libraries(hello_server PRIVATE glaze::glaze)
    target_include_directories(hello_server PRIVATE ${asio_SOURCE_DIR}/asio/include)

    if(WIN32)
        target_link_libraries(hello_server PRIVATE ws2_32)
    endif()

    if(MSVC)
        target_compile_options(hello_server PRIVATE /Zc:preprocessor)
    endif()

## Next Steps

- HTTP Server Guide - Server configuration and routing
- WebSocket Client Guide - Real-time communication
- REPE RPC Guide - High-performance RPC