[llvm-branch-commits] [lldb] r183468 - Update platform branch with top of tree.
Greg Clayton
gclayton at apple.com
Thu Jun 6 17:08:09 PDT 2013
Modified: lldb/branches/lldb-platform-work/www/python-reference.html
URL: http://llvm.org/viewvc/llvm-project/lldb/branches/lldb-platform-work/www/python-reference.html?rev=183468&r1=183467&r2=183468&view=diff
==============================================================================
--- lldb/branches/lldb-platform-work/www/python-reference.html (original)
+++ lldb/branches/lldb-platform-work/www/python-reference.html Thu Jun 6 19:06:43 2013
@@ -96,11 +96,8 @@ Python Interactive Interpreter. To exit,
<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>
+ type, the variable's <b>IsValid</b> method will return false. These variables are:</p>
+
<table class="stats" width="620" cellspacing="0">
<tr>
<td class="hed" width="20%">Variable</td>
@@ -160,7 +157,7 @@ Python Interactive Interpreter. To exit,
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
+ The <b>thread select <thread-index></b> command 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>
@@ -177,14 +174,25 @@ Python Interactive Interpreter. To exit,
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
+ The <b>frame select <frame-index></b> command 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
+ <p>While extremely convenient, these variables have a couple caveats that you should be aware of.
+ First of all, they 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>Moreover, they are only defined and meaningful while in the interactive Python interpreter.
+ There is no guarantee on their value in any other situation, hence you should not use them when defining
+ Python formatters, breakpoint scripts and commands (or any other Python extension point that LLDB provides).
+ As a rationale for such behavior, consider that lldb can
+ run in a multithreaded environment, and another thread might call the "script" command, changing the value out
+ from under you.</p>
+
+ <p>To get started with these objects and LLDB scripting, please 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>
@@ -213,9 +221,9 @@ frame #0: 0x0000000100000bb6 a.out main
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>
+ body of a function which takes three arguments:</p>
<p>
-<code><pre><tt>def breakpoint_function_wrapper(<b>frame</b>, <b>bp_loc</b>):
+<code><pre><tt>def breakpoint_function_wrapper(<b>frame</b>, <b>bp_loc</b>, <b>dict</b>):
<font color=green># Your code goes here</font>
</tt></pre></code>
<p><table class="stats" width="620" cellspacing="0">
@@ -251,7 +259,22 @@ frame #0: 0x0000000100000bb6 a.out main
are represented by <b>lldb.SBBreakpointLocation</b> objects.
</td>
</tr>
+ <tr>
+ <td class="content">
+ <b>dict</b>
+ </td>
+ <td class="content">
+ <b>dict</b>
+ </td>
+ <td class="content">
+ The python session dictionary as a standard python dictionary object.
+ </td>
+ </tr>
</table>
+ <p>Optionally, a Python breakpoint command can return a value. Returning False tells LLDB that you do not want to stop at the breakpoint.
+ Any other return value (including None or leaving out the return statement altogether) is akin to telling LLDB to actually stop at the breakpoint.
+ This can be useful in situations where a breakpoint only needs to stop the process when certain conditions are met, and you do not want to inspect the
+ program state manually at every stop and then continue.
<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
@@ -282,8 +305,8 @@ Enter your Python command(s). Type 'DONE
> <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>
+> <font color=green># No need to stop here</font>
+> <strong>return False</strong>
> <strong>DONE</strong>
</tt></pre></code>
<p>The <b>breakpoint command add</b> command above attaches a python script to breakpoint 1.
@@ -349,10 +372,9 @@ Enter your Python command(s). Type 'DONE
<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.
+ A return object which encapsulates success/failure information for the command and output text
+ that needs to be printed as a result of the command. The plain Python "print" command also works but
+ text won't go in the result by default (it is useful as a temporary logging facility).
</td>
</tr>
<tr>
@@ -368,6 +390,10 @@ Enter your Python command(s). Type 'DONE
</td>
</tr>
</table>
+ <p>As a convenience, you can treat the result object as a Python file object, and say
+ <code><pre><tt>print >>result, "my command does lots of cool stuff"</tt></pre></code>
+ SBCommandReturnObject and SBStream
+ both support this file-like behavior by providing write() and flush() calls at the Python layer.</p>
<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
@@ -427,9 +453,42 @@ 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
+ <p>A more interesting 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>
+ <p>
+ A commonly required facility is being able to create a command that does some token substitution, and then runs a different debugger command
+ (usually, it po'es the result of an expression evaluated on its argument). For instance, given the following program:
+ <code><pre><tt>
+#import <Foundation/Foundation.h>
+NSString*
+ModifyString(NSString* src)
+{
+ return [src stringByAppendingString:@"foobar"];
+}
+
+int main()
+{
+ NSString* aString = @"Hello world";
+ NSString* anotherString = @"Let's be friends";
+ return 1;
+}
+ </tt></pre></code>
+ you may want a pofoo X command, that equates po [ModifyString(X) capitalizedString].
+ The following debugger interaction shows how to achieve that goal:
+ <code><pre><tt>
+(lldb) <b>script</b>
+Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.
+>>> <b>def pofoo_funct(debugger, command, result, internal_dict):</b>
+... <b>cmd = "po [ModifyString(" + command + ") capitalizedString]"</b>
+... <b>lldb.debugger.HandleCommand(cmd)</b>
+...
+>>> ^D
+(lldb) <b>command script add pofoo -f pofoo_funct</b>
+(lldb) <b>pofoo aString</b>
+$1 = 0x000000010010aa00 Hello Worldfoobar
+(lldb) <b>pofoo anotherString</b>
+$2 = 0x000000010010aba0 Let's Be Friendsfoobar</tt></pre></code>
</div>
<div class="post">
<h1 class ="postheader">Using the lldb.py module in python</h1>
@@ -465,6 +524,11 @@ total 365848
<code><pre><tt><font color=green>#!/usr/bin/python</font>
import lldb
+import os
+
+def disassemble_instructions(insts):
+ for i in insts:
+ print i
<font color=green># Set the path to the executable to debug</font>
exe = "./a.out"
@@ -498,30 +562,30 @@ if target:
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
+ <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>
Modified: lldb/branches/lldb-platform-work/www/sidebar.incl
URL: http://llvm.org/viewvc/llvm-project/lldb/branches/lldb-platform-work/www/sidebar.incl?rev=183468&r1=183467&r2=183468&view=diff
==============================================================================
--- lldb/branches/lldb-platform-work/www/sidebar.incl (original)
+++ lldb/branches/lldb-platform-work/www/sidebar.incl Thu Jun 6 19:06:43 2013
@@ -14,16 +14,15 @@
<div class="urbangreymenu">
<h1 class="headerbar">Use and Extension</h1>
<ul>
- <li><a href="architecture.html">Architecture</a></li>
- <li><a href="customization.html">Customization</a></li>
- <li><a href="docs.html">Documentation</a></li>
- <li><a href="faq.html">FAQ</a></li>
+ <li><a href="tutorial.html">Tutorial</a></li>
+ <li><a href="lldb-gdb.html">GDB and LLDB command examples</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="symbolication.html">Symbolication</a></li>
+ <li><a href="varformats.html">Variable Formatting</a></li>
<li><a href="python-reference.html">Python Reference</a></li>
<li><a href="scripting.html">Python Example</a></li>
- <li><a href="tutorial.html">Tutorial</a></li>
- <li><a href="varformats.html">Variable Formatting</a></li>
+ <li><a href="symbols.html">Symbols on Mac OS X</a></li>
+ <li><a href="architecture.html">Architecture</a></li>
</ul>
</div>
</div>
@@ -48,4 +47,4 @@
</ul>
</div>
</div>
-</div>
\ No newline at end of file
+</div>
Modified: lldb/branches/lldb-platform-work/www/status.html
URL: http://llvm.org/viewvc/llvm-project/lldb/branches/lldb-platform-work/www/status.html?rev=183468&r1=183467&r2=183468&view=diff
==============================================================================
--- lldb/branches/lldb-platform-work/www/status.html (original)
+++ lldb/branches/lldb-platform-work/www/status.html Thu Jun 6 19:06:43 2013
@@ -1,61 +1,175 @@
-<!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 Status</title>
-</head>
-
-<body>
- <div class="www_title">
- The <strong>LLDB</strong> Debugger
- </div>
-
-<div id="container">
- <div id="content">
- <!--#include virtual="sidebar.incl"-->
-
- <div id="middle">
- <div class="post">
- <h1 class ="postheader">Status</h1>
- <div class="postcontent">
-
- <p>LLDB has matured a lot in the last year and can be used for
- C, C++ and Objective C development for x86_64, i386 and ARM debugging.
- The entire public API is exposed though a framework on Mac OS X which
- is used by Xcode, the lldb command line tool, and can also be used by
- python. The entire public API is exposed through script bridging which
- allows LLDB to use an embedded python script interpreter, as well as
- having a python module named "lldb" which can be used from python
- on the command line. This allows debug sessions to be scripted. It also
- allows powerful debugging actions to be created and attached to a variety
- of debugging workflows.</p>
-
- <p>What works well:</p>
- <ul>
- <li>Process control, including external process control via debugserver
- (which is included as part of the lldb project)</li>
- <li>Breakpoints: Source-line, symbolic, C++ mangled names, module
- scoping</li>
- <li>Symbol reading and object file introspection</li>
- <li>Script bridging</li>
- <li>Thread inspection and stepping</li>
- <li>Disassembly of i386, x86-64, & ARM/Thumb machine code</li>
- <li>Backtracing of i386, x86-64, & ARM/Thumb machine code</li>
- <li>libedit powers the command line prompt and input
- <li>Objective-C 2.0 Support: Printing properties, synthetic properties,
- Objective-C expressions, KVO, dynamic types, dot syntax, runtime data</li>
- <li>C++ support: method access, template support, dynamic types</li>
- <li>The public API to the library</li>
- <li>Expression evaluation</li>
- <li>Objective-C support: stepping into/over, printing the description of
- an object ("po")</li>
- </ul>
- </div>
- <div class="postfooter"></div>
- </div>
- </div>
- </div>
-</div>
-</body>
-</html>
\ No newline at end of file
+<!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 Status</title>
+</head>
+
+<body>
+ <div class="www_title">
+ The <strong>LLDB</strong> Debugger
+ </div>
+
+<div id="container">
+ <div id="content">
+ <!--#include virtual="sidebar.incl"-->
+
+ <div id="middle">
+ <div class="post">
+ <h1 class ="postheader">Mac OS X Status</h1>
+ <div class="postcontent">
+
+ <p>LLDB has matured a lot in the last year and can be used for
+ C, C++ and Objective C development for x86_64, i386 and ARM debugging.
+ The entire public API is exposed though a framework on Mac OS X which
+ is used by Xcode, the lldb command line tool, and can also be used by
+ Python. The entire public API is exposed through script bridging which
+ allows LLDB to use an embedded Python script interpreter, as well as
+ having a Python module named "lldb" which can be used from Python
+ on the command line. This allows debug sessions to be scripted. It also
+ allows powerful debugging actions to be created and attached to a variety
+ of debugging workflows.</p>
+ </div>
+ <h1 class ="postheader">Linux Status</h1>
+ <div class="postcontent">
+ <p> LLDB is improving on Linux. While the debugserver is not ported
+ (to enable remote debugging) and debugging of multi-threaded programs is in its infancy, most
+ of the functionality, including the Python API and the command line tool,
+ is working on the x86_64 architecture, and partially working with i386.
+ FreeBSD is untested. ARM architectures on Linux are untested.
+ For more details, see the Features by OS section below.
+ </div>
+ <h1 class ="postheader">Features by OS</h1>
+ <div class="postcontent">
+ <p> The table below shows a summary of the features that are available
+ on several platforms. In addition to Linux and Mac OS X, LLDB is also
+ known to work on FreeBSD. Windows support is under development.
+ <table border="1">
+ <tr>
+ <th>Feature</th>
+ <th>Linux<br>(x86_64)</th>
+ <th>Mac OS X (i386/x86_64 and ARM/Thumb)</th>
+ </tr>
+ <tr>
+ <td>Backtracing</td>
+ <td>OK (except with targets built with -fomit-frame-pointer)</td>
+ <td>OK</td>
+ </tr>
+ <tr>
+ <td>Breakpoints
+ <ul>
+ <li>source-line
+ <li>symbolic
+ <li>C++ mangled names
+ <li>module scoping
+ </ul>
+ </td>
+ <td>OK</td>
+ <td>OK</td>
+ </tr>
+ <tr>
+ <td>C++11:
+ <ul>
+ <li>function access
+ <li>template support
+ <li>dynamic types
+ </ul></td>
+ <td>OK</td>
+ <td>OK</td>
+ </tr>
+ <tr>
+ <td>Commandline lldb tool</td>
+ <td>OK</td>
+ <td>OK</td>
+ </tr>
+ <tr>
+ <td>Debugserver (remote debugging)</td>
+ <td>Not ported</td>
+ <td>OK</td>
+ </tr>
+ <tr>
+ <td>Disassembly</td>
+ <td>OK</td>
+ <td>OK</td>
+ </tr>
+ <tr>
+ <td>Expression evaluation</td>
+ <td>Works with some bugs</td>
+ <td>OK</td>
+ </tr>
+ <tr>
+ <td>Objective-C 2.0:
+ <ul>
+ <li>printing properties
+ <li>synthetic properties
+ <li>expressions
+ <li>KVO
+ <li>dynamic types
+ <li>dot syntax
+ <li>runtime data
+ <li>stepping into/over
+ <li>printing the description of an object ("po")
+ </ul></td>
+ <td>Not applicable</td>
+ <td>OK</td>
+ </tr>
+ <tr>
+ <td>Process control
+ <ul>
+ <li>launch
+ <li>attach
+ <li>continue
+ <li>fork
+ </ul>
+ </td>
+ <td>OK</td>
+ <td>OK</td>
+ </tr>
+ <tr>
+ <td>Public Python API</td>
+ <td>OK</td>
+ <td>OK</td>
+ </tr>
+ <tr>
+ <td>Registers (x86_64 and i386)
+ <ul>
+ <li>general purpose
+ <li>floating point
+ <li>exception state
+ <li>SSE
+ <li>AVX
+ </ul>
+ </td>
+ <td>OK (except for exception state registers)</td>
+ <td>OK</td>
+ </tr>
+ <tr>
+ <td>Script bridging</td>
+ <td>OK</td>
+ <td>OK</td>
+ </tr>
+ <tr>
+ <td>Symbol reading and object file introspection</td>
+ <td>OK</td>
+ <td>OK</td>
+ </tr>
+ <tr>
+ <td>Thread inspection and stepping</td>
+ <td>OK for single thread (no multi-threaded support)</td>
+ <td>OK</td>
+ </tr>
+ <tr>
+ <td>Watchpoints</td>
+ <td>OK</td>
+ <td>OK</td>
+ </tr>
+ </table>
+ </div>
+ <div class="postfooter"></div>
+ </div>
+ </div>
+ </div>
+</div>
+</body>
+</html>
Modified: lldb/branches/lldb-platform-work/www/tutorial.html
URL: http://llvm.org/viewvc/llvm-project/lldb/branches/lldb-platform-work/www/tutorial.html?rev=183468&r1=183467&r2=183468&view=diff
==============================================================================
--- lldb/branches/lldb-platform-work/www/tutorial.html (original)
+++ lldb/branches/lldb-platform-work/www/tutorial.html Thu Jun 6 19:06:43 2013
@@ -93,6 +93,13 @@
<br>(lldb) breakpoint set -n foo
</code>
+ <p>You can use the --name option multiple times to make a breakpoint on a set of functions as well. This is convenient
+ since it allows you to set commmon conditions or commands without having to specify them multiple times:</p>
+
+ <code>
+ (lldb) breakpoint set --name foo --name bar
+ </code>
+
<p>Setting breakpoints by name is even more specialized in LLDB as you can specify
that you want to set a breakpoint at a function by method name. To set a breakpoint
on all C++ methods named <code>foo</code> you can enter either of:</p>
@@ -117,6 +124,8 @@
<br>(lldb) breakpoint set -s foo.dylib -n foo
</code>
+ <p>The <code>--shlib</code> option can also be repeated to specify several shared libraries.</p>
+
<p>Suggestions on more interesting primitives of this sort are also very welcome.</p>
<p>Just like gdb, the lldb command interpreter does a shortest unique
@@ -136,10 +145,12 @@
things like if you specify "<code>--shlib <path></code>", and are completing on "<code>--file <path></code>", we will only
list source files in the shared library specified by "<code>--shlib <path></code>".</p>
- <p>The individual commands are pretty extensively documented, using
- the <code>help</code> command. And there is an <code>apropos</code> command that will
- search the help for a particular word and dump a summary help string
- for each matching command.</p>
+ <p>The individual commands are pretty extensively documented. You can
+ use the <code>help</code> command to get an overview of which commands are
+ available or to obtain details about specific commands. There is also an
+ <code>apropos</code> command that will search the help text for all commands
+ for a particular word and dump a summary help string for each matching
+ command.</p>
<p>Finally, there is a mechanism to construct aliases for commonly used
commands. So for instance if you get annoyed typing:</p>
@@ -347,7 +358,7 @@ Current breakpoints:
to see all the commands for watchpoint manipulations. For instance, we might do the following to watch
a variable called 'global' for write operation, but only stop if the condition '(global==5)' is true:</p>
- <pre><tt>(lldb) watch set var -w write global
+ <pre><tt>(lldb) watch set var global
Watchpoint created: Watchpoint 1: addr = 0x100001018 size = 4 state = enabled type = w
declare @ '/Volumes/data/lldb/svn/ToT/test/functionalities/watchpoint/watchpoint_commands/condition/main.cpp:12'
(lldb) watch modify -c '(global==5)'
Modified: lldb/branches/lldb-platform-work/www/varformats.html
URL: http://llvm.org/viewvc/llvm-project/lldb/branches/lldb-platform-work/www/varformats.html?rev=183468&r1=183467&r2=183468&view=diff
==============================================================================
--- lldb/branches/lldb-platform-work/www/varformats.html (original)
+++ lldb/branches/lldb-platform-work/www/varformats.html Thu Jun 6 19:06:43 2013
@@ -16,8 +16,7 @@
<h1 class="postheader">Variable display</h1>
<div class="postcontent">
- <p>LLDB was recently modified to allow users to define custom
- formatting options for the variables display.</p>
+ <p>LLDB has a data formatters subsystem that allows users to define custom display options for their variables.</p>
<p>Usually, when you type <code>frame variable</code> or
run some <code>expression</code> LLDB will
@@ -33,8 +32,7 @@
different style to the display for certain datatypes.
To do so, you need to give hints to the debugger as to
how variables should be displayed.<br>
- A new <b>type</b> command has been introduced in LLDB
- which allows to do just that.<br>
+ The LLDB <b>type</b> command allows you to do just that.<br>
</p>
<p>Using it you can change your visualization to look like this: </p>
@@ -51,7 +49,7 @@
style="font-style: italic;">synthetic children</span>.</p>
<p>To reflect this, the <b>type</b> command has four
- subcommands:<br>
+ subcommands (plus one specific for <i>categories</i>):<br>
</p>
<p><code>type format</code></p>
@@ -457,9 +455,7 @@
<code>"<b>${*var.int_pointer[0-3]}</b>".</code></p>
<p>Basically, the syntax is the same one described <a
href="formats.html">Frame and Thread Formatting</a>
- are accepted.
- Beyond what's described there, additional symbols have become available
- in the syntax for summary strings. The main of them is <code>${var</code>,
+ plus additional symbols specific for summary strings. The main of them is <code>${var</code>,
which is used refer to the variable that a summary is being created for.</p>
<p>The simplest thing you can do is grab a member variable
of a class or structure by typing its <i>expression
@@ -528,7 +524,7 @@
as in <code>${var.x->x%u}</code>, which would display the value of <code>x</code> as an unsigned integer.
<p>You can also use some other special format markers, not available
- for type formatters, but which carry a special meaning when used in this
+ for formats themselves, but which carry a special meaning when used in this
context:</p>
<table border="1">
@@ -873,18 +869,16 @@ def function (valobj,internal_dict):<br/
<table class="stats" width="620" cellspacing="0">
<td class="content">
<b>(lldb)</b> type summary add --python-script "height =
- int(valobj.GetChildMemberWithName('height').GetValue());width =
- int(valobj.GetChildMemberWithName('width').GetValue());
- return 'Area: ' + str(height*width)" Rectangle<br/>
+ valobj.GetChildMemberWithName('height').GetValueAsUnsigned(0);width =
+ valobj.GetChildMemberWithName('width').GetValueAsUnsigned(0);
+ return 'Area: %d' % (height*width)" Rectangle<br/>
</td>
</table>
<ul>
<li> using the <code>--python-function</code> (<code>-F</code>) option to <code>type summary add </code> and giving the name of a
Python function with the correct prototype. Most probably, you will define (or have
already defined) the function in the interactive interpreter, or somehow
- loaded it from a file, using the <code>script import</code> command. LLDB will not make any attempt at determining whether
- the function is defined and syntactically correct, until you try to call it. Any errors will be shown at that stage, as if
- you were executing your function inside the Python interactive interpreter itself.
+ loaded it from a file, using the <code>command script import</code> command. LLDB will emit a warning if it is unable to find the function you passed, but will still register the binding.
</ul>
</p>
@@ -915,8 +909,9 @@ def function (valobj,internal_dict):<br/
<table>
<code>
- <b>(lldb)</b> frame variable sarray<br>
+ <b>(lldb)</b> frame variable<br>
(Simple [3]) sarray = [1,4,7]<br>
+ (Simple [2]) sother = [3,6]<br>
</code> The above scenario works for <code>Simple [3]</code>
as well as for any other array of <code>Simple</code>
objects. </p>
@@ -926,20 +921,10 @@ def function (valobj,internal_dict):<br/
matching is slower than normal name matching, LLDB will
first try to match by name in any way it can, and only
when this fails, will it resort to regular expression
- matching. Thus, if your type has a base class with a
- cascading summary, this will be preferred over any
- regular expression match for your type itself.</p>
+ matching. </p>
<p>One of the ways LLDB uses this feature internally, is to match
the names of STL container classes, regardless of the template
- arguments provided (e.g. <code>std::vector<T></code> for any
- type argument <code>T</code>). The regular expressions used for this are:
- </p>
- <ul>
- <li><code>^(std::)?vector<.+>$</code> for <code>std::vector<T></code></li>
- <li><code>^(std::)?list<.+>$</code> for <code>std::list<T></code></li>
- <li><code>^(std::)?map<.+> >$</code> for <code>std::map<K,V></code></li>
- </ul>
- As you can see, the actual template arguments are ignored by the regular expression.
+ arguments provided. The details for this are found at <a href="http://llvm.org/svn/llvm-project/lldb/trunk/source/DataFormatters/FormatManager.cpp">FormatManager.cpp</a></p>
<p>The regular expression language used by LLDB is the <a href="http://en.wikipedia.org/wiki/Regular_expression#POSIX_Extended_Regular_Expressions">POSIX extended language</a>, as defined by the <a href="http://pubs.opengroup.org/onlinepubs/7908799/xsh/regex.h.html">Single UNIX Specification</a>, of which Mac OS X is a
compliant implementation.
@@ -1039,9 +1024,14 @@ def function (valobj,internal_dict):<br/
<i>this call should return a new LLDB SBValue object representing the child at the index given as argument</i> <br/>
<font color=blue>def</font> update(self): <br/>
<i>this call should be used to update the internal state of this Python object whenever the state of the variables in LLDB changes.</i><sup>[1]</sup><br/>
+ <font color=blue>def</font> has_children(self): <br/>
+ <i>this call should return True if this object might have children, and False if this object can be guaranteed not to have children.</i><sup>[2]</sup><br/>
</code>
-<sup>[1]</sup> This method is optional. Also, it may optionally choose to return a value (starting with LLDB SVN rev153061/LLDB-134). If it returns a value, and that value is <font color=blue><code>True</code></font>, LLDB will be allowed to cache the children and the children count it previously obtained, and will not return to the provider class to ask. If nothing, <font color=blue><code>None</code></font>, or anything other than <font color=blue><code>True</code></font> is returned, LLDB will discard the cached information and ask. Regardless, whenever necessary LLDB will call <code>update</code>.
- <p>For examples of how synthetic children are created, you are encouraged to look at <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/synthetic/">examples/synthetic</a> in the LLDB trunk.
+<sup>[1]</sup> This method is optional. Also, it may optionally choose to return a value (starting with SVN rev153061/LLDB-134). If it returns a value, and that value is <font color=blue><code>True</code></font>, LLDB will be allowed to cache the children and the children count it previously obtained, and will not return to the provider class to ask. If nothing, <font color=blue><code>None</code></font>, or anything other than <font color=blue><code>True</code></font> is returned, LLDB will discard the cached information and ask. Regardless, whenever necessary LLDB will call <code>update</code>.
+<br/>
+<sup>[2]</sup> This method is optional (starting with SVN rev166495/LLDB-175). While implementing it in terms of <code>num_children</code> is acceptable, implementors are encouraged to look for optimized coding alternatives whenever reasonable.
+ <p>For examples of how synthetic children are created, you are encouraged to look at <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/synthetic/">examples/synthetic</a> in the LLDB trunk. Please, be aware that the code in those files (except bitfield/)
+ is legacy code and is not maintained.
You may especially want to begin looking at <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/synthetic/bitfield">this example</a> to get
a feel for this feature, as it is a very easy and well commented example.</p>
The design pattern consistently used in synthetic providers shipping with LLDB
@@ -1072,8 +1062,7 @@ def function (valobj,internal_dict):<br/
} <br/>
</code> </p>
- <p>Currently, in LLDB <a href="http://llvm.org/svn/llvm-project/lldb/trunk/">top of tree</a>, synthetic children providers are enabled for
- <code>std::vector<T></code>, <code>std::list<T></code> and <code>std::map<K,V></code> both in the version provided by <a href="http://gcc.gnu.org/libstdc++/">libstdcpp</a> and by <a href="http://libcxx.llvm.org/">libcxx</a>.</p>
+ <p>LLDB has synthetic children providers for a core subset of STL classes, both in the version provided by <a href="http://gcc.gnu.org/libstdc++/">libstdcpp</a> and by <a href="http://libcxx.llvm.org/">libcxx</a>, as well as for several Foundation classes.</p>
<p>Synthetic children extend summary strings by enabling a new special variable: <code>${svar</code>.<br/>
This symbol tells LLDB to refer expression paths to the
@@ -1106,7 +1095,7 @@ def function (valobj,internal_dict):<br/
error: Couldn't convert the expression to DWARF<br/>
</code> </p>
The reason for this is that classes might have an overloaded <code><font color="blue">operator</font> []</code>, or other special provisions
- and the <code>expression</code> command ignores synthetic children when evaluating its arguments.
+ and the <code>expression</code> command chooses to ignore synthetic children in the interest of equivalency with code you asked to have compiled from source.
</div>
</div>
@@ -1142,12 +1131,10 @@ def function (valobj,internal_dict):<br/
<div class="postcontent">
<p>When doing Objective-C development, you may notice that some of your variables
come out as of type <code>id</code> (for instance, items extracted from <code>NSArray</code>).
- While this does not influence the ability of the runtime to send messages to them, it could make it impossible for LLDB
- to determine the actual formatters for that object, given its type-based algorithm.</p>
- <p>The debugger, however, can dynamically discover the type of an Objective-C
+By default, LLDB will not show you the real type of the object. it can actually dynamically discover the type of an Objective-C
variable, much like the runtime itself does when invoking a selector. In order
- to let LLDB do that, however, a special option to <code>frame variable</code> is
- required: <code>--dynamic-type</code>.</p>
+ to be shown the result of that discovery that, however, a special option to <code>frame variable</code> or <code>expression</code> is
+ required: <br/><code>--dynamic-type</code>.</p>
<p><code>--dynamic-type</code> can have one of three values:
<ul>
<li><code>no-dynamic-values</code>: the default, prevents dynamic type discovery</li>
@@ -1164,20 +1151,24 @@ def function (valobj,internal_dict):<br/
</p>
<p><table class="stats" width="620" cellspacing="0">
<td class="content">
- <b>(lldb)</b> frame variable ns_string --dynamic-type no-run-target --show-types
+ <b>(lldb)</b> expr @"Hello"
+ </td>
+ </table>
+ <code>(NSString *) $0 = 0x00000001048000b0 @"Hello"<br/>
+ </code>
+ <p><table class="stats" width="620" cellspacing="0">
+ <td class="content">
+ <b>(lldb)</b> expr -d no-run @"Hello"
</td>
</table>
- <code>(id, dynamic type: __NSCFString) ns_string = 0x00000001001183d0 @"An NSString saying hello world"<br/>
+ <code>(__NSCFString *) $1 = 0x00000001048000b0 @"Hello"<br/>
</code>
<p>
Because LLDB uses a detection algorithm that does not need to invoke any functions
- on the target process, <code>no-run-target</code> is enough for this to work.
- As a final sidenote on this, LLDB is currently able to provide a summary string for <code>NSString</code>
- that shows the content of the string, without requiring you to run code on the target
- process. This features requires you to enable the AppKit category (see below for details). The
- Python code for this formatter is at <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/summaries/cocoa/CFString.py">
- CFString.py</a> (the script is well commented, but intricate and might not be obvious, lacking
- working experience with Cocoa and the LLDB API).
+ on the target process, <code>no-run-target</code> is enough for this to work.</p>
+ As a side note, the summary for NSString shown in the example is built right into LLDB.
+ It was initially implemented through Python (the code is still available for reference at <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/summaries/cocoa/CFString.py">CFString.py</a>).
+ However, this is out of sync with the current implementation of the NSString formatter (which is a C++ function compiled into the LLDB core).
</p>
</div>
</div>
@@ -1186,7 +1177,7 @@ def function (valobj,internal_dict):<br/
<h1 class="postheader">Categories</h1>
<div class="postcontent">
<p>Categories are a way to group related formatters. For instance, LLDB itself groups
- the formatters for the C++ STL objects in a category named <code>gnu-libstdc++</code>.
+ the formatters for the libstdc++ types in a category named <code>gnu-libstdc++</code>.
Basically, categories act like containers in which to store formatters for a same library
or OS release.</p>
<p>By default, several categories are created in LLDB:
More information about the llvm-branch-commits
mailing list