How to Include Asio in a C++ Project: Header-Only Setup Guide

You can include Asio in your C++ project by adding the repository's include/ directory to your compiler's search path and including <asio.hpp> in your source files, as the library is entirely header-only.

The Asio library from the chriskohlhoff/asio repository provides cross-platform, low-level I/O services including sockets, timers, and asynchronous operations for modern C++ applications. Because it is header-only, you do not need to compile separate libraries or link binaries—just configure your include paths correctly. This guide shows you exactly how to include Asio in a C++ project using standard build tools and compiler flags.

Obtaining the Asio Source Code

First, download the source code to your local machine. You can clone the repository directly or download a release archive from the GitHub releases page.

git clone https://github.com/chriskohlhoff/asio.git

The critical directory is include/ at the root of the repository, which contains all the header files you need. The primary umbrella header is located at include/asio.hpp, though you can also include more granular headers like include/asio/ip/tcp.hpp or include/asio/steady_timer.hpp to reduce compilation times.

Configuring the Include Path

Since Asio is header-only, you must tell your compiler where to find the headers. This typically involves adding the path to the include/ directory as an additional include directory.

GCC and Clang

When compiling with GCC or Clang, use the -I flag to specify the path to the Asio include/ directory.

g++ -std=c++11 -I/path/to/asio/include main.cpp -o my_app

Replace /path/to/asio with the actual location where you cloned or extracted the repository.

Visual Studio

In Visual Studio, right-click your project and navigate to Configuration Properties → C/C++ → General. Add the path to the Asio include/ directory to Additional Include Directories. You can then compile with the default MSVC toolchain without additional linker flags for the core library.

Including the Headers in Your Source Files

Once the include path is configured, add the headers to your C++ source files. The simplest approach is to include the umbrella header asio.hpp, which pulls in the entire API.

#include <asio.hpp>

For better compile times, include only the specific components you need. For example, use include/asio/ip/tcp.hpp for TCP networking, include/asio/steady_timer.hpp for timers, or include/asio/co_spawn.hpp for C++20 coroutine support.

Linking Requirements

Asio's core functionality requires no linking against a compiled library. However, certain optional features require third-party libraries:

• SSL Support: If you use include/asio/ssl.hpp, you must link against OpenSSL using -lssl and -lcrypto (GCC/Clang) or by adding the appropriate libraries in Visual Studio.
• Boost Integration: If you use the Boost.Asio compatibility mode or Boost-specific executor types, link against the corresponding Boost libraries.

Complete Working Examples

Here are practical examples demonstrating how to use Asio after including it in your project.

Synchronous TCP Client

This example uses include/asio.hpp and include/asio/ip/tcp.hpp to resolve a hostname and send an HTTP request.

#include <asio.hpp>
#include <iostream>

int main() {
    try {
        asio::io_context ctx;
        asio::ip::tcp::resolver resolver(ctx);
        auto endpoints = resolver.resolve("example.com", "80");

        asio::ip::tcp::socket socket(ctx);
        asio::connect(socket, endpoints);

        const std::string request =
            "GET / HTTP/1.1\r\nHost: example.com\r\n\r\n";
        asio::write(socket, asio::buffer(request));

        for (char buf[512];;) {
            std::size_t n = socket.read_some(asio::buffer(buf));
            std::cout.write(buf, n);
        }
    } catch (std::exception& e) {
        std::cerr << "Error: " << e.what() << "\n";
    }
}

Asynchronous Timer with Coroutines

This example uses include/asio.hpp, include/asio/co_spawn.hpp, and include/asio/awaitable.hpp for C++20 coroutines.

#include <asio.hpp>
#include <iostream>

asio::awaitable<void> timer_task() {
    asio::steady_timer t(co_await asio::this_coro::executor);
    t.expires_after(std::chrono::seconds(2));
    co_await t.async_wait(asio::use_awaitable);
    std::cout << "Timer fired after 2 seconds\n";
}

int main() {
    asio::io_context ctx;
    asio::co_spawn(ctx, timer_task(), asio::detached);
    ctx.run();
}

SSL Client Setup

This example requires include/asio/ssl.hpp and linking against OpenSSL.

#include <asio.hpp>
#include <asio/ssl.hpp>
#include <iostream>

int main() {
    asio::io_context ctx;
    asio::ssl::context ssl_ctx(asio::ssl::context::tlsv12_client);
    ssl_ctx.set_default_verify_paths();

    asio::ssl::stream<asio::ip::tcp::socket> stream(ctx, ssl_ctx);
    asio::ip::tcp::resolver resolver(ctx);
    auto endpoints = resolver.resolve("www.google.com", "https");
    asio::connect(stream.lowest_layer(), endpoints);
    stream.handshake(asio::ssl::stream_base::client);

    std::cout << "SSL handshake completed\n";
}

Summary

• Asio is header-only: Add the include/ directory from chriskohlhoff/asio to your compiler's search path.
• Primary header: Use include/asio.hpp for the full API, or granular headers like include/asio/ip/tcp.hpp for specific components.
• No core linking required: The library does not require linking against a binary, though OpenSSL is required for include/asio/ssl.hpp.
• Standards support: Requires C++11 or later, with enhanced features available in C++17 and C++20.

Frequently Asked Questions

Is Asio header-only?

Yes, Asio is entirely header-only. You do not need to compile the source files or link against a .lib or .a file for core functionality. Simply add the include/ directory to your compiler's include path and start using the headers.

Do I need to link a library to use Asio?

Core Asio functionality requires no linking. However, if you use SSL features via include/asio/ssl.hpp, you must link against OpenSSL. Additionally, if you use Boost.Asio integration or Boost-specific components, you must link against the relevant Boost libraries.

What is the difference between standalone Asio and Boost.Asio?

Standalone Asio resides in the chriskohlhoff/asio repository and places all classes in the asio:: namespace. Boost.Asio is the same codebase distributed with Boost, using the boost::asio:: namespace. Both share identical header layouts and APIs, so the inclusion method is the same—only the namespace and distribution mechanism differ.

Which C++ standard version does Asio require?

Asio requires C++11 or later. Many modern features, such as the awaitable coroutine support in include/asio/awaitable.hpp, require C++20. The library works with any conforming compiler including GCC, Clang, and MSVC.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}