README

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
  * People: Justin Erenkrantz, Greg Stein

----

1. INSTALL

1.1 Build systems

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

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