[utils] Add a script that runs clang in LLDB and stops it when a specified diagnostic is emitted

[arphaman]

Summary

This script is useful while working on and debugging Clang's diagnostics, as you don't have to figure out where the diagnostic is emitted before setting a breakpoint for the emission of that diagnostic.

[hintonda]

Cool, I'll try to play with this later today.

BTW, since the call to DiagnosticsEngine::Report is delayed when using PartialDiagnostic, would it make sense to add them as well? Also, this doesn't seem to solve the initial problem of finding the Diag name in the first place.

Eventually, I'd like a scan-build like tool that let you rerun a particular compilation command (without needing to construct the -cc1 command yourself), that adds breakpoints for all warning/error diagnostics seen before invoking lldb -- perhaps even leveraging the compilation database, a la clang-tidy.

[arphaman]

It might make sense to add a breakpoint at PartialDiagnostic(unsigned DiagID, StorageAllocator &Allocator), I'll check how that works.

I reckon it should be possible to have a script that could find the name of all emitted diagnostics. Let's say we'd like to run clang with -cc1 main.cpp.
If we run it in LLDB and put a breakpoint at DiagnosticsEngine::Report, we could add a command to that breakpoint that would print a unique string and the diagnostic id.
The script would redirect the stdout from LLDB/Clang, but it would replace the occurrence of the unique string and diagnostic id with the name of the diagnostic by evaluating some diagtool that maps the id back to the diagnostic (If there are multiple same diagnostics it could also add an id and then we could extend this script to stop at the Nth specific diagnostic).

[hintonda]

This is a good example of how to script lldb, but it's predicated on knowing the diag name, which is great if you know the name.

However, this isn't my use case. I don't have the diag name, just a diagnostic message. In order to get the diag name associated with a specific diagnostic message, I have to grep the source, which was the original motivation behind D35175.

Here's how I currently do it:

1. select a partial substring from the diagnostic (omitting variable/class names and anything that might be part of a %select{}, e.g., (public|private|protected), etc...)
2. use grep to match a diagnostic definition in one of the diagnostic inc files generated by tblgen, i.e., tools/clang/include/clang/Basic/Diagnostic*.inc
3. if one or more matches found, select the correct one(s), otherwise, adjust substring and go back to 2
4. pass diag name(s) found in 3 to this tool

However, once the diag name is known, it would be just as easy to find/grep the source to find the file/line numbers and where the diag name is seen. Then you could either look directly at the source, or use them to set breakpoints in lldb. This avoids issues concerning late calls to report and PartialDiagnostic locations.

Alternatively, one could do what John suggested (paraphrasing here) and munge the strings found in tools/clang/include/clang/Basic/Diagnostic*.inc to create regular expressions and use flex to generate a lexer, or write one by hand, that could find a specific diag name that matched the diagnostic message. (obviously there are a lot of ways to do this)

[arphaman]

Makes sense. I'll see if I can get somewhere with the regex idea.

[hintonda]

In D36083#827745, @arphaman wrote:

Makes sense. I'll see if I can get somewhere with the regex idea.

Btw, I created a quick prototype with sed and found that the diag strings aren't unique -- which isn't surprising since there's no requirement for that. In fact, 23 of them are just "%0".

I suppose you could add a breakpoint for multiple values.

utils/debug-diag.py

+#!/usr/bin/env python
+
+# This tool allows you to find a backtrace for a reported diagnostic in Clang.
+#
+# To use:
+#  1) Ensure that diagtool is compiled and is up-to-date
+#  2) Invoke the tool:
+#       debug-diag warn_some_warning /path/to/clang -- -cc1 myfile.cpp
+
+import os
+import subprocess
+import sys
+import tempfile
+
+def invokeLLDB(diagCode, clang, args):
+    # Set a breakpoint at the diagnostic
+    command = """breakpoint set -n DiagnosticsEngine::Report
+breakpoint modify -c "DiagID == %d"
+run
+bt""" % (diagCode)
+
+    filename = ""
+    with tempfile.NamedTemporaryFile(delete=False) as f:
+        f.write(command)
+        filename = f.name
+        f.close()
+
+    p = None
+    try:
+        p = subprocess.Popen(["lldb","-s",f.name, clang,"--"] + args)
+        p.wait()
+    except KeyboardInterrupt:
+        print  >>sys.stderr, 'Killing LLDB.'
+        p.terminate()
+        os.unlink(filename)
+    except:
+        os.unlink(filename)
+        raise
+
+def main():
+    import argparse
+
+    description = "Runs clang in a debugger and stops at a breakpoint when the given diagnostic is reported"
+    parser = argparse.ArgumentParser(description=description)
+    parser.add_argument("diag", metavar="diagnostic", nargs=1,
+                        help="name of the diagnostic")
+    parser.add_argument("clang", metavar="clang", nargs=1,
+                        help="path to clang")
+    parser.add_argument("arguments", metavar="arg", nargs="+",
+                        help="command line arguments that should be passed to clang")
+    args = parser.parse_args()
+
+    if args.arguments[0] != "-cc1":
+        # Clang must run in -cc1 to avoid the fork which breaks debugging.
+        # FIXME: Invoke the driver and figure out the -cc1 options.
+        print >>sys.stderr, "The '-cc1' option should be passed to clang"
+        sys.exit(1)
+
+    # Compute the diagnostic code for the given diagnostic.
+    # FIXME: Diagtool binary might have out-of-date ids, when clang's
+    # diagnostics are modified and clang is rebuilt but diagtool wasn't. The
+    # script should try to identify this issue.
+    diagtool = os.path.join(os.path.dirname(args.clang[0]), "diagtool")
+    p = subprocess.Popen([diagtool,'find-diagnostic-id',args.diag[0]],
+                         stdin=subprocess.PIPE,
+                         stdout=subprocess.PIPE)
+    out,_ = p.communicate()
+    diagCode = None
+    try:
+        diagCode = int(out)
+    except ValueError:
+        # diag-tool will report to stderr.
+        sys.exit(1)
+
+    # Use LLDB to run clang and stop at the diagnostic.
+    invokeLLDB(diagCode, args.clang[0], args.arguments)
+
+if __name__ == '__main__':
+    main()