Index: third_party/afl/src/docs/INSTALL |
diff --git a/third_party/afl/src/docs/INSTALL b/third_party/afl/src/docs/INSTALL |
new file mode 100644 |
index 0000000000000000000000000000000000000000..6c44b922d47ceaa1b3a3268807f28e652dfa47a2 |
--- /dev/null |
+++ b/third_party/afl/src/docs/INSTALL |
@@ -0,0 +1,169 @@ |
+========================= |
+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. |
+ |
+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 |
+------------------ |
+ |
+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 has SHM |
+support compiled out, so you will need to address this issue first. It's |
+possible that all you need is this: |
+ |
+ https://github.com/pelya/android-shmem |