A Foundation Library
=====================

This is a C++ foundation library. It contains fundamental algorithms,
functions, and operating system bindings merged from several projects
of mine, intended to replace the separate implementations. Operating
system bindings include threads and synchronisation, time, and
networking. On top, we implement a few network protocols.

It is written in C++03, and thus it's probably not too exciting if you
can use all of Boost, or have a full C++1y compiler at hand. On the
plus side, it's simple and lean.

In addition to a number of simple off-the-shelf algorithms (that can
of course be handy by themselves), two comparatively-novel approaches
are taken for

- memory buffers. Instead of pointer,length pairs, the library uses
  descriptors (afl::base::Memory) that support all operations you'd
  want on a buffer (copy, split, etc.). The idea is it to make harder
  to program buffer overflows.

- asynchronous operations. The afl::async framework can be used for
  inter-thread communication and for networking. Instead of requiring
  callbacks, you post operations to a controller, which returns you
  these operations as they complete. The operation object also is a
  handle to cancel an operation mid-way should you change your mind.


Testsuite
----------

The library comes with an extensive testsuite.

The testsuite will also test a number of timed operations. To keep the
total running time of the testsuite low, timeouts sometimes are pretty
tight. This requires you to run the testsuite on an idle processor to
avoid sporadic failures.


Building
---------

Makefiles are generated using https://github.com/stefanreuther/accidental-build

To build:

    mkdir afl-build
    cd afl-build
    /path/to/accidental-build/Make.pl IN=/path/to/afl prefix=result
    make all test install

This will build everything and place the result in afl-build/result.

The build system supports out-of-tree builds, parallelisation, and
automatic dependencies.

To add or remove files, modify the file list file in P9/Settings.


Source Code Layout
-------------------

- P9/       Old Makefile generator inputs; now only file list.
- afl/      Main library.
- app/      Example applications.
- arch/     Platform specifics. Do not include in your applications.
            These expect a target macro (TARGET_OS_POSIX, TARGET_OS_WIN32)
            to be set, which is done by the Makefile (but which is most
            likely not set in user code).
- config/   Configuration specifics. Do not include in your applications.
            These expect a macro from afl/config.h to be set.
- etc/      Extra (non source) files.
- test/     Unit tests.

For compiling your own applications, point "-I" to the source root
directory, so you can include afl header files as "afl/...".