[Lldb-commits] [lldb] r183058 - A few cleanups for our documentation
Enrico Granata
egranata at apple.com
Fri May 31 15:54:23 PDT 2013
Author: enrico
Date: Fri May 31 17:54:23 2013
New Revision: 183058
URL: http://llvm.org/viewvc/llvm-project?rev=183058&view=rev
Log:
A few cleanups for our documentation
Modified:
lldb/trunk/www/architecture.html
lldb/trunk/www/python-reference.html
lldb/trunk/www/varformats.html
Modified: lldb/trunk/www/architecture.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/architecture.html?rev=183058&r1=183057&r2=183058&view=diff
==============================================================================
--- lldb/trunk/www/architecture.html (original)
+++ lldb/trunk/www/architecture.html Fri May 31 17:54:23 2013
@@ -60,7 +60,7 @@
<li>Classes can't inherit from any other classes.</li>
<li>Classes can't contain virtual methods.</li>
<li>Classes should be compatible with script bridging utilities like <a href="http://www.swig.org/">swig</a>.</li>
- <li>Classes should be lightweight and be backed by a single object pointer, shared pointer or global variable in the lldb_private.</li>
+ <li>Classes should be lightweight and be backed by a single member. Pointers (or shared pointers) are the preferred choice since they allow changing the contents of the backend without affecting the public object layout.</li>
<li>The interface should be as minimal as possible in order to give a complete API.</li>
</ul>
<p>By adhering to these rules we should be able to continue to
Modified: lldb/trunk/www/python-reference.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/python-reference.html?rev=183058&r1=183057&r2=183058&view=diff
==============================================================================
--- lldb/trunk/www/python-reference.html (original)
+++ lldb/trunk/www/python-reference.html Fri May 31 17:54:23 2013
@@ -305,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.
@@ -391,7 +391,8 @@ Enter your Python command(s). Type 'DONE
</tr>
</table>
<p>As a convenience, you can treat the result object as a Python file object, and say
- print >>result, "my command does lots of cool stuff". SBCommandReturnObject and SBStream
+ <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
Modified: lldb/trunk/www/varformats.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/varformats.html?rev=183058&r1=183057&r2=183058&view=diff
==============================================================================
--- lldb/trunk/www/varformats.html (original)
+++ lldb/trunk/www/varformats.html Fri May 31 17:54:23 2013
@@ -32,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>
@@ -50,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>
@@ -456,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
@@ -527,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">
@@ -872,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>
@@ -914,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>
@@ -925,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.
@@ -1041,10 +1027,11 @@ def function (valobj,internal_dict):<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>.
+<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, and LLDB will honor it starting with SVN rev166495. While implementing it in terms of <code>num_children</code> is acceptable, implementors are encouraged to look for optimized coding alternatives whenever reasonable. For an example, see the <code>std::list</code> providers shipping with LLDB.
- <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>[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
@@ -1075,7 +1062,7 @@ def function (valobj,internal_dict):<br/
} <br/>
</code> </p>
- <p>LLDB has synthetic children providers for basic 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>. and for basic Cocoa containers (NSArray and NSDictionary).</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
@@ -1108,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>
@@ -1144,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>
@@ -1166,18 +1151,23 @@ 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>(__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 first implementation of this feature was a Python script (still available for reference at <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/summaries/cocoa/CFString.py">CFString.py</a>).
+ 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>
@@ -1187,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 lldb-commits
mailing list