[Lldb-commits] [lldb] r148650 - in /lldb/trunk: examples/python/cmdtemplate.py www/build.html www/customization.html www/download.html www/features.html www/formats.html www/python-faq.html www/sidebar.incl
Greg Clayton
gclayton at apple.com
Sat Jan 21 18:55:09 PST 2012
Author: gclayton
Date: Sat Jan 21 20:55:08 2012
New Revision: 148650
URL: http://llvm.org/viewvc/llvm-project?rev=148650&view=rev
Log:
Added a python FAQ page with detailed examples of how to add python functions
to breakpoints, creating new LLDB commands using python modules and also how
to run scripts from the command line.
Added:
lldb/trunk/examples/python/cmdtemplate.py
lldb/trunk/www/python-faq.html (with props)
Modified:
lldb/trunk/www/build.html
lldb/trunk/www/customization.html
lldb/trunk/www/download.html
lldb/trunk/www/features.html
lldb/trunk/www/formats.html
lldb/trunk/www/sidebar.incl
Added: lldb/trunk/examples/python/cmdtemplate.py
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/examples/python/cmdtemplate.py?rev=148650&view=auto
==============================================================================
--- lldb/trunk/examples/python/cmdtemplate.py (added)
+++ lldb/trunk/examples/python/cmdtemplate.py Sat Jan 21 20:55:08 2012
@@ -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'
Modified: lldb/trunk/www/build.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/build.html?rev=148650&r1=148649&r2=148650&view=diff
==============================================================================
--- lldb/trunk/www/build.html (original)
+++ lldb/trunk/www/build.html Sat Jan 21 20:55:08 2012
@@ -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>
Modified: lldb/trunk/www/customization.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/customization.html?rev=148650&r1=148649&r2=148650&view=diff
==============================================================================
--- lldb/trunk/www/customization.html (original)
+++ lldb/trunk/www/customization.html Sat Jan 21 20:55:08 2012
@@ -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>
Modified: lldb/trunk/www/download.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/download.html?rev=148650&r1=148649&r2=148650&view=diff
==============================================================================
--- lldb/trunk/www/download.html (original)
+++ lldb/trunk/www/download.html Sat Jan 21 20:55:08 2012
@@ -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>
Modified: lldb/trunk/www/features.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/features.html?rev=148650&r1=148649&r2=148650&view=diff
==============================================================================
--- lldb/trunk/www/features.html (original)
+++ lldb/trunk/www/features.html Sat Jan 21 20:55:08 2012
@@ -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>
Modified: lldb/trunk/www/formats.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/formats.html?rev=148650&r1=148649&r2=148650&view=diff
==============================================================================
--- lldb/trunk/www/formats.html (original)
+++ lldb/trunk/www/formats.html Sat Jan 21 20:55:08 2012
@@ -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>
Added: lldb/trunk/www/python-faq.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/python-faq.html?rev=148650&view=auto
==============================================================================
--- lldb/trunk/www/python-faq.html (added)
+++ lldb/trunk/www/python-faq.html Sat Jan 21 20:55:08 2012
@@ -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>
Propchange: lldb/trunk/www/python-faq.html
------------------------------------------------------------------------------
svn:executable = *
Modified: lldb/trunk/www/sidebar.incl
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/sidebar.incl?rev=148650&r1=148649&r2=148650&view=diff
==============================================================================
--- lldb/trunk/www/sidebar.incl (original)
+++ lldb/trunk/www/sidebar.incl Sat Jan 21 20:55:08 2012
@@ -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>
More information about the lldb-commits
mailing list