docs/INSTALL - platform/external/AFLplusplus - Git at Google

 =========================
 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 start 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.

 If you are using clang, please review llvm_mode/README.llvm; the LLVM
 integration mode can offer substantial performance gains compared to the
 traditional approach.

 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 everything 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.

 The llvm_mode requires a dynamically linked, fully-operational installation of
 clang. At least on FreeBSD, the clang binaries are static and do not include
 some of the essential tools, so if you want to make it work, you may need to
 follow the instructions in llvm_mode/README.llvm.

 Beyond that, everything should work as advertised.

 The QEMU mode is currently supported only on Linux. I think it's just a QEMU
 problem, I couldn't get a vanilla copy of user-mode emulation support working
 correctly on BSD at all.

 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.

 The llvm_mode requires a fully-operational installation of clang. The one that
 comes with Xcode is missing some of the essential headers and helper tools.
 See llvm_mode/README.llvm for advice on how to build the compiler from scratch.

 4) Linux or *BSD on non-x86 systems
 -----------------------------------

 Standard build will fail on non-x86 systems, but you should be able to
 leverage two other options:

   - The LLVM mode (see llvm_mode/README.llvm), which does not rely on
     x86-specific assembly shims. It's fast and robust, but requires a
     complete installation of clang.

   - The QEMU mode (see qemu_mode/README.qemu), which can be also used for
     fuzzing cross-platform binaries. It's slower and more fragile, but
     can be used even when you don't have the source for the tested app.

 If you're not sure what you need, you need the LLVM mode. To get it, try:

 $ AFL_NO_X86=1 gmake && gmake -C llvm_mode

 ...and compile your target program with afl-clang-fast or afl-clang-fast++
 instead of the traditional afl-gcc or afl-clang wrappers.

 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, so I don't have a lot of feedback.

 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.

 Note that Solaris reportedly comes with crash reporting enabled, which causes
 problems with crashes being misinterpreted as hangs, similarly to the gotchas
 for Linux and MacOS X. AFL does not auto-detect crash reporting on this
 particular platform, but you may need to run the following command:

 $ coreadm -d global -d global-setid -d process -d proc-setid \
   -d kzone -d log

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

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

 You're on your own. On POSIX-compliant systems, you may be able to compile and
 run the fuzzer; and the LLVM mode may offer a way to instrument non-x86 code.

 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; it will run around
 20x faster or so. If you have a *really* compelling use case for Cygwin, let
 me know.

 Although Android on x86 should theoretically work, the stock kernel may have
 SHM support compiled out, and if so, you may have to address that issue first.
 It's possible that all you need is this workaround:

   https://github.com/pelya/android-shmem

 Joshua J. Drake notes that the Android linker adds a shim that automatically
 intercepts SIGSEGV and related signals. To fix this issue and be able to see
 crashes, you need to put this at the beginning of the fuzzed program:

   signal(SIGILL, SIG_DFL);
   signal(SIGABRT, SIG_DFL);
   signal(SIGBUS, SIG_DFL);
   signal(SIGFPE, SIG_DFL);
   signal(SIGSEGV, SIG_DFL);

 You may need to #include <signal.h> first.
	=========================
	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 start 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.

	If you are using clang, please review llvm_mode/README.llvm; the LLVM
	integration mode can offer substantial performance gains compared to the
	traditional approach.

	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 everything 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.

	The llvm_mode requires a dynamically linked, fully-operational installation of
	clang. At least on FreeBSD, the clang binaries are static and do not include
	some of the essential tools, so if you want to make it work, you may need to
	follow the instructions in llvm_mode/README.llvm.

	Beyond that, everything should work as advertised.

	The QEMU mode is currently supported only on Linux. I think it's just a QEMU
	problem, I couldn't get a vanilla copy of user-mode emulation support working
	correctly on BSD at all.

	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.

	The llvm_mode requires a fully-operational installation of clang. The one that
	comes with Xcode is missing some of the essential headers and helper tools.
	See llvm_mode/README.llvm for advice on how to build the compiler from scratch.

	4) Linux or *BSD on non-x86 systems
	-----------------------------------

	Standard build will fail on non-x86 systems, but you should be able to
	leverage two other options:

	- The LLVM mode (see llvm_mode/README.llvm), which does not rely on
	x86-specific assembly shims. It's fast and robust, but requires a
	complete installation of clang.

	- The QEMU mode (see qemu_mode/README.qemu), which can be also used for
	fuzzing cross-platform binaries. It's slower and more fragile, but
	can be used even when you don't have the source for the tested app.

	If you're not sure what you need, you need the LLVM mode. To get it, try:

	$ AFL_NO_X86=1 gmake && gmake -C llvm_mode

	...and compile your target program with afl-clang-fast or afl-clang-fast++
	instead of the traditional afl-gcc or afl-clang wrappers.

	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, so I don't have a lot of feedback.

	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.

	Note that Solaris reportedly comes with crash reporting enabled, which causes
	problems with crashes being misinterpreted as hangs, similarly to the gotchas
	for Linux and MacOS X. AFL does not auto-detect crash reporting on this
	particular platform, but you may need to run the following command:

	$ coreadm -d global -d global-setid -d process -d proc-setid \
	-d kzone -d log

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

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

	You're on your own. On POSIX-compliant systems, you may be able to compile and
	run the fuzzer; and the LLVM mode may offer a way to instrument non-x86 code.

	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; it will run around
	20x faster or so. If you have a really compelling use case for Cygwin, let
	me know.

	Although Android on x86 should theoretically work, the stock kernel may have
	SHM support compiled out, and if so, you may have to address that issue first.
	It's possible that all you need is this workaround:

	https://github.com/pelya/android-shmem

	Joshua J. Drake notes that the Android linker adds a shim that automatically
	intercepts SIGSEGV and related signals. To fix this issue and be able to see
	crashes, you need to put this at the beginning of the fuzzed program:

	signal(SIGILL, SIG_DFL);
	signal(SIGABRT, SIG_DFL);
	signal(SIGBUS, SIG_DFL);
	signal(SIGFPE, SIG_DFL);
	signal(SIGSEGV, SIG_DFL);

	You may need to #include <signal.h> first.