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

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:

#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>.

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

Compile with the preprocessor definition:

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

# 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

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

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 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.

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