mirror of
https://github.com/capstone-engine/llvm-capstone.git
synced 2025-03-06 01:19:28 +00:00
A few cleanups for our documentation
llvm-svn: 183058
This commit is contained in:
Enrico Granata
parent
65ac02ad78
commit
8e698323ec
@ -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
|
||||
|
||||
@ -305,8 +305,8 @@ Enter your Python command(s). Type 'DONE' to end.
|
||||
> <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' to end.
|
||||
</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
|
||||
|
||||
@ -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>(__NSCFString *) ns_string = 0x00000001001183d0 @"An NSString saying hello world"<br/>
|
||||
<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 *) $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:
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user