[llvm] Add documentation on debugging LLVM. (PR #156128)

[Peter Collingbourne via llvm-commits]

================
@@ -0,0 +1,110 @@
+==============
+Debugging LLVM
+==============
+
+This document is a collection of tips and tricks for debugging LLVM
+using a source-level debugger. The assumption is that you are trying to
+figure out the root cause of a miscompilation in the program that you
+are compiling.
+
+Extract and rerun the compile command
+=====================================
+
+Extract the Clang command that produces the buggy code. The way to do
+this depends on the build system used by your program.
+
+- For Ninja-based build systems, you can pass ``-t commands`` to Ninja
+  and filter the output by the targeted source file name. For example:
+  ``ninja -t commands myprogram | grep path/to/file.cpp``.
+
+- For Bazel-based build systems using Bazel 9 or newer (not released yet
+  as of this writing), you can pass ``--output=commands`` to the ``bazel
+  aquery`` subcommand for a similar result. For example: ``bazel aquery
+  --output=commands 'deps(//myprogram)' | grep path/to/file.cpp``. Build
+  commands must generally be run from a subdirectory of the source
+  directory named ``bazel-$PROJECTNAME``. Bazel typically makes the target
+  paths of ``-o`` and ``-MF`` read-only when running commands outside
+  of a build, so it may be necessary to change or remove these flags.
+
+- A method that should work with any build system is to build your program
+  under `Bear <https://github.com/rizsotto/Bear>`_ and look for the
+  compile command in the resulting ``compile_commands.json`` file.
+
+Once you have the command you can use the following steps to debug
+it. Note that any flags mentioned later in this document are LLVM flags
+so they must be prefixed with ``-mllvm`` when passed to the Clang driver,
+e.g. ``-mllvm -print-after-all``.
+
+Understanding the source of the issue
+=====================================
+
+If you have a miscompilation introduced by a pass, it is frequently
+possible to identify the pass where things go wrong by searching a
+pass-by-pass printout, which is enabled using the ``-print-after-all``
+flag. Pipe stderr into ``less`` (append ``2>&1 | less`` to command
+line) and use text search to move between passes (e.g. type ``/Dump
+After<Enter>``, ``n`` to move to next pass, ``N`` to move to previous
+pass). If the name of the function containing the buggy IR is known, you
+can filter the output by passing ``-filter-print-funcs=functionname``. You
+can sometimes pass ``-debug`` to get useful details about what passes
+are doing.
+
+Creating a debug build of LLVM
+==============================
+
+The subsequent debugging steps require a debug build of LLVM. Pass the
+``-DCMAKE_BUILD_TYPE=Debug`` to CMake in a separate build tree to create
+a debug build.
+
+Understanding where an instruction came from
+============================================
+
+A common debugging task involves understanding which part of the code
+introduced a buggy instruction. The pass-by-pass dump is sometimes enough,
+but for complex or unfamiliar passes, more information is often required.
+
+The first step is to record a run of the debug build of Clang under `rr
----------------
pcc wrote:

Yeah, but you can't usually tell ahead of time that you're not going to hit an `<optimized out>` so it seems simplest to use a full debug build for this.

At some point I want other build systems to get something like Bazel's `--per_file_copt` for easily opting TUs into debug info without having to rebuild the whole thing but that's getting a bit off topic.

https://github.com/llvm/llvm-project/pull/156128