How to Configure Asio Build Options: Autotools, CMake, and Compilation Flags

You configure Asio build options through the ./configure script using flags like --enable-static, --with-openssl, and --disable-epoll, which modify the Autotools configuration in configure.ac and src/Makefile.am while generating compile-time macros in include/asio/detail/config.hpp.

While Asio is primarily a header-only C++ networking library, building it as a compiled library—either standalone or as part of the Boost distribution—requires understanding how to configure Asio build options across different build systems. The chriskohlhoff/asio repository provides Autotools-based configuration through configure.ac and Makefile.am, allowing you to customize library types, SSL support, platform-specific I/O back-ends, and compiler optimizations.

Understanding Asio's Configuration Architecture

The configuration system spans three critical files that process your build options. The configure.ac file at the repository root defines all --enable, --with, and --disable flags using AC_ARG_ENABLE and AC_ARG_WITH macros, setting AM_CONDITIONAL variables that flow into the build system. The src/Makefile.am consumes these conditionals to determine which subdirectories—such as examples and tests—are included in the compilation. Finally, include/asio/detail/config.hpp translates these settings into compile-time macros like ASIO_HAS_EPOLL, which conditionally includes platform-specific code paths throughout the library.

Essential Configure Flags for Asio

Library Type Selection (--enable-static, --enable-shared)

Control whether Asio builds as static (.a) or shared (.so/.dll) libraries using the --enable-static and --enable-shared flags. These options modify the LIBADD variable in Makefile.am, adding -static or -shared linker directives as appropriate.

./configure --enable-static --enable-shared

SSL/TLS Support (--with-openssl)

Enable OpenSSL integration for the SSL/TLS components located in include/asio/ssl/ by specifying the OpenSSL installation path. This flag checks for openssl/ssl.h and automatically links -lssl -lcrypto.

./configure --with-openssl=/usr/local/ssl

Platform-Specific I/O Back-ends (--disable-epoll, --disable-kqueue, --disable-iocp)

Remove unnecessary platform-specific I/O multiplexing implementations to reduce binary size. The --disable-epoll, --disable-kqueue, and --disable-iocp flags prevent their corresponding source files from being compiled, with the resulting macros defined in include/asio/detail/config.hpp.

./configure --disable-epoll --disable-kqueue --disable-iocp

Build Optimization Flags (--enable-static-pic, --enable-werror)

For embedding Asio into shared objects, use --enable-static-pic to add -fPIC to CXXFLAGS, creating position-independent static libraries. The --enable-werror flag adds -Werror to treat all compiler warnings as errors, essential for CI pipelines.

./configure --enable-static-pic --enable-werror

Optional Components and Dependencies

Controlling Examples and Tests (--disable-examples, --disable-tests)

Exclude demonstration programs and the test suite from the build to reduce compilation time. The --disable-examples flag removes src/examples/ from SUBDIRS in Makefile.am, while --disable-tests excludes src/tests/.

./configure --disable-examples --disable-tests

Boost Integration (--with-boost)

When building Asio as a Boost component, specify the Boost installation path to link against Boost.System and Boost.Thread libraries. This flag triggers a check for boost/version.hpp in configure.ac.

./configure --with-boost=/path/to/boost

Threading Support (--with-pthread)

Force explicit linking with -lpthread on platforms where autodetection fails using the --with-pthread flag, which adds pthread directly to the LIBS variable.

./configure --with-pthread

Environment Variables and Compiler Flags

Beyond configure flags, you can tune the build by exporting standard environment variables before running ./configure. The CXXFLAGS, CPPFLAGS, and LDFLAGS variables propagate directly into the generated Makefiles, allowing optimization levels and macro definitions without modifying source files.

export CXXFLAGS="-O3 -march=native -DNDEBUG"
./configure --enable-static

Step-by-Step Build Configuration Workflow

Follow this typical workflow to configure and build Asio from the chriskohlhoff/asio source:

1. Extract the source and navigate to the root directory
2. Run the configure script with your desired options
3. Compile with parallel jobs
4. Install to system directories (optional)

tar xf asio-1.38.1.tar.gz
cd asio-1.38.1

./configure \
    --enable-static \
    --enable-shared \
    --with-openssl=/usr/local/ssl \
    --disable-examples \
    CXXFLAGS="-O2 -march=native"

make -j$(nproc)
sudo make install

Summary

• The ./configure script in chriskohlhoff/asio processes build options through configure.ac, src/Makefile.am, and include/asio/detail/config.hpp
• Use --enable-static and --enable-shared to control library output formats
• Enable SSL with --with-openssl and disable unused I/O back-ends with --disable-epoll or similar flags
• Control optional components using --disable-examples and --disable-tests
• Set compiler optimizations via CXXFLAGS environment variables before running configure

Frequently Asked Questions

Does Asio require compilation since it is header-only?

While Asio is primarily header-only, compilation becomes necessary when building it as a standalone library package or when integrating with Boost. The configure script manages these compiled builds by linking against system libraries like OpenSSL and pthreads.

How do I disable specific I/O back-ends to reduce binary size?

Use the --disable-epoll, --disable-kqueue, or --disable-iocp flags to exclude Linux epoll, BSD kqueue, or Windows IOCP implementations respectively. These flags remove the corresponding source files from the build and prevent the associated macros from being defined in include/asio/detail/config.hpp.

Where are the configuration macros stored after running configure?

The configure.ac script generates compile-time macros in include/asio/detail/config.hpp based on feature detection and user-specified flags. This header is included throughout the Asio codebase to enable or disable platform-specific functionality like ASIO_HAS_EPOLL.

Can I use CMake instead of Autotools to configure Asio?

Yes, when building Asio as part of the Boost distribution, CMake is available as an alternative to Autotools. However, the standalone chriskohlhoff/asio repository primarily uses the Autotools-based ./configure script described in this guide.

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