[Lldb-commits] [PATCH] D132148: [lldb][docs] Add documentation for LLDB fuzzers

[Chelsea Cassanova via Phabricator via lldb-commits]

cassanova created this revision.
cassanova added reviewers: JDevlieghere, mib.
cassanova added a project: LLDB.
Herald added a subscriber: arphaman.
Herald added a project: All.
cassanova requested review of this revision.
Herald added a subscriber: lldb-commits.

This commit adds a new page to the LLDB HTML documentation for the LLDB fuzzers. The page primarily explains what the fuzzers are as well as how to build them, run them and investigate and reproduce bugs.


Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D132148

Files:
  lldb/docs/index.rst
  lldb/docs/resources/fuzzing.rst


Index: lldb/docs/resources/fuzzing.rst
===================================================================
--- /dev/null
+++ lldb/docs/resources/fuzzing.rst
@@ -0,0 +1,77 @@
+Fuzzing LLDB
+============
+
+Overview
+--------
+
+LLDB has fuzzers that provide automated `fuzz testing <https://en.wikipedia.org/wiki/Fuzzing>`_ for different components of LLDB. The fuzzers are built with `libFuzzer <https://llvm.org/docs/LibFuzzer.html>`_ . Currently, there are fuzzers for target creation, LLDB's command interpreter and LLDB's expression evaluator.
+
+Building the fuzzers
+--------------------
+
+Building the LLDB fuzzers requires a build configuration that has the address sanitizer and sanitizer coverage. This CMake invocation will configure a build directory that can be used to build the LLDB fuzzers:
+
+::
+   $ cmake <path to root of llvm source tree> \
+        -G Ninja \
+        -DCMAKE_BUILD_TYPE='Release' \
+        -DLLVM_USE_SANITIZER='Address' \
+        -DLLVM_USE_SANITIZE_COVERAGE=On \
+        -DLLVM_BUILD_RUNTIME=Off \
+        -DLLVM_ENABLE_ASSERTIONS:BOOL=ON \
+        -DLLDB_ENABLE_PYTHON=ON \
+        -DLLVM_ENABLE_PROJECTS='llvm;clang;lldb' \
+        -DLLVM_ENABLE_RUNTIMES='libcxx;libcxxabi'
+
+If you want to debug LLDB itself when you find a bug using the fuzzers, use the CMake option ``-DCMAKE_BUILD_TYPE='RelWithDebInfo'``
+
+To build a fuzzer, run the desired ninja command for the fuzzer(s) you want to build:
+
+::
+   $ ninja lldb-target-fuzzer
+   $ ninja lldb-commandinterpreter-fuzzer
+   $ ninja lldb-expression-fuzzer
+
+Once built, the binaries for the fuzzers will exist in the ``bin`` directory of your build folder.
+
+Note that building the LLDB expression evaluator fuzzer will require the CMake option ``-DCLANG_ENABLE_PROTO_FUZZER=ON``.
+
+Running the fuzzers
+-------------------
+
+Currently, there are plans to integrate the LLDB fuzzers into the `OSS Fuzz <https://github.com/google/oss-fuzz>`_ project for continuous integration.
+
+If you want to run the fuzzers on your own machine, you can run the binaries that were generated with ninja:
+
+::
+   $ ./<lldb fuzzer build directory>/bin/lldb-target-fuzzer
+   $ ./<lldb fuzzer build directory>/bin/lldb-commandinterpreter-fuzzer
+   $ ./<lldb fuzzer build directory>/bin/lldb-expression-fuzzer
+
+This will run the fuzzer binaries directly, and you can use the `libFuzzer options <https://llvm.org/docs/LibFuzzer.html#options>`_ to customize how the fuzzers are run.
+
+Another way to run the fuzzers is to use a ninja target that will both build the fuzzers and then run them immediately after. These custom targets run each fuzzer with command-line arguments that provide better fuzzing for the components being tested. Running the fuzzers this way will also create directories that will store any inputs that caused LLDB to crash, timeout or run out of memory. The directories are created for each fuzzer.
+
+To run the custom ninja targets, run the command for your desired fuzzer:
+
+::
+   $ ninja fuzz-lldb-target
+   $ ninja fuzz-lldb-commandinterpreter
+   $ ninja fuzz-lldb-expression
+
+Investigating and reproducing bugs
+----------------------------------
+
+When the fuzzers find an input that causes LLDB to crash, timeout or run out of memory, the input is saved to a file in the build directory. When running the fuzzer binaries directly this input is stored in a file named ``<crash/timeout/oom>-<hash>``.
+
+When running the fuzzers using the custom ninja targets shown above, the inputs will be stored in ``fuzzer-artifacts/<fuzzer name>-artifacts``, which is created in your build directory. The input files will have the name ``<fuzzer name>-<crash/timeout/oom>-<hash>``.
+
+If you want to reproduce the issue found by a fuzzer once you have gotten the input, you can pass the input to LLDB depending on which component you were fuzzing. For example, if you found an input that crashed target creation, you could run:
+
+::
+   $ lldb <input you are investigating>
+
+If you want to reproduce the issue found by a fuzzer once you have gotten the input, you can pass the individual input to the fuzzer binary as a command-line argument:
+
+::
+   $ ./<fuzzer binary> <input you are investigating>
Index: lldb/docs/index.rst
===================================================================
--- lldb/docs/index.rst
+++ lldb/docs/index.rst
@@ -150,6 +150,7 @@
    resources/contributing
    resources/build
    resources/test
+   resources/fuzzing
    resources/bots
    resources/caveats
 


-------------- next part --------------
A non-text attachment was scrubbed...
Name: D132148.453707.patch
Type: text/x-patch
Size: 4526 bytes
Desc: not available
URL: <http://lists.llvm.org/pipermail/lldb-commits/attachments/20220818/7f915105/attachment.bin>