[lldb][docs] Add documentation for LLDB fuzzers

[cassanova]

Summary

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.

[mib]

Left few comments :)

lldb/docs/resources/fuzzing.rst

13

missing word ?

29–34

Don't we have a top-level ninja lldb-fuzzer command that runs all the fuzzer ? If not, what about adding that ?

38

Is it an issue to have this enabled for the other fuzzers ? If not, may be you should just add it to the general cmake invocation

[JDevlieghere]

lldb/docs/resources/fuzzing.rst

15–27

I would simplify this a bit and say that in addition to your regular CMake arguments, you have to pass -DLLVM_USE_SANITIZER='Address' -DLLVM_USE_SANITIZE_COVERAGE=On. I think the libfuzzer documentation says something similar so in addition to listing that explicitly here, we should also include a link to that (in case that ever changes in the future).

43

I think this could be its own section that talks about where the fuzzers are (will be) running.

45

48–50

I would say "from the build directory" and use relative paths here.

70–73

This is specific to LLDB's target fuzzer and not something I think folks should rely on. libfuzzer makes it really easy to reproduce bugs (as you explain below) so we should encourage everyone to use that.

[JDevlieghere]

lldb/docs/resources/fuzzing.rst

29–34

Building all the fuzzers (lldb-fuzzer(s)) or running all the fuzzers (fuzz-lldb)?

Personally +1 having a target that builds all the fuzzers. I'm not sure if I would ever want to run all the fuzzers in parallel, but I'm also not opposed to the idea as it would be similar to what check-lldb does.

[mib]

lldb/docs/resources/fuzzing.rst

29–34

Yeah, I meant for building the fuzzers (I haven't commented below on the running the fuzzer in parallel for that reason)

[cassanova]

lldb/docs/resources/fuzzing.rst

13

Yep :)

15–27

That's a good idea. I didn't mention this explicitly here but I put the entire CMake invocation because I assumed that someone who wanted to try this would be making a new, not-in-source-tree build directory.

38

Having this enabled doesn't cause problems for the other fuzzers. I had this on its own in case there were people that didn't want to use all of the fuzzers and therefore wouldn't need this option enabled all the time.

I can place this in the line that would say "In addition to your regular CMake arguments...". Also having a target that builds all fuzzers is a good idea.

43

I can add a "Continuous Integration" section for OSS Fuzz

48–50

Sounds good, what's funny is that I originally had the relative directories and then I removed them to try and be more general :)

70–73

That makes sense, I used the target fuzzer as an example for using fuzzer inputs with LLDB itself but for reproducing it's better to use libFuzzer.

[cassanova]

Removed the full CMake invocation for the fuzzer build configuration.

Added the information on OSS Fuzz to its own section.

Changed build directory in fuzzer execution command to use a relative path.

Removed reference to using LLDB with fuzzer inputs.

Fixed typos.

[JDevlieghere]

LGTM modulo inline comment.

lldb/docs/resources/fuzzing.rst

16–18

Remove the $ because these are not shell commands.

lldb/docs/index.rst

 .. toctree::
    :hidden:
    :maxdepth: 1
    :caption: Development
 
    resources/contributing
    resources/build
    resources/test
+   resources/fuzzing
    resources/bots
    resources/caveats
 
 
 .. toctree::
    :hidden:
    :maxdepth: 1
    :caption: Design

lldb/docs/resources/fuzzing.rst

+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 enabled. In addition to your regular CMake arguments, you will need these argumets to build the fuzzers:
+
+::
+   -DLLVM_USE_SANITIZER='Address' \
+   -DLLVM_USE_SANITIZE_COVERAGE=On \
+   -DCLANG_ENABLE_PROTO_FUZZER=ON
+
+More information on libFuzzer's sanitizer coverage is available here: `<https://llvm.org/docs/LibFuzzer.html#fuzzer-usage>`_
+
+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.
+
+Continuous integration
+----------------------
+
+Currently, there are plans to integrate the LLDB fuzzers into the `OSS Fuzz <https://github.com/google/oss-fuzz>`_ project for continuous integration.
+
+Running the fuzzers
+-------------------
+
+If you want to run the fuzzers locally, you can run the binaries that were generated with ninja from the build directory:
+
+::
+   $ ./bin/lldb-target-fuzzer
+   $ ./bin/lldb-commandinterpreter-fuzzer
+   $ ./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 individual input to the fuzzer binary as a command-line argument:
+
+::
+   $ ./<fuzzer binary> <input you are investigating>