diff options
Diffstat (limited to 'lldb')
| -rw-r--r-- | lldb/examples/python/cmdtemplate.py | 49 | ||||
| -rwxr-xr-x | lldb/www/build.html | 2 | ||||
| -rwxr-xr-x | lldb/www/customization.html | 2 | ||||
| -rwxr-xr-x | lldb/www/download.html | 2 | ||||
| -rwxr-xr-x | lldb/www/features.html | 2 | ||||
| -rwxr-xr-x | lldb/www/formats.html | 2 | ||||
| -rwxr-xr-x | lldb/www/python-faq.html | 421 | ||||
| -rw-r--r-- | lldb/www/sidebar.incl | 2 |
8 files changed, 477 insertions, 5 deletions
diff --git a/lldb/examples/python/cmdtemplate.py b/lldb/examples/python/cmdtemplate.py new file mode 100644 index 00000000000..12192e9b916 --- /dev/null +++ b/lldb/examples/python/cmdtemplate.py @@ -0,0 +1,49 @@ +#!/usr/bin/python + +#---------------------------------------------------------------------- +# Be sure to add the python path that points to the LLDB shared library. +# +# To use this in the embedded python interpreter using "lldb": +# % cd /path/containing/cmdtemplate.py +# % lldb +# (lldb) script import cmdtemplate +# +# For the shells csh, tcsh: +# ( setenv PYTHONPATH /path/to/LLDB.framework/Resources/Python ; ./cmdtemplate.py ) +# +# For the shells sh, bash: +# PYTHONPATH=/path/to/LLDB.framework/Resources/Python ./cmdtemplate.py +#---------------------------------------------------------------------- + +import lldb +import commands +import optparse +import shlex + +def ls(debugger, command, result, dict): + command_args = shlex.split(command) + usage = "usage: %prog [options] <PATH> [PATH ...]" + description='''This command lets you run the /bin/ls command from within lldb as a quick and easy example.''' + parser = optparse.OptionParser(description=description, prog='ls',usage=usage) + parser.add_option('-v', '--verbose', action='store_true', dest='verbose', help='display verbose debug info', default=False) + try: + (options, args) = parser.parse_args(command_args) + except: + return + + for arg in args: + if options.verbose: + print commands.getoutput('/bin/ls "%s"' % arg) + else: + print commands.getoutput('/bin/ls -lAF "%s"' % arg) + +if __name__ == '__main__': + # This script is being run from the command line, create a debugger in case we are + # going to use any debugger functions in our function. + lldb.debugger = lldb.SBDebugger.Create() + ls (sys.argv) +elif lldb.debugger: + # This script is being run from LLDB in the emabedded command interpreter + # Add any commands contained in this module to LLDB + lldb.debugger.HandleCommand('command script add -f cmdtemplate.ls ls') + print '"ls" command installed, type "ls --help" for detailed help' diff --git a/lldb/www/build.html b/lldb/www/build.html index 67980a2fb60..e5ba6f5ff57 100755 --- a/lldb/www/build.html +++ b/lldb/www/build.html @@ -3,7 +3,7 @@ <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link href="style.css" rel="stylesheet" type="text/css" />
-<title>LLDB FAQ</title>
+<title>Building LLDB</title>
</head>
<body>
diff --git a/lldb/www/customization.html b/lldb/www/customization.html index cf50b760f71..b61c716dd21 100755 --- a/lldb/www/customization.html +++ b/lldb/www/customization.html @@ -3,7 +3,7 @@ <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link href="style.css" rel="stylesheet" type="text/css" />
-<title>Customization</title>
+<title>LLDB Customization</title>
</head>
<body>
diff --git a/lldb/www/download.html b/lldb/www/download.html index 47bf34fabb1..9ccc23f7fee 100755 --- a/lldb/www/download.html +++ b/lldb/www/download.html @@ -3,7 +3,7 @@ <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link href="style.css" rel="stylesheet" type="text/css" />
-<title>LLDB FAQ</title>
+<title>Downloading LLDB Sources</title>
</head>
<body>
diff --git a/lldb/www/features.html b/lldb/www/features.html index bd4906fdc32..7beb8f11743 100755 --- a/lldb/www/features.html +++ b/lldb/www/features.html @@ -3,7 +3,7 @@ <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link href="style.css" rel="stylesheet" type="text/css" />
-<title>LLDB Homepage</title>
+<title>LLDB Features</title>
</head>
<body>
diff --git a/lldb/www/formats.html b/lldb/www/formats.html index 16d31c48133..39be8a6213f 100755 --- a/lldb/www/formats.html +++ b/lldb/www/formats.html @@ -3,7 +3,7 @@ <head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link href="style.css" rel="stylesheet" type="text/css" />
-<title>LLDB Homepage</title>
+<title>LLDB Stack and Frame Formats</title>
</head>
<body>
diff --git a/lldb/www/python-faq.html b/lldb/www/python-faq.html new file mode 100755 index 00000000000..6b319804d9f --- /dev/null +++ b/lldb/www/python-faq.html @@ -0,0 +1,421 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
+<link href="style.css" rel="stylesheet" type="text/css" />
+<title>LLDB Python FAQ</title>
+</head>
+
+<body>
+ <div class="www_title">
+ LLDB Python FAQ
+ </div>
+
+<div id="container">
+ <div id="content">
+ <!--#include virtual="sidebar.incl"-->
+ <div id="middle">
+ <div class="post">
+ <h1 class ="postheader">Introduction</h1>
+ <div class="postcontent">
+
+ <p>The entire LLDB API is available through a script bridging interface in Python. Python can be used
+ as an embedded script interpreter, or it can be used directly from python at the command line.</p>
+
+ </div>
+ <div class="postfooter"></div>
+
+ <div class="post">
+ <h1 class ="postheader">Embedded Python Interpreter</h1>
+ <div class="postcontent">
+
+ <p>The embedded python interpreter can be accessed in a variety of way from within LLDB. The
+ easiest way is to type <b>script</b> command prompt:</p>
+<code><pre><tt>(lldb) <strong>script</strong>
+Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
+>>> 2+3
+5
+>>> hex(12345)
+'0x3039'
+>>>
+</tt></pre></code>
+
+ <p>This drops you into the embedded python interpreter. There are a some convenience variables
+ that are set for you in the <b>lldb</b> python module that refer to the current program
+ and debugger state:</p>
+ <table class="stats" width="620" cellspacing="0">
+ <tr>
+ <td class="hed" width="20%">Variable</td>
+ <td class="hed" width="10%">Type</td>
+ <td class="hed" width="70%">Description</td>
+ </tr>
+
+ <tr>
+ <td class="content">
+ <b>lldb.debugger</b>
+ </td>
+ <td class="content">
+ <b>lldb.SBDebugger</b>
+ </td>
+ <td class="content">
+ A module global variable containing the current debugger object.
+ The type is a <b>lldb.SBDebugger</b> object and it contains a reference to the debegger
+ object that owns the command interpreter and all targets in your debug session.
+ </td>
+ </tr>
+ <tr>
+ <td class="content">
+ <b>lldb.target</b>
+ </td>
+ <td class="content">
+ <b>lldb.SBTarget</b>
+ </td>
+ <td class="content">
+ A module global variable containing the currently selected target.
+ The type is a <b>lldb.SBTarget</b> object and the object will only be valid if there is a current target.
+ The <b>target select <target-index></b> commmand can be used to change the
+ currently selected target.
+ </td>
+ </tr>
+ <tr>
+ <td class="content">
+ <b>lldb.process</b>
+ </td>
+ <td class="content">
+ <b>lldb.SBProcess</b>
+ </td>
+ <td class="content">
+ A module global variable containing the current process.
+ The type is a <b>lldb.SBProcess</b> object and the object will only be
+ valid if there is a current target and that target has a process.
+ </td>
+ </tr>
+ <tr>
+ <td class="content">
+ <b>lldb.thread</b>
+ </td>
+ <td class="content">
+ <b>lldb.SBThread</b>
+ </td>
+ <td class="content">
+ A module global variable containing the current thread.
+ The type is a <b>lldb.SBThread</b> object and the object will only be valid if
+ the process has threads, and if the process has a thread selected.
+ A thread is always selected in the command interpreter when a target stops.
+ The <b>thread select <thread-index></b> commmand can be used to change the
+ currently selected thread.
+ </td>
+ </tr>
+ <tr>
+ <td class="content">
+ <b>lldb.frame</b>
+ </td>
+ <td class="content">
+ <b>lldb.SBFrame</b>
+ </td>
+ <td class="content">
+ A module global variable containing the current stack frame.
+ The type is a <b>lldb.SBFrame</b> object and the object will only be valid if
+ the thread is stopped and has a frame selected.
+ A stack frame is always selected in the command interpreter when a target stops.
+ The <b>frame select <frame-index></b> commmand can be used to change the
+ currently selected thread.
+ </td>
+ </tr>
+ </table>
+
+ <p>One in the embedded interpreter, these objects can be used. Almost all of the <b>lldb.SB</b> objects
+ are able to briefly describe themselves by printing them:
+<code><pre><tt>(lldb) <b>script</b>
+Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
+>>> <strong>print lldb.debugger</strong>
+Debugger (instance: "debugger_1", id: 1)
+>>> <strong>print lldb.target</strong>
+a.out
+>>> <strong>print lldb.process</strong>
+SBProcess: pid = 59289, state = stopped, threads = 1, executable = a.out
+>>> <strong>print lldb.thread</strong>
+SBThread: tid = 0x1f03
+>>> <strong>print lldb.frame</strong>
+frame #0: 0x0000000100000bb6 a.out main + 54 at main.c:16
+</tt></pre></code>
+
+ </div>
+ <div class="postfooter"></div>
+
+ </div>
+ <div class="post">
+ <h1 class ="postheader">Running a Python script when a breakpoint gets hit</h1>
+ <div class="postcontent">
+
+ <p>A python script can be run when a breakpoint gets hit. Adding python
+ scripts to breakpoints provides a way to create complex breakpoint
+ conditions and also allows for smart logging and data gathering.</p>
+ <p>A python function gets run when a breakpoint, and this function has
+ two arguments:</p>
+ <p>
+<code><pre><tt>def breakpoint_function(<b>frame</b>, <b>bp_loc</b>):
+ <font color=green># Your code goes here</font>
+</tt></pre></code>
+ <p><table class="stats" width="620" cellspacing="0">
+ <tr>
+ <td class="hed" width="10%">Argument</td>
+ <td class="hed" width="10%">Type</td>
+ <td class="hed" width="80%">Description</td>
+ </tr>
+
+ <tr>
+ <td class="content">
+ <b>frame</b>
+ </td>
+ <td class="content">
+ <b>lldb.SBFrame</b>
+ </td>
+ <td class="content">
+ The current stack frame where the breakpoint got hit.
+ The type is a <b>lldb.SBFrame</b> object and the object will always be valid.
+ This <b>frame</b> argument might <i>not</i> match the currently selected stack frame found in the <b>lldb</b> module global variable <b>lldb.frame</b>.
+ </td>
+ </tr>
+ <tr>
+ <td class="content">
+ <b>bp_loc</b>
+ </td>
+ <td class="content">
+ <b>lldb.SBBreakpointLocation</b>
+ </td>
+ <td class="content">
+ The breakpoint location that just got hit. Breakpoints are represented by <b>lldb.SBBreakpoint</b>
+ objects. These breakpoint objects can have one or more locations. These locations
+ are represented by <b>lldb.SBBreakpointLocation</b> objects.
+ </td>
+ </tr>
+ </table>
+ <p>Now we are ready to create a python function and attach it to a breakpoint. The following example will wllow you to
+ create an order file for a shared library. We do this by setting a regular exprsssion breakpoint
+ at every function in a shared library. The regular expression we will use is '.' which will match
+ any function that has at least any character in the function name.
+ This will result in one <b>lldb.SBBreakpoint</b> object
+ that contains many <b>lldb.SBBreakpointLocation</b> objects. As the breakpoint continually gets
+ hit, we use the hit count on the main <b>lldb.SBBreakpoint</b> to tell us the breakpoint hit
+ number, and we disable the location (not the main breakpoint) on the <b>lldb.SBBreakpointLocation</b>
+ object. Then we log some info and continue the process.
+<code><pre><tt>(lldb) <strong>breakpoint set --func-regex=. --shlib=libfoo.dylib</strong>
+Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223
+(lldb) <strong>breakpoint command add --script-type python 1</strong>
+Enter your Python command(s). Type 'DONE' to end.
+> <font color=green># Get the hit count of the main breakpoint</font>
+> <strong>hit_count = bp_loc.GetBreakpoint().GetHitCount()</strong>
+> <font color=green># Get the name of the function</font>
+> <strong>name = frame.GetFunctionName()</strong>
+> <font color=green># Print the order and the function name</font>
+> <strong>print '[%i] %s' % (hit_count, name)</strong>
+> <font color=green># Disable the current breakpoint location so it doesn't get hit again</font>
+> <strong>bp_loc.SetEnabled(False)</strong>
+> <font color=green># How continue the process</font>
+> <strong>frame.GetThread().GetProcess().Continue()</strong>
+> <strong>DONE</strong>
+</tt></pre></code>
+ <p>The <b>breakpoint command add</b> command above attaches a python script to breakpoint 1.
+ To remove the breakpoint command:
+ <p><code>(lldb) <strong>breakpoint command delete 1</strong></code>
+ </div>
+ </div>
+ <div class="post">
+ <h1 class ="postheader">Create a new LLDB command using a python function</h1>
+ <div class="postcontent">
+
+ <p>Python functions can be used to create new commands that the LLDB command interpreter
+ doesn't have. This provides a very flexible and easy way to extend LLDB to meet your
+ debugging requirements. </p>
+ <p>A python function that implements a new LDB command has four arguments:</p>
+ <p>
+ def Symbolicate(debugger, command, result, dict):
+ SymbolicateCrashLog (command.split())
+
+ <code><pre><tt>def command_function(<b>debugger</b>, <b>command</b>, <b>result</b>, <b>dict</b>):
+ <font color=green># Your code goes here</font>
+ </tt></pre></code>
+ <p><table class="stats" width="620" cellspacing="0">
+ <tr>
+ <td class="hed" width="10%">Argument</td>
+ <td class="hed" width="10%">Type</td>
+ <td class="hed" width="80%">Description</td>
+ </tr>
+
+ <tr>
+ <td class="content">
+ <b>debugger</b>
+ </td>
+ <td class="content">
+ <b>lldb.SBDebugger</b>
+ </td>
+ <td class="content">
+ The current debugger object.
+ </td>
+ </tr>
+ <tr>
+ <td class="content">
+ <b>command</b>
+ </td>
+ <td class="content">
+ <b>python string</b>
+ </td>
+ <td class="content">
+ A python string containing all arguments for your command. If you need to chop up the arguments
+ try using the <b>shlex</b> module's <code>shlex.split(command)</code> to properly extract the
+ arguments.
+ </td>
+ </tr>
+ <tr>
+ <td class="content">
+ <b>result</b>
+ </td>
+ <td class="content">
+ <b>lldb.SBCommandReturnObject</b>
+ </td>
+ <td class="content">
+ A return object where you can indicate the success or failure of your command. You can also
+ provide information for the command result by printing data into it. You can also just print
+ data as you normally would in a python script and the outout will show up.
+ </td>
+ </tr>
+ <tr>
+ <td class="content">
+ <b>dict</b>
+ </td>
+ <td class="content">
+ <b>python dict object</b>
+ </td>
+ <td class="content">
+ The dictionary for the current embedded script session which contains all variables
+ and functions.
+ </td>
+ </tr>
+ </table>
+ <p>Now we can create a module called <b>ls.py</b> that will implement a function that
+ can be used by LLDB's python command code:</p>
+
+<code><pre><tt><font color=green>#!/usr/bin/python</font>
+
+import lldb
+import commands
+import optparse
+import shlex
+
+def ls(debugger, command, result, dict):
+ print commands.getoutput('/bin/ls %s' % command)
+
+<font color=green># Any code that isn't in a function in python gets run when the module is loaded</font>
+if lldb.debugger:
+ <font color=green># This script is being run from LLDB in the emabedded command interpreter
+ # lets register the 'ls' command with the command interpreter automatically!</font>
+ lldb.debugger.HandleCommand('command script add -f ls.ls ls')
+ print 'The "ls" python command has been installed and is ready for use.'
+</tt></pre></code>
+ <p>Now we can load the module into LLDB and use it</p>
+<code><pre><tt>% lldb
+(lldb) <strong>script import ls</strong>
+The "ls" python command has been installed and is ready for use.
+(lldb) <strong>ls -l /tmp/</strong>
+total 365848
+-rw-r--r--@ 1 someuser wheel 6148 Jan 19 17:27 .DS_Store
+-rw------- 1 someuser wheel 7331 Jan 19 15:37 crash.log
+</tt></pre></code>
+ <p>A template has been created in the source repository that can help you to create
+ lldb command quickly:</p>
+ <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/python/cmdtemplate.py">cmdtemplate.py</a>
+ </div>
+ <div class="post">
+ <h1 class ="postheader">Using the lldb.py module in python</h1>
+ <div class="postcontent">
+
+ <p>LLDB has all of its core code build into a shared library which gets
+ used by the <b>lldb</b> command line application. On Mac OS X this
+ shared library is a framework: <b>LLDB.framework</b> and on other
+ unix variants the program is a shared library <b>lldb.so</b>. The
+ <b>LLDB.framework</b> contains the <b>lldb.py</b> module and you will
+ need to tell python where to look in order to find this module. This
+ is done by setting the <b>PYTHONPATH</b> environment variable contain
+ a path to the directory that contains the <b>lldb.py</b> python module:
+
+ <p>For csh and tcsh:</p>
+ <p><code>% <b>setenv PYTHONPATH /Developer/Library/PrivateFrameworks/LLDB.framework/Resources/Python</b></code></p>
+ <p>For sh and bash:
+ <p><code>% <b>export PYTHONPATH=/Developer/Library/PrivateFrameworks/LLDB.framework/Resources/Python</b></code></p>
+
+ <p>
+ Now your python scripts are ready to import the lldb module. Below is a
+ python script that will launch a program from the current working directory
+ called "a.out", set a breakpoint at "main", and then run and hit the breakpoint,
+ and print the process, thread and frame objects if the process stopped:
+
+ </p>
+<code><pre><tt><font color=green>#!/usr/bin/python</font>
+
+import lldb
+
+<font color=green># Set the path to the executable to debug</font>
+exe = "./a.out"
+
+<font color=green># Create a new debugger instance</font>
+debugger = lldb.SBDebugger.Create()
+
+<font color=green># When we step or continue, don't return from the function until the process
+# stops. We do this by setting the async mode to false.</font>
+debugger.SetAsync (False)
+
+<font color=green># Create a target from a file and arch</font>
+print "Creating a target for '%s'" % exe
+
+target = debugger.CreateTargetWithFileAndArch (exe, lldb.LLDB_ARCH_DEFAULT)
+
+if target:
+ <font color=green># If the target is valid set a breakpoint at main</font>
+ main_bp = target.BreakpointCreateByName ("main", target.GetExecutable().GetFilename());
+
+ print main_bp
+
+ <font color=green># Launch the process. Since we specified synchronous mode, we won't return
+ # from this function until we hit the breakpoint at main</font>
+ process = target.LaunchSimple (None, None, os.getcwd())
+
+ <font color=green># Make sure the launch went ok</font>
+ if process:
+ <font color=green># Print some simple process info</font>
+ state = process.GetState ()
+ print process
+ if state == lldb.eStateStopped:
+ <font color=green># Get the first thread</font>
+ thread = process.GetThreadAtIndex (0)
+ if thread:
+ <font color=green># Print some simple thread info</font>
+ print thread
+ <font color=green># Get the first frame</font>
+ frame = thread.GetFrameAtIndex (0)
+ if frame:
+ <font color=green># Print some simple frame info</font>
+ print frame
+ function = frame.GetFunction()
+ <font color=green># See if we have debug info (a function)</font>
+ if function:
+ <font color=green># We do have a function, print some info for the function</font>
+ print function
+ <font color=green># Now get all instructions for this function and print them</font>
+ insts = function.GetInstructions(target)
+ disassemble_instructions (insts)
+ else:
+ <font color=green># See if we have a symbol in the symbol table for where we stopped</font>
+ symbol = frame.GetSymbol();
+ if symbol:
+ <font color=green># We do have a symbol, print some info for the symbol</font>
+ print symbol
+</tt></pre></code>
+ </div>
+ <div class="postfooter"></div>
+
+ </div>
+ </div>
+</div>
+</body>
+</html>
diff --git a/lldb/www/sidebar.incl b/lldb/www/sidebar.incl index 22ef2af0c7b..b36da7d9201 100644 --- a/lldb/www/sidebar.incl +++ b/lldb/www/sidebar.incl @@ -20,8 +20,10 @@ <li><a href="faq.html">FAQ</a></li> <li><a href="formats.html">Frame and Thread Formatting</a></li> <li><a href="lldb-gdb.html">LLDB and GDB</a></li> + <li><a href="python-faq.html">Python FAQ</a></li> <li><a href="scripting.html">Python Scripting</a></li> <li><a href="tutorial.html">Tutorial</a></li> + <li><a href="varformats.html">Variable Formatting</a></li> </ul> </div> </div> |
