[Lldb-commits] [lldb] r148769 - in /lldb/trunk/www: python-faq.html python-reference.html sidebar.incl
Jim Ingham
jingham at apple.com
Mon Jan 23 18:44:08 PST 2012
Author: jingham
Date: Mon Jan 23 20:44:07 2012
New Revision: 148769
URL: http://llvm.org/viewvc/llvm-project?rev=148769&view=rev
Log:
Better name for the python reference.
Added:
lldb/trunk/www/python-reference.html
- copied unchanged from r148768, lldb/trunk/www/python-faq.html
Removed:
lldb/trunk/www/python-faq.html
Modified:
lldb/trunk/www/sidebar.incl
Removed: lldb/trunk/www/python-faq.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/python-faq.html?rev=148768&view=auto
==============================================================================
--- lldb/trunk/www/python-faq.html (original)
+++ lldb/trunk/www/python-faq.html (removed)
@@ -1,457 +0,0 @@
-<!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 as Python functions through a script bridging interface.
- This means the LLDB API's can be used directly from python either interactively or to build python apps that
- provide debugger features. </p>
- <p>Additionally, Python can be used as a programmatic interface within the
- lldb command interpreter (we refer to this for brevity as the embedded interpreter). Of course,
- in this context it has full access to the LLDB API - with some additional conveniences we will
- call out in the FAQ.</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 ways from within LLDB. The
- easiest way is to use the lldb command <b>script</b> with no arguments at the lldb 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. When running under the <b>script</b> command,
- lldb sets some convenience variables that give you quick access to the currently selected entities that characterize
- the program and debugger state. In each case, if there is no currently selected entity of the appropriate
- type, the variable's <b>IsValid</b> method will return false.
- <p>Note also, these variables hold the values
- of the selected objects on entry to the embedded interpreter. They do not update as you use the LLDB
- API's to change, for example, the currently selected stack frame or thread.</p>
- These are all global variables contained in the <b>lldb</b> python namespace :</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">
- Contains the debugger object whose <b>script</b> command was invoked.
- The <b>lldb.SBDebugger</b> object owns the command interpreter
- and all the targets in your debug session. There will always be a
- Debugger in the embedded interpreter.
- </td>
- </tr>
- <tr>
- <td class="content">
- <b>lldb.target</b>
- </td>
- <td class="content">
- <b>lldb.SBTarget</b>
- </td>
- <td class="content">
- Contains the currently selected target - for instance the one made with the
- <b>file</b> or selected by the <b>target select <target-index></b> command.
- The <b>lldb.SBTarget</b> manages one running process, and all the executable
- and debug files for the process.
- </td>
- </tr>
- <tr>
- <td class="content">
- <b>lldb.process</b>
- </td>
- <td class="content">
- <b>lldb.SBProcess</b>
- </td>
- <td class="content">
- Contains the process of the currently selected target.
- The <b>lldb.SBProcess</b> object manages the threads and allows access to
- memory for the process.
- </td>
- </tr>
- <tr>
- <td class="content">
- <b>lldb.thread</b>
- </td>
- <td class="content">
- <b>lldb.SBThread</b>
- </td>
- <td class="content">
- Contains the currently selected thread.
- The <b>lldb.SBThread</b> object manages the stack frames in that thread.
- 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. So as long as you have a stopped process, there will be
- some selected thread.
- </td>
- </tr>
- <tr>
- <td class="content">
- <b>lldb.frame</b>
- </td>
- <td class="content">
- <b>lldb.SBFrame</b>
- </td>
- <td class="content">
- Contains the currently selected stack frame.
- The <b>lldb.SBFrame</b> object manage the stack locals and the register set for
- that stack.
- 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 frame. So as long as you have a stopped process, there will
- be some selected frame.
- </td>
- </tr>
- </table>
-
- <p>Once in the embedded interpreter, these objects can be used. To get started, note that almost
- all of the <b>lldb</b> Python objects are able to briefly describe themselves when you pass them
- to the Python <b>print</b> function:
-<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>One very powerful use of the lldb Python API is to have a python script 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>When your process hits a breakpoint to which you have attached some python code, the code is executed as the
- body of a function which takes two arguments:</p>
- <p>
-<code><pre><tt>def breakpoint_function_wrapper(<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 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>An example will show how simple it is to write some python code and attach it to a breakpoint.
- The following example will allow you to track the order in which the functions in a given shared library
- are first executed during one run of your program. This is a simple method to gather an order file which
- can be used to optimize function placement within a binary for execution locality.</p>
- <p>We do this by setting a regular expression breakpoint
- that will match every function in the shared library. The regular expression '.' will match
- any string that has at least one character in it, so we will use that.
- This will result in one <b>lldb.SBBreakpoint</b> object
- that contains an <b>lldb.SBBreakpointLocation</b> object for each function. As the breakpoint gets
- hit, we use a counter to track the order in which the function at this particular breakpoint location got hit.
- Since our code is passed the location that was hit, we can get the name of the function from the location,
- disable the location so we won't count this function again; then log some info and continue the process.</p>
- <p>Note we also have to initialize our counter, which we do with the simple one-line version of the <b>script</b>
- command.
- <p>Here is the code:
-
-<code><pre><tt>(lldb) <strong>breakpoint set --func-regex=. --shlib=libfoo.dylib</strong>
-Breakpoint created: 1: regex = '.', module = libfoo.dylib, locations = 223
-(lldb) <strong>script counter = 0</strong>
-(lldb) <strong>breakpoint command add --script-type python 1</strong>
-Enter your Python command(s). Type 'DONE' to end.
-> <font color=green># Increment our counter. Since we are in a function, this must be a global python variable</font>
-> <strong>global counter</strong>
-> <strong>counter += 1</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' % (counter, 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 LLDB command interpreter commands, which will work
- like all the natively defined lldb commands. This provides a very flexible and easy way to extend LLDB to meet your
- debugging requirements. </p>
- <p>To write a python function that implements a new LDB command define the function to take four arguments as follows:</p>
-
- <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 output will show up; this is useful for
- logging, but the real output for your command should go in the result object.
- </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>One other handy convenience when defining lldb command-line commands is the command
- <b>command script import</b> which will import a module specified by file path - so you
- don't have to change your PYTHONPATH for temporary scripts. It also has another convenience
- that if your new script module has a function of the form:</p>
-
- <code><pre><tt>def __lldb_module_init(<b>debugger</b>, <b>dict</b>):
- <font color=green># Command Initialization code goes here</font>
- </tt></pre></code>
-
- <p>where <b>debugger</b> and <b>dict</b> are as above, that function will get run when the module is loaded
- allowing you to add whatever commands you want into the current debugger.</p>
- <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):
- result.PutCString(commands.getoutput('/bin/ls %s' % command))
-
-<font color=green># And the initialization code to add your commands </font>
-def __lldb_module_init(debugger, dict):
- 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>command 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>. LLDB also
- provides an lldb.py module that contains the bindings from LLDB into Python.
- To use the
- <b>LLDB.framework</b> to create your own stand-alone python programs, 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, adding
- a path to the directory that contains the <b>lldb.py</b> python module. On
- Mac OS X, this is contained inside the LLDB.framework, so you would do:
-
- <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> Alternately, you can append the LLDB Python directory to the <b>sys.path</b> list directly in
- your Python code before importing the lldb module.</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. Otherwise we would have to handle the process events ourselves which, while doable is
-#a little tricky. 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>
Modified: lldb/trunk/www/sidebar.incl
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/sidebar.incl?rev=148769&r1=148768&r2=148769&view=diff
==============================================================================
--- lldb/trunk/www/sidebar.incl (original)
+++ lldb/trunk/www/sidebar.incl Mon Jan 23 20:44:07 2012
@@ -20,7 +20,7 @@
<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="python-reference.html">Python Reference</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>
More information about the lldb-commits
mailing list