# How to Build Asio Examples Using CMake

> Easily build Asio examples using CMake. Follow this guide to configure the repository root and run make to compile all example cpp files into separate executables.

- Repository: [chriskohlhoff/asio](https://github.com/chriskohlhoff/asio)
- Tags: how-to-guide
- Published: 2026-07-16

---

**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`](https://github.com/chriskohlhoff/asio/blob/main/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`](https://github.com/chriskohlhoff/asio/blob/main/src/examples/cpp14/echo/async_tcp_echo_server.cpp) or [`src/examples/cpp20/type_erasure/main.cpp`](https://github.com/chriskohlhoff/asio/blob/main/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.

```bash
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:

```bash
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:

```bash
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`](https://github.com/chriskohlhoff/asio/blob/main/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:

```bash
./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`](https://github.com/chriskohlhoff/asio/blob/main/CMakeLists.txt) links automatically.

## Summary

- Examples are located in `src/examples/` and built via the **CMake** workflow defined in [`src/examples/CMakeLists.txt`](https://github.com/chriskohlhoff/asio/blob/main/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`](https://github.com/chriskohlhoff/asio/blob/main/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`](https://github.com/chriskohlhoff/asio/blob/main/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.