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

  This document provides basic installation instructions and discusses known
  issues for a variety of platforms. See README for the general instruction
  manual.

1) Linux on x86
---------------

This platform is expected to work well. 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 bundled with the
program may depend on bash, gdb, and similar basic tools.

You may have to change several settings to get optimal results (most notably,
disable crash reporting utilities and switch to a different CPU governor), but
afl-fuzz will guide you through that if necessary.

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

Similarly to Linux, these platforms are expected to work well and are
regularly tested. 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.

The QEMU mode is currently supported only on Linux. I'll try to get BSD
working at some point in the not-too-distant future.

3) MacOS X on x86
-----------------

MacOS X should work, but there are some gotchas due to the idiosyncrasies of
the platform. On top of this, I have limited release testing capabilities
and depend mostly on user feedback.

To build AFL, install Xcode and follow the general instructions for Linux.

The Xcode 'gcc' tool is just a wrapper for clang, so be sure to use afl-clang
to compile any instrumented binaries; afl-gcc will fail unless you have GCC
installed from another source (in which case, please specify AFL_CC and
AFL_CXX to point to the "real" GCC binaries).

Only 64-bit compilation will work on the platform; porting the 32-bit
instrumentation would require a fair amount of work due to the way OS X
handles relocations, and today, virtually all MacOS X boxes are 64-bit.

The crash reporting daemon that comes by default with MacOS X will cause
problems with fuzzing. You need to 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
and definitely don't look POSIX-compliant. 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.

User emulation mode of QEMU does not appear to be supported on MacOS X, so
black-box instrumentation mode (-Q) will not work.

4) Linux or *BSD on ARMv7
-------------------------

ARMv7 is not officially supported. Your best option may be using the QEMU
instrumentation mode and ignoring the compile-time instrumentation capabilities
(since they will definitely, positively not work as-is).

To try out QEMU, remove the "xorb %al, %al" and "cmp -s .test-instr0" lines from
Makefile, build the fuzzer, and then then follow the instructions in the
qemu_mode/README.qemu file to compile the support for QEMU. If this succeeds,
you will have to compile targets *without* using afl-gcc, and then always
remember to invoke the fuzzer with -Q.

Alternatively, you can try an unofficial ARM patch that enables the compile-time
features, but it is buggy and no longer maintained. Please refer to
experimental/arm_support/README for hints.

5) Solaris on x86
-----------------

The fuzzer reportedly works on Solaris, but I have not tested this first-hand,
and the user base is fairly small.

To get the ball rolling, 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

Do *not* specify --with-as=/usr/gnu/bin/as - this will produce a GCC binary that
ignores the -B flag and you will be back to square one.

If you have system-wide crash reporting enabled, you may run into problems
similar to the gotchas for Linux and MacOS X, but I have not verified this.
More information about AppCrash can be found here:

  http://www.oracle.com/technetwork/server-storage/solaris10/app-crash-142906.html

User emulation mode of QEMU is not available on Solaris, so black-box
instrumentation mode (-Q) will not work.

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

More exotic CPU architectures are not supported and probably will not be. They
offer no intrinsic benefits for fuzzing and there is negligible user interest,
so I am prioritizing other work. You may be able to get QEMU mode to work by
following the instructions in section #4.

The fuzzer will not run on Windows. It will also not work under Cygwin. It
could be ported to the latter platform fairly easily, but it's a pretty bad
idea, because Cygwin is extremely slow. It makes much more sense to use
VirtualBox or so to run a hardware-accelerated Linux VM.

Although Android on x86 should theoretically work, the stock kernel has SHM
supported compiled out, so you will need to address this issue first.
