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

> Learn to configure Asio build options using Autotools flags like --enable-static and --with-openssl. Optimize your Asio compilation for specific needs.

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

---

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

```bash
./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`](https://github.com/chriskohlhoff/asio/blob/main/openssl/ssl.h) and automatically links `-lssl -lcrypto`.

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

```bash
./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.

```bash
./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/`.

```bash
./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`](https://github.com/chriskohlhoff/asio/blob/main/boost/version.hpp) in `configure.ac`.

```bash
./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.

```bash
./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.

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

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