[lldb] Add long help to `crashlog`

[kastiglione]

Summary

Convert the crashlog command to be implemented as a class. The Symbolicate
function is switched to a class, to implement get_long_help. The text for the
long help comes from the help output generated by OptionParser. That is, the
output of help crashlog is the same as crashlog --help.

[kastiglione]

The output of help crashlog is:

(lldb) help crashlog 
For more information run 'help crashlog'  Expects 'raw' input (see 'help raw-input'.)

Syntax: crashlog
Usage: crashlog [options] <FILE> [FILE ...]

Symbolicate one or more darwin crash log files to provide source file and line
information, inlined stack frames back to the concrete functions, and
disassemble the location of the crash for the first frame of the crashed
thread. If this script is imported into the LLDB command interpreter, a
"crashlog" command will be added to the interpreter for use at the LLDB
command line. After a crash log has been parsed and symbolicated, a target
will have been created that has all of the shared libraries loaded at the load
addresses found in the crash log file. This allows you to explore the program
as if it were stopped at the locations described in the crash log and
functions can be disassembled and lookups can be performed using the addresses
found in the crash log.

Options:
  -h, --help            show this help message and exit
  -v, --verbose         display verbose debug info
  -g, --debug           display verbose debug logging
  -a, --load-all        load all executable images, not just the images found
                        in the crashed stack frames
  --images              show image list
  --debug-delay=NSEC    pause for NSEC seconds for debugger
  -c, --crashed-only    only symbolicate the crashed thread
  -d DISASSEMBLE_DEPTH, --disasm-depth=DISASSEMBLE_DEPTH
                        set the depth in stack frames that should be
                        disassembled (default is 1)
  -D, --disasm-all      enabled disassembly of frames on all threads (not just
                        the crashed thread)
  -B DISASSEMBLE_BEFORE, --disasm-before=DISASSEMBLE_BEFORE
                        the number of instructions to disassemble before the
                        frame PC
  -A DISASSEMBLE_AFTER, --disasm-after=DISASSEMBLE_AFTER
                        the number of instructions to disassemble after the
                        frame PC
  -C NLINES, --source-context=NLINES
                        show NLINES source lines of source context (default =
                        4)
  --source-frames=NFRAMES
                        show source for NFRAMES (default = 4)
  --source-all          show source for all threads, not just the crashed
                        thread
  -i, --interactive     parse all crash logs and enter interactive mode

[kastiglione]

refer to the debugger parameter, not lldb.debugger

[kastiglione]

lldb/examples/python/crashlog.py

1240–1244

Note that I introduced __lldb_init_module here because there's some bug when registering a command class using lldb.debugger. In other words, this failed:

lldb.debugger.HandleCommand('command script add -c mod.Command cmd')

and this succeeds:

def __lldb_init_module(debugger, _):
    debugger.HandleCommand('command script add -c mod.Command cmd')

When using the first form, an error would happen when running the command. The error message is "no function to execute".

[jingham]

lldb/examples/python/crashlog.py

1240–1244

That makes sense. All of the "lldb.{debugger, target, process, thread, etc}" variables are only set when entering the interactive script interpreter. They don't get set when processing "command script import". So lldb.debugger would have been None here.

In general, since pretty much no python we write in the lldb project is going to run in the interactive interpreter, you should never use those lldb.etc variables.

I actually think we could make the lldb.debugger work, since that really is a singleton for the command interpreter, but it seems much better form to pass debugger directly to whoever needs it, so for the sake of clarity they all get unset when we leave the interactive script interpreter.

[jingham]

Oops, forgot to include the "why requesting changes..."

Can you see if also adding a "get_short_help" gets rid of that dopey:

For more information run 'help crashlog'  Expects 'raw' input (see 'help raw-input'.)

line? It's getting added as the placeholder text in CommandObjectPythonObject & CommandObjectPythonFunction. It is not a very good place holder, but anyway having the short help is good for "apropos" listings and the like. And if those classes are doing the right thing, an actual short help should override the placeholder.

[jingham]

If adding the short help doesn't fix this, I'm fine with this change as is. We can go down the getting rid of that placeholder rabbit hole at some other time.

[kastiglione]

Add get_short_help, and add missing changes that should have been part of original diff.

[kastiglione]

Can you see if also adding a "get_short_help" gets rid of that dopey:

Good call, it worked.

[kastiglione]

lldb/examples/python/crashlog.py

1240–1244

Yes I've come to learn to avoid "lldb.{debugger, target, process, thread, etc}" at all costs, which is how I was able to get past the strange error message.

So lldb.debugger would have been None here.

It wasn't, which made things trickier to understand.

Also note that the docs recommend this idiom used here in crashlog.py. Look for if __name__ == '__main__' in https://lldb.llvm.org/use/python-reference.html#create-a-new-lldb-command-using-a-python-function.

[jingham]

LGTM

[JDevlieghere]

Nice!

lldb/examples/python/crashlog.py

if target:
                          module_version,
                          module.GetUUIDString(),
                          module.file.fullpath))
         out_file.close()
     else:
         result.PutCString("error: invalid target")
 
 
-def Symbolicate(debugger, command, result, dict):
+class Symbolicate:
+    def __call__(self, debugger, command, exe_ctx, result):
         try:
             SymbolicateCrashLogs(debugger, shlex.split(command))
         except Exception as e:
             result.PutCString("error: python exception: %s" % e)
 
+    def get_long_help(self):
+        option_parser = CrashLogOptionParser()
+        return option_parser.get_usage()
+
 
 def SymbolicateCrashLog(crash_log, options):
     if options.debug:
         crash_log.dump()
     if not crash_log.images:
         print('error: no images in crash log')
         return
 
if add_interactive_options:
             '-i',
             '--interactive',
             action='store_true',
             help='parse all crash logs and enter interactive mode',
             default=False)
     return option_parser
 
 
-def SymbolicateCrashLogs(debugger, command_args):
+def CrashLogOptionParser():
     description = '''Symbolicate one or more darwin crash log files to provide source file and line information,
 inlined stack frames back to the concrete functions, and disassemble the location of the crash
 for the first frame of the crashed thread.
 If this script is imported into the LLDB command interpreter, a "crashlog" command will be added to the interpreter
 for use at the LLDB command line. After a crash log has been parsed and symbolicated, a target will have been
 created that has all of the shared libraries loaded at the load addresses found in the crash log file. This allows
 you to explore the program as if it were stopped at the locations described in the crash log and functions can
 be disassembled and lookups can be performed using the addresses found in the crash log.'''
-    option_parser = CreateSymbolicateCrashLogOptions(
-        'crashlog', description, True)
+    return CreateSymbolicateCrashLogOptions('crashlog', description, True)
+
+def SymbolicateCrashLogs(debugger, command_args):
+    option_parser = CrashLogOptionParser()
     try:
         (options, args) = option_parser.parse_args(command_args)
     except:
         return
 
     if options.debug:
         print('command_args = %s' % command_args)
         print('options', options)
         print('args', args)
 
     if options.debug_delay > 0:
         print("Waiting %u seconds for debugger to attach..." % options.debug_delay)
         time.sleep(options.debug_delay)
     error = lldb.SBError()
 
     if args:
         if options.interactive:
             interactive_crashlogs(debugger, options, args)
         else:
             for crash_log_file in args:
                 crash_log = CrashLogParser().parse(debugger, crash_log_file, options.verbose)
                 SymbolicateCrashLog(crash_log, options)
+
 if __name__ == '__main__':
     # Create a new debugger instance
     debugger = lldb.SBDebugger.Create()
     SymbolicateCrashLogs(debugger, sys.argv[1:])
     lldb.SBDebugger.Destroy(debugger)
-elif getattr(lldb, 'debugger', None):
+
+def __lldb_init_module(debugger, internal_dict):
     lldb.debugger.HandleCommand(
-        'command script add -f lldb.macosx.crashlog.Symbolicate crashlog')
+        'command script add -c lldb.macosx.crashlog.Symbolicate crashlog')
     lldb.debugger.HandleCommand(
         'command script add -f lldb.macosx.crashlog.save_crashlog save_crashlog')