clang/tools/clang-fuzzer/README.txt

   1 This directory contains three utilities for fuzzing Clang: clang-fuzzer,
   2 clang-objc-fuzzer, and clang-proto-fuzzer. All use libFuzzer to generate inputs
   3 to clang via coverage-guided mutation.
   4
   5 The three utilities differ, however, in how they structure inputs to Clang.
   6 clang-fuzzer makes no attempt to generate valid C++ programs and is therefore
   7 primarily useful for stressing the surface layers of Clang (i.e. lexer, parser).
   8
   9 clang-objc-fuzzer is similar but for Objective-C: it makes no attempt to
  10 generate a valid Objective-C program.
  11
  12 clang-proto-fuzzer uses a protobuf class to describe a subset of the C++
  13 language and then uses libprotobuf-mutator to mutate instantiations of that
  14 class, producing valid C++ programs in the process.  As a result,
  15 clang-proto-fuzzer is better at stressing deeper layers of Clang and LLVM.
  16
  17 Some of the fuzzers have example corpuses inside the corpus_examples directory.
  18
  19 ===================================
  20  Building clang-fuzzer
  21 ===================================
  22 Within your LLVM build directory, run CMake with the following variable
  23 definitions:
  24 - CMAKE_C_COMPILER=clang
  25 - CMAKE_CXX_COMPILER=clang++
  26 - LLVM_USE_SANITIZE_COVERAGE=YES
  27 - LLVM_USE_SANITIZER=Address
  28
  29 Then build the clang-fuzzer target.
  30
  31 Example:
  32   cd $LLVM_SOURCE_DIR
  33   mkdir build && cd build
  34   cmake .. -GNinja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
  35     -DLLVM_USE_SANITIZE_COVERAGE=YES -DLLVM_USE_SANITIZER=Address
  36   ninja clang-fuzzer
  37
  38 ======================
  39  Running clang-fuzzer
  40 ======================
  41   bin/clang-fuzzer CORPUS_DIR
  42
  43
  44 ===================================
  45  Building clang-objc-fuzzer
  46 ===================================
  47 Within your LLVM build directory, run CMake with the following variable
  48 definitions:
  49 - CMAKE_C_COMPILER=clang
  50 - CMAKE_CXX_COMPILER=clang++
  51 - LLVM_USE_SANITIZE_COVERAGE=YES
  52 - LLVM_USE_SANITIZER=Address
  53
  54 Then build the clang-objc-fuzzer target.
  55
  56 Example:
  57   cd $LLVM_SOURCE_DIR
  58   mkdir build && cd build
  59   cmake .. -GNinja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
  60     -DLLVM_USE_SANITIZE_COVERAGE=YES -DLLVM_USE_SANITIZER=Address
  61   ninja clang-objc-fuzzer
  62
  63 ======================
  64  Running clang-objc-fuzzer
  65 ======================
  66   bin/clang-objc-fuzzer CORPUS_DIR
  67
  68 e.g. using the example objc corpus,
  69
  70   bin/clang-objc-fuzzer <path to corpus_examples/objc> <path to new directory to store  corpus findings>
  71
  72
  73 =======================================================
  74  Building clang-proto-fuzzer (Linux-only instructions)
  75 =======================================================
  76 Install the necessary dependencies:
  77 - binutils  // needed for libprotobuf-mutator
  78 - liblzma-dev  // needed for libprotobuf-mutator
  79 - libz-dev  // needed for libprotobuf-mutator
  80 - docbook2x  // needed for libprotobuf-mutator
  81 - Recent version of protobuf [3.3.0 is known to work]
  82
  83 Within your LLVM build directory, run CMake with the following variable
  84 definitions:
  85 - CMAKE_C_COMPILER=clang
  86 - CMAKE_CXX_COMPILER=clang++
  87 - LLVM_USE_SANITIZE_COVERAGE=YES
  88 - LLVM_USE_SANITIZER=Address
  89 - CLANG_ENABLE_PROTO_FUZZER=ON
  90
  91 Then build the clang-proto-fuzzer and clang-proto-to-cxx targets.  Optionally,
  92 you may also build clang-fuzzer with this setup.
  93
  94 Example:
  95   cd $LLVM_SOURCE_DIR
  96   mkdir build && cd build
  97   cmake .. -GNinja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
  98     -DLLVM_USE_SANITIZE_COVERAGE=YES -DLLVM_USE_SANITIZER=Address \
  99     -DCLANG_ENABLE_PROTO_FUZZER=ON
 100   ninja clang-proto-fuzzer clang-proto-to-cxx
 101
 102 This directory also contains a Dockerfile which sets up all required
 103 dependencies and builds the fuzzers.
 104
 105 ============================
 106  Running clang-proto-fuzzer
 107 ============================
 108   bin/clang-proto-fuzzer CORPUS_DIR
 109
 110 Arguments can be specified after -ignore_remaining_args=1 to modify the compiler
 111 invocation.  For example, the following command line will fuzz LLVM with a
 112 custom optimization level and target triple:
 113   bin/clang-proto-fuzzer CORPUS_DIR -ignore_remaining_args=1 -O3 -triple \
 114       arm64apple-ios9
 115
 116 To translate a clang-proto-fuzzer corpus output to C++:
 117   bin/clang-proto-to-cxx CORPUS_OUTPUT_FILE
 118
 119 ===================
 120  llvm-proto-fuzzer
 121 ===================
 122 Like, clang-proto-fuzzer, llvm-proto-fuzzer is also a protobuf-mutator based
 123 fuzzer. It receives as input a cxx_loop_proto which it then converts into a
 124 string of valid LLVM IR: a function with either a single loop or two nested
 125 loops. It then creates a new string of IR by running optimization passes over
 126 the original IR. Currently, it only runs a loop-vectorize pass but more passes
 127 can easily be added to the fuzzer. Once there are two versions of the input
 128 function (optimized and not), llvm-proto-fuzzer uses LLVM's JIT Engine to
 129 compile both functions. Lastly, it runs both functions on a suite of inputs and
 130 checks that both functions behave the same on all inputs. In this way,
 131 llvm-proto-fuzzer can find not only compiler crashes, but also miscompiles
 132 originating from LLVM's optimization passes.
 133
 134 llvm-proto-fuzzer is built very similarly to clang-proto-fuzzer. You can run the
 135 fuzzer with the following command:
 136   bin/clang-llvm-proto-fuzzer CORPUS_DIR
 137
 138 To translate a cxx_loop_proto file into LLVM IR do:
 139   bin/clang-loop-proto-to-llvm CORPUS_OUTPUT_FILE
 140 To translate a cxx_loop_proto file into C++ do:
 141   bin/clang-loop-proto-to-cxx CORPUS_OUTPUT_FILE
 142
 143 Note: To get a higher number of executions per second with llvm-proto-fuzzer it
 144 helps to build it without ASan instrumentation and with the -O2 flag. Because
 145 the fuzzer is not only compiling code, but also running it, as the inputs get
 146 large, the time necessary to fuzz one input can get very high.
 147 Example:
 148   cmake .. -GNinja -DCMAKE_C_COMPILER=clang -DCMAKE_CXX_COMPILER=clang++ \
 149     -DCLANG_ENABLE_PROTO_FUZZER=ON -DLLVM_USE_SANITIZE_COVERAGE=YES \
 150     -DCMAKE_CXX_FLAGS="-O2"
 151   ninja clang-llvm-proto-fuzzer clang-loop-proto-to-llvm