How to Build Asio Examples Using CMake

You can build all Asio examples using a standard CMake workflow by configuring the repository root and running cmake --build ., which automatically compiles every .cpp file in src/examples/ into separate executables.

The chriskohlhoff/asio repository ships with dozens of ready-to-run example programs that demonstrate asynchronous I/O, timers, executors, and C++20 type-erasure utilities. Because all examples are ordinary C++ source files integrated into the standard CMake build system, you can compile them from source without manual Makefile editing.

Locate the Example Source Files

All example programs reside in the src/examples/ directory, organized by C++ standard (e.g., cpp14/, cpp20/). The src/examples/CMakeLists.txt script contains a helper macro that automatically discovers each .cpp file—such as src/examples/cpp14/echo/async_tcp_echo_server.cpp or src/examples/cpp20/type_erasure/main.cpp—and registers it as an executable target whose name matches the source filename.

Configure the CMake Build

Run CMake from the repository root to detect your compiler and system libraries. The configuration process automatically sets the appropriate C++ standard (C++14 or C++20) and enables platform-specific linking.

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release

During configuration, CMake links each example against the Asio library in header-only mode and pulls in required platform libraries (e.g., pthread on POSIX systems or ws2_32 on Windows).

Compile All Examples or Selective Targets

To compile every example at once, invoke the build command:

cmake --build .

To save time, build a specific example by passing its target name to the --target flag. Target names match the source filenames without extensions:

cmake --build . --target async_tcp_echo_server
cmake --build . --target type_erasure_main

For C++20-only demonstrations like the type-erasure utilities in src/examples/cpp20/type_erasure/main.cpp, ensure your compiler supports C++20—the CMake scripts automatically guard these targets and enable them only when the compiler reports C++20 support.

Run the Compiled Binaries

After successful compilation, executables are placed in the examples/ subdirectory of your build folder. Run them directly from the command line:

./examples/async_tcp_echo_server  # TCP echo server on port 12345

./examples/blocking_udp_echo_client 127.0.0.1 12345

Platform-Specific Build Notes

Different operating systems require specific system libraries that the CMake scripts link automatically:

• Linux and macOS: The build automatically adds -pthread for threading support.
• Windows: Networking examples link against Ws2_32.lib. SSL examples (see src/examples/cpp11/ssl/README) additionally require Crypt32.lib and the Windows SChannel library, which the top-level CMakeLists.txt links automatically.

Summary

• Examples are located in src/examples/ and built via the CMake workflow defined in src/examples/CMakeLists.txt.
• The build script automatically creates executable targets for each .cpp file and links them against the header-only Asio library.
• Build all examples with cmake --build . or select specific targets with --target <name> (e.g., async_tcp_echo_server).
• Compiled binaries output to build/examples/ and require C++14 minimum (C++20 for type-erasure demos).
• Platform libraries (pthread, ws2_32, Crypt32.lib) are linked automatically based on your operating system.

Frequently Asked Questions

Where are the Asio example source files located?

All example source files are stored under src/examples/ in the chriskohlhoff/asio repository. They are organized into subdirectories by C++ standard, such as cpp14/echo/ for asynchronous echo servers and cpp20/type_erasure/ for C++20-specific demonstrations.

How do I compile only one specific example instead of the entire collection?

Use the --target flag with cmake --build and specify the example filename without the extension. For instance, cmake --build . --target async_tcp_echo_server compiles only that specific example, saving time by skipping unrelated targets.

What C++ standard is required to build the Asio examples?

Most examples require at least C++14. The C++20-specific demonstrations (such as the type-erasure examples in src/examples/cpp20/type_erasure/main.cpp) are guarded by CMake checks and only enabled when your compiler reports C++20 support.

Why do I get linker errors for socket functions when building on Windows?

The Asio library requires Windows socket libraries that the CMake scripts should automatically link. According to the src/examples/CMakeLists.txt configuration, the build automatically links Ws2_32.lib for networking and Crypt32.lib for SSL examples (along with SChannel). If you encounter linker errors, verify that your CMake generator is correctly detecting the Windows SDK and linking these system libraries.

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