Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(483)

Side by Side Diff: third_party/afl/src/docs/INSTALL

Issue 2075883002: Add American Fuzzy Lop (afl) to third_party/afl/ (Closed) Base URL: https://chromium.googlesource.com/chromium/src.git@master
Patch Set: Fix nits Created 4 years, 6 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
« no previous file with comments | « third_party/afl/src/docs/ChangeLog ('k') | third_party/afl/src/docs/QuickStartGuide.txt » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
(Empty)
1 =========================
2 Installation instructions
3 =========================
4
5 This document provides basic installation instructions and discusses known
6 issues for a variety of platforms. See README for the general instruction
7 manual.
8
9 1) Linux on x86
10 ---------------
11
12 This platform is expected to work well. Compile the program with:
13
14 $ make
15
16 You can start using the fuzzer without installation, but it is also possible to
17 install it with:
18
19 # make install
20
21 There are no special dependencies to speak of; you will need GNU make and a
22 working compiler (gcc or clang). Some of the optional scripts bundled with the
23 program may depend on bash, gdb, and similar basic tools.
24
25 If you are using clang, please review llvm_mode/README.llvm; the LLVM
26 integration mode can offer substantial performance gains compared to the
27 traditional approach.
28
29 You may have to change several settings to get optimal results (most notably,
30 disable crash reporting utilities and switch to a different CPU governor), but
31 afl-fuzz will guide you through that if necessary.
32
33 2) OpenBSD, FreeBSD, NetBSD on x86
34 ----------------------------------
35
36 Similarly to Linux, these platforms are expected to work well and are
37 regularly tested. Compile everything with GNU make:
38
39 $ gmake
40
41 Note that BSD make will *not* work; if you do not have gmake on your system,
42 please install it first. As on Linux, you can use the fuzzer itself without
43 installation, or install it with:
44
45 # gmake install
46
47 Keep in mind that if you are using csh as your shell, the syntax of some of the
48 shell commands given in the README and other docs will be different.
49
50 The llvm_mode requires a dynamically linked, fully-operational installation of
51 clang. At least on FreeBSD, the clang binaries are static and do not include
52 some of the essential tools, so if you want to make it work, you may need to
53 follow the instructions in llvm_mode/README.llvm.
54
55 Beyond that, everything should work as advertised.
56
57 The QEMU mode is currently supported only on Linux. I think it's just a QEMU
58 problem, I couldn't get a vanilla copy of user-mode emulation support working
59 correctly on BSD at all.
60
61 3) MacOS X on x86
62 -----------------
63
64 MacOS X should work, but there are some gotchas due to the idiosyncrasies of
65 the platform. On top of this, I have limited release testing capabilities
66 and depend mostly on user feedback.
67
68 To build AFL, install Xcode and follow the general instructions for Linux.
69
70 The Xcode 'gcc' tool is just a wrapper for clang, so be sure to use afl-clang
71 to compile any instrumented binaries; afl-gcc will fail unless you have GCC
72 installed from another source (in which case, please specify AFL_CC and
73 AFL_CXX to point to the "real" GCC binaries).
74
75 Only 64-bit compilation will work on the platform; porting the 32-bit
76 instrumentation would require a fair amount of work due to the way OS X
77 handles relocations, and today, virtually all MacOS X boxes are 64-bit.
78
79 The crash reporting daemon that comes by default with MacOS X will cause
80 problems with fuzzing. You need to turn it off by following the instructions
81 provided here: http://goo.gl/CCcd5u
82
83 The fork() semantics on OS X are a bit unusual compared to other unix systems
84 and definitely don't look POSIX-compliant. This means two things:
85
86 - Fuzzing will be probably slower than on Linux. In fact, some folks report
87 considerable performance gains by running the jobs inside a Linux VM on
88 MacOS X.
89
90 - Some non-portable, platform-specific code may be incompatible with the
91 AFL forkserver. If you run into any problems, set AFL_NO_FORKSRV=1 in the
92 environment before starting afl-fuzz.
93
94 User emulation mode of QEMU does not appear to be supported on MacOS X, so
95 black-box instrumentation mode (-Q) will not work.
96
97 The llvm_mode requires a fully-operational installation of clang. The one that
98 comes with Xcode is missing some of the essential headers and helper tools.
99 See llvm_mode/README.llvm for advice on how to build the compiler from scratch.
100
101 4) Linux or *BSD on non-x86 systems
102 -----------------------------------
103
104 Standard build will fail on non-x86 systems, but you should be able to
105 leverage two other options:
106
107 - The LLVM mode (see llvm_mode/README.llvm), which does not rely on
108 x86-specific assembly shims. It's fast and robust, but requires a
109 complete installation of clang.
110
111 - The QEMU mode (see qemu_mode/README.qemu), which can be also used for
112 fuzzing cross-platform binaries. It's slower and more fragile, but
113 can be used even when you don't have the source for the tested app.
114
115 If you're not sure what you need, you need the LLVM mode. To get it, try:
116
117 $ AFL_NO_X86=1 gmake && gmake -C llvm_mode
118
119 ...and compile your target program with afl-clang-fast or afl-clang-fast++
120 instead of the traditional afl-gcc or afl-clang wrappers.
121
122 5) Solaris on x86
123 -----------------
124
125 The fuzzer reportedly works on Solaris, but I have not tested this first-hand,
126 and the user base is fairly small, so I don't have a lot of feedback.
127
128 To get the ball rolling, you will need to use GNU make and GCC or clang. I'm
129 being told that the stock version of GCC that comes with the platform does not
130 work properly due to its reliance on a hardcoded location for 'as' (completely
131 ignoring the -B parameter or $PATH).
132
133 To fix this, you may want to build stock GCC from the source, like so:
134
135 $ ./configure --prefix=$HOME/gcc --with-gnu-as --with-gnu-ld \
136 --with-gmp-include=/usr/include/gmp --with-mpfr-include=/usr/include/mpfr
137 $ make
138 $ sudo make install
139
140 Do *not* specify --with-as=/usr/gnu/bin/as - this will produce a GCC binary that
141 ignores the -B flag and you will be back to square one.
142
143 If you have system-wide crash reporting enabled, you may run into problems
144 similar to the gotchas for Linux and MacOS X, but I have not verified this.
145 More information about AppCrash can be found here:
146
147 http://www.oracle.com/technetwork/server-storage/solaris10/app-crash-142906.ht ml
148
149 User emulation mode of QEMU is not available on Solaris, so black-box
150 instrumentation mode (-Q) will not work.
151
152 6) Everything else
153 ------------------
154
155 You're on your own. On POSIX-compliant systems, you may be able to compile and
156 run the fuzzer; and the LLVM mode may offer a way to instrument non-x86 code.
157
158 The fuzzer will not run on Windows. It will also not work under Cygwin. It
159 could be ported to the latter platform fairly easily, but it's a pretty bad
160 idea, because Cygwin is extremely slow. It makes much more sense to use
161 VirtualBox or so to run a hardware-accelerated Linux VM; it will run around
162 20x faster or so. If you have a *really* compelling use case for Cygwin, let
163 me know.
164
165 Although Android on x86 should theoretically work, the stock kernel has SHM
166 support compiled out, so you will need to address this issue first. It's
167 possible that all you need is this:
168
169 https://github.com/pelya/android-shmem
OLDNEW
« no previous file with comments | « third_party/afl/src/docs/ChangeLog ('k') | third_party/afl/src/docs/QuickStartGuide.txt » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698