# Asio Build Requirements: Complete Guide for Linux, Windows, and macOS

> Discover Asio build requirements for Linux, Windows, and macOS. Learn about modern C++ compiler needs, optional Boost and OpenSSL dependencies, and single macro compilation.

- Repository: [chriskohlhoff/asio](https://github.com/chriskohlhoff/asio)
- Tags: getting-started
- Published: 2026-07-16

---

**Asio requires only a modern C++ compiler for header-only use, with optional dependencies on Boost libraries and OpenSSL for specific features, and supports separate compilation mode via a single macro definition.**

The chriskohlhoff/asio repository provides a cross-platform C++ library for network and low-level I/O programming. Understanding the Asio build requirements is essential because the library is header-only by default, yet offers optional compiled modes and platform-specific toolchains for different use cases.

## Supported Platforms and Compilers

According to `src/doc/using.qbk`, Asio is regularly tested on specific platform and compiler combinations while maintaining compatibility with many others.

### Regularly Tested Platforms

The following configurations undergo continuous testing:

- **Linux** – GCC 4.6+ or Clang 3.4+
- **FreeBSD** – GCC 9+
- **macOS** – Xcode 10+
- **Windows** – Visual C++ 11.0 (Visual Studio 2012) or later for both 32-bit and 64-bit builds

### Additional Compatible Platforms

Asio also supports these platforms, though they may not be tested as frequently:

- AIX, Android, HP-UX, iOS, NetBSD, OpenBSD, QNX Neutrino, Solaris, Tru64
- MinGW and Cygwin (requires `__USE_W32_SOCKETS`)

## Mandatory and Optional Dependencies

### Core Library Requirements

Asio is **header-only** by default and carries **no mandatory runtime dependencies**. Simply include the headers and compile with a standard C++ compiler.

### Optional Libraries for Extended Features

Specific functionality requires additional libraries:

- **Boost.Coroutine** – Required for `asio::spawn()`
- **Boost.Regex** – Required for the `boost::regex` overloads of `read_until()` and `async_read_until()`
- **OpenSSL** – Required for SSL/TLS support
- **Boost.Date_Time** and **Boost.Serialization** – Required only for certain example programs

## Header-Only vs. Separate Compilation

### Header-Only Usage

For most applications, no build steps are required:

```cpp
#include <asio.hpp>

int main() {
    asio::io_context ctx;
    // Use Asio objects directly
}

```

### Separate Compilation Mode

To reduce compilation times in large projects, enable separate compilation by adding `#include <asio/impl/src.hpp>` to exactly one source file and defining `ASIO_SEPARATE_COMPILATION`. For shared library builds, also define `ASIO_DYN_LINK`. For SSL support, additionally include `<asio/ssl/impl/src.hpp>`.

```cpp
// In exactly one .cpp file
#include <asio/impl/src.hpp>
#include <asio.hpp>

```

Compile with the preprocessor definition:

```bash
g++ -DASIO_SEPARATE_COMPILATION main.cpp -o my_app

```

## Building Asio on Linux and Unix

The repository includes Autotools support via `configure.ac` and `src/Makefile.am`. Follow these steps to build the library and examples:

1. Place the Boost directory next to the Asio source tree, or specify its location with `./configure --with-boost=/path/to/boost`
2. Run `./configure` in the Asio root directory
3. Build examples and tests with `make`
4. Run the test suite with `make check`

```bash

# Configure (assumes Boost is in sibling directory)

./configure

# Build the compiled source (creates libasio.a)

make -C src

# Build examples and run tests

make
make check

```

## Building Asio on Windows

### Using Visual Studio (MSVC)

For Microsoft Visual C++ builds using `src/Makefile.msc`:

1. Set the `BOOSTDIR` environment variable to your Boost installation path
2. Navigate to the `src` directory
3. Run `nmake -f Makefile.msc` to compile the library
4. Run `nmake -f Makefile.msc check` to execute the test suite

```bat
set BOOSTDIR=C:\path\to\boost
cd src
nmake -f Makefile.msc
nmake -f Makefile.msc check

```

### Using MinGW

For MinGW builds using `src/Makefile.mgw`, use forward slashes in paths:

1. Set `BOOSTDIR` using forward slashes (e.g., `c:/projects/boost_1_84_0`)
2. Navigate to `src`
3. Run `make -f Makefile.mgw`
4. Run `make -f Makefile.mgw check` to test

```bat
set BOOSTDIR=c:/path/to/boost
cd src
make -f Makefile.mgw
make -f Makefile.mgw check

```

## Summary

- Asio is header-only by default with no mandatory runtime dependencies according to `src/doc/using.qbk`
- Supported platforms include Linux (GCC 4.6+/Clang 3.4+), FreeBSD (GCC 9+), macOS (Xcode 10+), and Windows (VS 2012+)
- Optional features require Boost.Coroutine, Boost.Regex, or OpenSSL
- Separate compilation mode requires including [`asio/impl/src.hpp`](https://github.com/chriskohlhoff/asio/blob/main/asio/impl/src.hpp) in one translation unit and defining `ASIO_SEPARATE_COMPILATION`
- Build systems provided include Autotools for Unix, NMake for MSVC via `src/Makefile.msc`, and Make for MinGW via `src/Makefile.mgw`

## Frequently Asked Questions

### Does Asio require Boost?

No, Asio does not require Boost for its core functionality. However, specific features like `asio::spawn()` require Boost.Coroutine, and regex-based operations require Boost.Regex. The optional compiled library mode can also utilize Boost for configuration.

### How do I enable SSL support in Asio?

SSL support requires linking against OpenSSL. When using separate compilation mode, include `<asio/ssl/impl/src.hpp>` in the same source file that includes `<asio/impl/src.hpp>`, and ensure your build system links against the OpenSSL libraries.

### What is the difference between header-only and separate compilation?

Header-only mode includes all implementation code in every translation unit that includes Asio headers, resulting in longer compile times but simpler build configuration. Separate compilation mode moves implementation details into a single compiled object file or library, reducing overall build time for larger projects.

### Which Visual Studio versions are compatible with Asio?

Asio requires Visual C++ 11.0 or later, which corresponds to Visual Studio 2012 and all subsequent versions. This is documented in `src/doc/using.qbk` as the minimum supported version for Windows builds.