=========================
Installation instructions
=========================

  (See README for the general instruction manual.)

1) Linux (x86)
--------------

Compile the program with:

$ make

You can starting using the fuzzer without installation, but it is also possible
to install it with:

# make install

There are no special dependencies to speak of; you will need GNU make and a
working compiler (gcc or clang). Some of the optional scripts in experimental/*
may depend on bash, gdb, and similar basic tools.

2) OpenBSD, FreeBSD, NetBSD (x86)
---------------------------------

Compile with GNU make:

$ gmake

Note that BSD make will *not* work; if you do not have gmake on your system,
please install it first. As on Linux, you can use the fuzzer itself without
installation, or install it with:

# gmake install

Keep in mind that if you are using csh as your shell, the syntax of some of the
shell commands given in the README and other docs will be different. Beyond
that, everything should work as advertised.

3) MacOS X (x86)
----------------

Follow the instructions for Linux. Of course, you need Xcode installed to
compile this or any other program.

Note that 'gcc' is just a wrapper for clang on MacOS X, so you should compile
everything with afl-clang. If you have GCC installed, you can use the afl-gcc
wrappers, but specify AFL_CC or AFL_CXX to point to the real GCC binary.

At this point, only 64-bit compilation is supported; given that all modern
MacOS X boxes are 64-bit, and that 32-bit mode needs a fair amount of work due
to the idiosyncrasies of the platform, this is unlikely to change.

If the CrashReporter app gets in the way, you can turn it off by following the
instructions provided here: http://goo.gl/CCcd5u

The fork() semantics on OS X are a bit unusual compared to other unix systems.
This means two things:

  - Fuzzing will be probably slower than on Linux. In fact, some folks report
    considerable performance gains by running the jobs inside a Linux VM on
    MacOS X.

  - Some non-portable, platform-specific code may be incompatible with the
    afl forkserver. If you run into any problems, set AFL_NO_FORKSRV=1 in the
    environment before starting afl-fuzz.

4) Linux (ARMv7)
----------------

ARMv7 is not officially supported. You can try an unofficial patch, but
expect to run into some issues. Please refer to experimental/arm_support/README
for compilation and usage tips.

5) Solaris (x86)
----------------

The fuzzer reportedly works on Solaris; you will need to use GNU make and GCC or
clang. I'm being told that the stock version of GCC that comes with the platform
does not work properly due to its reliance on a hardcoded location for 'as'
(completely ignoring the -B parameter or $PATH).

To fix this, you may want to build stock GCC from the source, like so:

$ ./configure --prefix=$HOME/gcc --with-gnu-as --with-gnu-ld \
  --with-gmp-include=/usr/include/gmp --with-mpfr-include=/usr/include/mpfr
$ make
$ sudo make install

6) Everything else
------------------

CPU architectures other than x86 and ARMv7 will not work and support for them is
not planned. There are no intrinsic benefits of fuzzing on exotic hardware and
practically no user interest in doing so, so I'm prioritizing other work.

More exotic unix-like systems on x86 may turn out to be working, but they are
not officially supported and have not been tested.

The fuzzer will not work under Cygwin; it could be ported fairly easily, but
doing so is probably a bad idea: you will get much better results with a Linux
machine or a hardware-accelerated VM.
