1#!/usr/bin/python
2
3#----------------------------------------------------------------------
4# Be sure to add the python path that points to the LLDB shared library.
5#
6# # To use this in the embedded python interpreter using "lldb" just
7# import it with the full path using the "command script import"
8# command
9#   (lldb) command script import /path/to/cmdtemplate.py
10#----------------------------------------------------------------------
11
12import lldb
13import commands
14import optparse
15import shlex
16
17
18def create_framestats_options():
19    usage = "usage: %prog [options]"
20    description = '''This command is meant to be an example of how to make an LLDB command that
21does something useful, follows best practices, and exploits the SB API.
22Specifically, this command computes the aggregate and average size of the variables in the current frame
23and allows you to tweak exactly which variables are to be accounted in the computation.
24'''
25    parser = optparse.OptionParser(
26        description=description,
27        prog='framestats',
28        usage=usage)
29    parser.add_option(
30        '-i',
31        '--in-scope',
32        action='store_true',
33        dest='inscope',
34        help='in_scope_only = True',
35        default=False)
36    parser.add_option(
37        '-a',
38        '--arguments',
39        action='store_true',
40        dest='arguments',
41        help='arguments = True',
42        default=False)
43    parser.add_option(
44        '-l',
45        '--locals',
46        action='store_true',
47        dest='locals',
48        help='locals = True',
49        default=False)
50    parser.add_option(
51        '-s',
52        '--statics',
53        action='store_true',
54        dest='statics',
55        help='statics = True',
56        default=False)
57    return parser
58
59
60def the_framestats_command(debugger, command, result, dict):
61    # Use the Shell Lexer to properly parse up command options just like a
62    # shell would
63    command_args = shlex.split(command)
64    parser = create_framestats_options()
65    try:
66        (options, args) = parser.parse_args(command_args)
67    except:
68        # if you don't handle exceptions, passing an incorrect argument to the OptionParser will cause LLDB to exit
69        # (courtesy of OptParse dealing with argument errors by throwing SystemExit)
70        result.SetError("option parsing failed")
71        return
72
73    # in a command - the lldb.* convenience variables are not to be used
74    # and their values (if any) are undefined
75    # this is the best practice to access those objects from within a command
76    target = debugger.GetSelectedTarget()
77    process = target.GetProcess()
78    thread = process.GetSelectedThread()
79    frame = thread.GetSelectedFrame()
80    if not frame.IsValid():
81        return "no frame here"
82    # from now on, replace lldb.<thing>.whatever with <thing>.whatever
83    variables_list = frame.GetVariables(
84        options.arguments,
85        options.locals,
86        options.statics,
87        options.inscope)
88    variables_count = variables_list.GetSize()
89    if variables_count == 0:
90        print >> result, "no variables here"
91        return
92    total_size = 0
93    for i in range(0, variables_count):
94        variable = variables_list.GetValueAtIndex(i)
95        variable_type = variable.GetType()
96        total_size = total_size + variable_type.GetByteSize()
97    average_size = float(total_size) / variables_count
98    print >>result, "Your frame has %d variables. Their total size is %d bytes. The average size is %f bytes" % (
99        variables_count, total_size, average_size)
100    # not returning anything is akin to returning success
101
102
103def __lldb_init_module(debugger, dict):
104    # This initializer is being run from LLDB in the embedded command interpreter
105    # Make the options so we can generate the help text for the new LLDB
106    # command line command prior to registering it with LLDB below
107    parser = create_framestats_options()
108    the_framestats_command.__doc__ = parser.format_help()
109    # Add any commands contained in this module to LLDB
110    debugger.HandleCommand(
111        'command script add -f cmdtemplate.the_framestats_command framestats')
112    print 'The "framestats" command has been installed, type "help framestats" or "framestats --help" for detailed help.'
113