README

January 10, 2026 · View on GitHub

Welcome to Apache Serf, a high-performance asynchronous HTTP client library.

The Apache Serf library is a C-based HTTP client library built upon the Apache Portable Runtime (APR) library. It multiplexes connections, running the read/write communication asynchronously. Memory copies and transformations are kept to a minimum to provide high performance operation.

Site: https://serf.apache.org/
Code: https://svn.apache.org/repos/asf/serf/
Official Git Mirror: https://github.com/apache/serf/
Issues: https://issues.apache.org/jira/browse/SERF
Mail: dev@serf.apache.org

INSTALL

1.1 Build systems

Apache Serf can use either SCons or CMake. Both build systems should offer the same features.

A note on the required dependencies:

APR and APR-Util must be at least version 1.3.0.
Use a modern OpenSSL 3.x. Serf will work with OpenSSL 1.1.1 and maybe even 0.9.x, but those versions have known security bugs. LibreSSL seems to work, but we don't test it.
Use the latest ZLib to avoid buffer overrun bugs.

1.1.1 SCons build system

You must use at least SCons version 2.3.5. If it is not installed on your system, then you can install it onto your system. If you do not have permissions, then you can download and install the "local" version into your home directory. When installed privately, simply create a symlink for 'scons' in your PATH to /path/to/scons/scons.py.

Fetch the scons-local package: http://prdownloads.sourceforge.net/scons/scons-local-2.3.5.tar.gz

Alternatively create a virtual Python environment and install SCons via pip (replace the path ~/scons_venv with your preferred path):

$python -m venv ~/scons_venv$ ~/scons_venv/bin/pip install scons

In the build instructions below, make sure to include the full path to your virtual environment:

$ ~/scons_venv/bin/scons [...see below...]

1.1.2 Building Apache Serf using SCons

To build serf:

$ scons PREFIX=/path/to/prefix
APR=/path/to/apr APU=/path/to/apr-util
OPENSSL=/path/to/openssl ZLIB=/path/to/zlib
BROTLI=/path/to/brotli GSSAPI=/path/to/kerberos

The switches are recorded into .saved_config, so they only need to be specified the first time scons is run.

PREFIX should specify where serf should be installed. PREFIX defaults to /usr/local.

The default for the mandatory dependencies (APR, APU, OPENSSL, ZLIB) is /usr.

The build system looks for apr-1-config at $APR/bin/apr-1-config, or the path should indicate apr-1-config itself. Similarly for the path to apu-1-config in$ APU or $APU/bin/apu-1-config.

OPENSSL should specify the root of the install (e.g., /opt/local). The includes will be found $OPENSSL/include/openssl and libraries at$ OPENSSL/lib.

ZLIB should specify the root of the install. The includes will be found $ZLIB/include and libraries at$ ZLIB/lib.

The BROTLI and GSSAPI dependencies are optional.

BROTLI should be the path to the installation of the Brotli compression library; for example, BROTLI=/usr/local. The includes will be found in $BROTLI/include/brotli and the libraries in$ BROTLI/lib.

GSSAPI should be the path to the installation of a package that provides the GSSAPI implementation such as Kerberos5 or Heimdal. SCons will look for the configuration program $GSSAPI/bin/krb5-config.

NOTE: Do not use the GSSAPI switch on Windows; it provides the SSPI API which Serf uses by default on that platform.

If you wish to use VPATH-style builds (where objects are created in a distinct directory from the source), you can use:

$ scons -Y /path/to/serf/source

If you plan to install the library on a system that uses different paths for architecture dependent files, specify LIBDIR. LIBDIR defaults to /usr/local/lib otherwise. Example for a 64 bit GNU/Linux system:

$ scons PREFIX=/usr/ LIBDIR=/usr/lib64

At any point, the current settings can be examined:

$ scons --help

1.1.3 Running the test suite

$ scons check

Some tests take a long time to run, for example a 4GB request. These can be enabled by passing ENABLE_SLOW_TESTS on the command line:

$ scons check ENABLE_SLOW_TESTS=1

1.1.4 Installing Apache Serf

$ scons install

Note that the PREFIX variable should have been specified in a previous invocation of scons (and saved into .saved_config), or it can be specified on the install command line:

$ scons PREFIX=/some/path install

Distribution package maintainers regularly install to a buildroot, and would normally use something like below in their build systems, with placeholders for the specific paths:

$scons PREFIX=/usr/ LIBDIR=/usr/lib64$ scons install --install-sandbox=/path/to/buildroot

1.1.5 Cleaning up the build

$ scons -c

1.2.1 CMake build system

Get the sources, either a release tarball or by checking out the official repository. The CMake build system currently only exists in trunk and it will be included in the 1.5 release.

The process for building on Unix and Windows is the same.

$ cmake -B out [build options]
$ cmake --build out

or, with a multi-config generator:

$ cmake --build out --config Release

"out" in the commands above is the build directory used by CMake.

Build options can be added, for example:

$ cmake -B out -DCMAKE_INSTALL_PREFIX=/usr/local/serf -DSKIP_TESTS=ON

Build options can be listed using:

$ cmake -LH

By default, CMake will look for dependencies in ${CMAKE_SEARCH_PREFIX}, which you can override on the command line, e.g.::

$ cmake -DCMAKE_SEARCH_PREFIX=/opt

The search for each the five dependencies can be modified by setting their *_ROOT CMake variables:

$ cmake -DAPR_ROOR=/path/to/apr \
        -DAPRUtil_ROOT=/path/to/apr-util \
        -DOPENSSL_ROOT_DIR=/path/to/openssl \
        -DZLIB_ROOT=/path/to/zlib \
        -DBrotli_ROOT=/path/to/brotli \
        -DGSSAPI_ROOT=/path/to/kerberos5

1.2.2 MacOS specifics

The CMake build system can search for dependencies from Homebrew or MacPorts: use 'cmake -DUSE_HOMEBREW=ON' to search for Homebrew packages, or 'cmake -DUSE_MACPORTS=ON' to search installed MacPorts. Just not both.

1.2.3 Windows tricks

Modern versions of Microsoft Visual Studio provide support for CMake projects out-of-box, including intellisense, integrated options editor, test explorer, and more.

In order to use it for Serf, open the source directory with Visual Studio, and the configuration should start automatically. For editing the cache (options), do right-click to the CMakeLists.txt file and clicking CMake Settings for Serf will open the editor. After the required settings are configured, hit F7 in order to build. For more info, check the article bellow:
```
https://learn.microsoft.com/en-us/cpp/build/cmake-projects-in-visual-studio
```
There is a useful tool for bootstrapping the dependencies, vcpkg. It provides ports for the most of Serf's dependencies, which then could be installed via a single command.

To start using it, download the registry from GitHub, bootstrap vcpkg, and install the dependencies:
```
$ git clone https://github.com/microsoft/vcpkg
$ cd vcpkg && .\bootstrap-vcpkg.bat -disableMetrics
$ .\vcpkg install apr apr-util [any other dependency]
```
After this is done, vcpkg can be integrated into CMake by passing the vcpkg toolchain to CMAKE_TOOLCHAIN_FILE option. In order to do it with Visual Studio, open the CMake cache editor as explained in the previous step, and put the following into CMake toolchain file field, where VCPKG_ROOT is the path to vcpkg registry:
```
<VCPKG_ROOT>/scripts/buildsystems/vcpkg.cmake
```

1.2.4 Running the test suite

To run the test suite, go to the CMake output directory, then:

$ ctest

or, with a multi-config generator:

$ ctest -C Release

This is equivalent to:

$ cmake --build out --target test

or:

$ cmake --build out --config Release --target test

or, on Windows using the Visual Studio generator:

$ cmake --build out --config Release --target run_tests

)

Some tests take a long time to run, for example a 4GB request. These can be enabled by passing ENABLE_SLOW_TESTS on the command line:

$ cmake -DENABLE_SLOW_TESTS=ON

1.2.5 Installing Apache Serf

$ cmake --build out --target install
$ cmake --build out --config Release --target install