forked from OSchip/llvm-project
1294 lines
73 KiB
HTML
Executable File
1294 lines
73 KiB
HTML
Executable 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 Data Formatters</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">Variable display</h1>
|
|
<div class="postcontent">
|
|
|
|
<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
|
|
automatically choose the way to display your results on
|
|
a per-type basis, as in the following example:</p>
|
|
|
|
<p> <code> <b>(lldb)</b> frame variable<br>
|
|
(uint8_t) x = 'a'<br>
|
|
(intptr_t) y = 124752287<br>
|
|
</code> </p>
|
|
|
|
<p>However, in certain cases, you may want to associate a
|
|
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>
|
|
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>
|
|
|
|
<p> <code> <b>(lldb)</b> frame variable<br>
|
|
(uint8_t) x = chr='a' dec=65 hex=0x41<br>
|
|
(intptr_t) y = 0x76f919f<br>
|
|
</code> </p>
|
|
|
|
<p>There are several features related to data visualization: <span
|
|
style="font-style: italic;">formats</span>, <span
|
|
style="font-style: italic;">summaries</span>, <span
|
|
style="font-style: italic;">filters</span>, <span
|
|
style="font-style: italic;">synthetic children</span>.</p>
|
|
|
|
<p>To reflect this, the <b>type</b> command has four
|
|
subcommands (plus one specific for <i>categories</i>):<br>
|
|
</p>
|
|
|
|
<p><code>type format</code></p>
|
|
<p><code>type summary</code></p>
|
|
<p><code>type filter</code></p>
|
|
<p><code>type synthetic</code></p>
|
|
|
|
|
|
<p>These commands are meant to bind printing options to
|
|
types. When variables are printed, LLDB will first check
|
|
if custom printing options have been associated to a
|
|
variable's type and, if so, use them instead of picking
|
|
the default choices.<br>
|
|
</p>
|
|
|
|
<p>Each of the commands has four subcommands available:<br>
|
|
</p>
|
|
<p><code>add</code>: associates a new printing option to one
|
|
or more types</p>
|
|
<p><code>delete</code>: deletes an existing association</p>
|
|
<p><code>list</code>: provides a listing of all
|
|
associations</p>
|
|
<p><code>clear</code>: deletes all associations</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="post">
|
|
<h1 class="postheader">type format</h1>
|
|
<div class="postcontent">
|
|
|
|
<p>Type formats enable you to quickly override the default
|
|
format for displaying primitive types (the usual basic
|
|
C/C++/ObjC types: <code><font color="blue">int</font></code>, <code><font color="blue">float</font></code>, <code><font color="blue">char</font></code>, ...).</p>
|
|
|
|
<p>If for some reason you want all <code>int</code>
|
|
variables in your program to print out as hex, you can add
|
|
a format to the <code>int</code> type.<br></p>
|
|
|
|
<p>This is done by typing
|
|
<table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> type format add --format hex int
|
|
</td>
|
|
<table>
|
|
at the LLDB command line.</p>
|
|
|
|
<p>The <code>--format</code> (which you can shorten to <code>-f</code>) option accepts a <a
|
|
href="#formatstable">format name</a>. Then, you provide one or more
|
|
types to which you want the new format applied.</p>
|
|
|
|
<p>A frequent scenario is that your program has a <code>typedef</code>
|
|
for a numeric type that you know represents something
|
|
that must be printed in a certain way. Again, you can
|
|
add a format just to that typedef by using <code>type
|
|
format add</code> with the name alias.</p>
|
|
|
|
<p>But things can quickly get hierarchical. Let's say you
|
|
have a situation like the following:</p>
|
|
|
|
<p><code><font color="blue">typedef int</font> A;<br>
|
|
<font color="blue">typedef</font> A B;<br>
|
|
<font color="blue">typedef</font> B C;<br>
|
|
<font color="blue">typedef</font> C D;<br>
|
|
</code></p>
|
|
|
|
<p>and you want to show all <code>A</code>'s as hex, all
|
|
<code>C'</code>s as byte arrays and leave the defaults
|
|
untouched for other types (albeit its contrived look, the example is far
|
|
from unrealistic in large software systems).</p>
|
|
|
|
<p>If you simply type <br>
|
|
<table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> type format add -f hex A<br>
|
|
<b>(lldb)</b> type format add -f uint8_t[] C
|
|
</td>
|
|
<table>
|
|
<br>
|
|
values of type <code>B</code> will be shown as hex
|
|
and values of type <code>D</code> as byte arrays, as in:</p>
|
|
|
|
<p> <code>
|
|
<b>(lldb)</b> frame variable -T<br/>
|
|
(A) a = 0x00000001<br/>
|
|
(B) b = 0x00000002<br/>
|
|
(C) c = {0x03 0x00 0x00 0x00}<br/>
|
|
(D) d = {0x04 0x00 0x00 0x00}<br/>
|
|
</code> </p>
|
|
|
|
<p>This is because by default LLDB <i>cascades</i>
|
|
formats through typedef chains. In order to avoid that
|
|
you can use the option <code>-C no</code> to prevent
|
|
cascading, thus making the two commands required to
|
|
achieve your goal:<br>
|
|
<table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> type format add -C no -f hex A<br>
|
|
<b>(lldb)</b> type format add -C no -f uint8_t[] C
|
|
</td>
|
|
<table>
|
|
|
|
<p>which provides the desired output:</p>
|
|
<p> <code>
|
|
<b>(lldb)</b> frame variable -T<br/>
|
|
(A) a = 0x00000001<br/>
|
|
(B) b = 2<br/>
|
|
(C) c = {0x03 0x00 0x00 0x00}<br/>
|
|
(D) d = 4<br/>
|
|
</code> </p>
|
|
|
|
<p>Two additional options that you will want to look at
|
|
are <code>--skip-pointers</code> (<code>-p</code>) and <code>--skip-references</code> (<code>-r</code>). These two
|
|
options prevent LLDB from applying a format for type <code>T</code>
|
|
to values of type <code>T*</code> and <code>T&</code>
|
|
respectively.</p>
|
|
|
|
<p> <code> <b>(lldb)</b> type format add -f float32[]
|
|
int<br>
|
|
<b>(lldb)</b> frame variable pointer *pointer -T<br>
|
|
(int *) pointer = {1.46991e-39 1.4013e-45}<br>
|
|
(int) *pointer = {1.53302e-42}<br>
|
|
<b>(lldb)</b> type format add -f float32[] int -p<br>
|
|
<b>(lldb)</b> frame variable pointer *pointer -T<br>
|
|
(int *) pointer = 0x0000000100100180<br>
|
|
(int) *pointer = {1.53302e-42}<br>
|
|
</code> </p>
|
|
|
|
<p>While they can be applied to pointers and references, formats will make no attempt
|
|
to dereference the pointer and extract the value before applying the format, which means you
|
|
are effectively formatting the address stored in the pointer rather than the pointee value.
|
|
For this reason, you may want to use the <code>-p</code> option when defining formats.</p>
|
|
|
|
<p>If you need to delete a custom format simply type <code>type
|
|
format delete</code> followed by the name of the type
|
|
to which the format applies.Even if you
|
|
defined the same format for multiple types on the same command,
|
|
<code>type format delete</code> will only remove the format for
|
|
the type name passed as argument.<br>
|
|
</p>
|
|
<p>
|
|
To delete ALL formats, use
|
|
<code>type format clear</code>. To see all the formats
|
|
defined, use <code>type format list</code>.</p>
|
|
|
|
<p>If all you need to do, however, is display one variable
|
|
in a custom format, while leaving the others of the same
|
|
type untouched, you can simply type:<br>
|
|
<br>
|
|
<table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> frame variable counter -f hex
|
|
</td>
|
|
<table>
|
|
|
|
<p>This has the effect of displaying the value of <code>counter</code>
|
|
as an hexadecimal number, and will keep showing it this
|
|
way until you either pick a different format or till you
|
|
let your program run again.</p>
|
|
|
|
<p>Finally, this is a list of formatting options available
|
|
out of
|
|
which you can pick:</p><a name="formatstable"></a>
|
|
<table border="1">
|
|
<tbody>
|
|
<tr valign="top">
|
|
<td width="23%"><b>Format name</b></td>
|
|
<td><b>Abbreviation</b></td>
|
|
<td><b>Description</b></td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>default</b></td>
|
|
<td><br>
|
|
</td>
|
|
<td>the default LLDB algorithm is used to pick a
|
|
format</td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>boolean</b></td>
|
|
<td>B</td>
|
|
<td>show this as a true/false boolean, using the
|
|
customary rule that 0 is false and everything else
|
|
is true</td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>binary</b></td>
|
|
<td>b</td>
|
|
<td>show this as a sequence of bits</td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>bytes</b></td>
|
|
<td>y</td>
|
|
<td>show the bytes one after the other<br>
|
|
e.g. <code>(int) s.x = 07 00 00 00</code></td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>bytes with ASCII</b></td>
|
|
<td>Y</td>
|
|
<td>show the bytes, but try to display them as ASCII
|
|
characters as well<br>
|
|
e.g. <code>(int *) c.sp.x = 50 f8 bf 5f ff 7f 00
|
|
00 P.._....</code></td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>character</b></td>
|
|
<td>c</td>
|
|
<td>show the bytes as ASCII characters<br>
|
|
e.g. <code>(int *) c.sp.x =
|
|
P\xf8\xbf_\xff\x7f\0\0</code></td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>printable character</b></td>
|
|
<td>C</td>
|
|
<td>show the bytes as printable ASCII
|
|
characters<br>
|
|
e.g. <code>(int *) c.sp.x = P.._....</code></td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>complex float</b></td>
|
|
<td>F</td>
|
|
<td>interpret this value as the real and imaginary
|
|
part of a complex floating-point number<br>
|
|
e.g. <code>(int *) c.sp.x = 2.76658e+19 +
|
|
4.59163e-41i</code></td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>c-string</b></td>
|
|
<td>s</td>
|
|
<td>show this as a 0-terminated C string</td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>decimal</b></td>
|
|
<td>i</td>
|
|
<td>show this as a signed integer number (this does
|
|
not perform a cast, it simply shows the bytes as
|
|
an integer with sign)</td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>enumeration</b></td>
|
|
<td>E</td>
|
|
<td>show this as an enumeration, printing the
|
|
value's name if available or the integer value
|
|
otherwise<br>
|
|
e.g. <code>(enum enumType) val_type = eValue2</code></td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>hex</b></td>
|
|
<td>x</td>
|
|
<td>show this as in hexadecimal notation (this does
|
|
not perform a cast, it simply shows the bytes as
|
|
hex)</td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>float</b></td>
|
|
<td>f</td>
|
|
<td>show this as a floating-point number (this does
|
|
not perform a cast, it simply interprets the bytes
|
|
as an IEEE754 floating-point value)</td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>octal</b></td>
|
|
<td>o</td>
|
|
<td>show this in octal notation</td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>OSType</b></td>
|
|
<td>O</td>
|
|
<td>show this as a MacOS OSType<br>
|
|
e.g. <code>(float) x = '\n\x1f\xd7\n'</code></td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>unicode16</b></td>
|
|
<td>U</td>
|
|
<td>show this as UTF-16 characters<br>
|
|
e.g. <code>(float) x = 0xd70a 0x411f</code></td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>unicode32</b></td>
|
|
<td><br>
|
|
</td>
|
|
<td>show this as UTF-32 characters<br>
|
|
e.g. <code>(float) x = 0x411fd70a</code></td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>unsigned decimal</b></td>
|
|
<td>u</td>
|
|
<td>show this as an unsigned integer number (this
|
|
does not perform a cast, it simply shows the bytes
|
|
as unsigned integer)</td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>pointer</b></td>
|
|
<td>p</td>
|
|
<td>show this as a native pointer (unless this is
|
|
really a pointer, the resulting address will
|
|
probably be invalid)</td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>char[]</b></td>
|
|
<td><br>
|
|
</td>
|
|
<td>show this as an array of characters<br>
|
|
e.g. <code>(char) *c.sp.z = {X}</code></td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>int8_t[], uint8_t[]<br>
|
|
int16_t[], uint16_t[]<br>
|
|
int32_t[], uint32_t[]<br>
|
|
int64_t[], uint64_t[]<br>
|
|
uint128_t[]</b></td>
|
|
<td><br>
|
|
</td>
|
|
<td>show this as an array of the corresponding
|
|
integer type<br>
|
|
e.g.<br>
|
|
<code>(int) x = {1 0 0 0}</code> (with uint8_t[])<br>
|
|
<code>(int) y = {0x00000001}</code> (with uint32_t[])</td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>float32[], float64[]</b></td>
|
|
<td><br>
|
|
</td>
|
|
<td>show this as an array of the corresponding
|
|
floating-point type<br>
|
|
e.g. <code>(int *) pointer = {1.46991e-39
|
|
1.4013e-45}</code></td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>complex integer</b></td>
|
|
<td>I</td>
|
|
<td>interpret this value as the real and imaginary
|
|
part of a complex integer number<br>
|
|
e.g. <code>(int *) pointer = 1048960 + 1i</code></td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>character array</b></td>
|
|
<td>a</td>
|
|
<td>show this as a character array<br>
|
|
e.g. <code>(int *) pointer =
|
|
\x80\x01\x10\0\x01\0\0\0</code></td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="post">
|
|
<h1 class="postheader">type summary</h1>
|
|
<div class="postcontent">
|
|
<p>Type formats work by showing a different kind of display for
|
|
the value of a variable. However, they only work for basic types.
|
|
When you want to display a class or struct in a custom format, you
|
|
cannot do that using formats.</p>
|
|
<p>A different feature, type summaries, works by extracting
|
|
information from classes, structures, ... (<i>aggregate types</i>)
|
|
and arranging it in a user-defined format, as in the following example:</p>
|
|
<p> <i>before adding a summary...</i><br>
|
|
<code> <b>(lldb)</b> frame variable -T one<br>
|
|
(i_am_cool) one = {<br>
|
|
(int) x = 3<br>
|
|
(float) y = 3.14159<br>
|
|
(char) z = 'E'<br>
|
|
}<br>
|
|
</code> <br>
|
|
<i>after adding a summary...</i><br>
|
|
<code> <b>(lldb)</b> frame variable one<br>
|
|
(i_am_cool) one = int = 3, float = 3.14159, char = 69<br>
|
|
</code> </p>
|
|
|
|
<p>There are two ways to use type summaries: the first one is to bind a <i>
|
|
summary string</i> to the type; the second is to write a Python script that returns
|
|
the string to be used as summary. Both options are enabled by the <code>type summary add</code>
|
|
command.</p>
|
|
<p>The command to obtain the output shown in the example is:</p>
|
|
<table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> type summary add --summary-string "int = ${var.x}, float = ${var.y}, char = ${var.z%u}" i_am_cool
|
|
</td>
|
|
<table>
|
|
|
|
<p>Initially, we will focus on summary strings, and then describe the Python binding
|
|
mechanism.</p>
|
|
|
|
</div>
|
|
</div>
|
|
<div class="post">
|
|
<h1 class="postheader">Summary Strings</h1>
|
|
<div class="postcontent">
|
|
<p>Summary strings are written using a simple control language, exemplified by the snippet above.
|
|
A summary string contains a sequence of tokens that are processed by LLDB to generate the summary.</p>
|
|
|
|
<p>Summary strings can contain plain text, control characters and
|
|
special variables that have access to information about
|
|
the current object and the overall program state.</p>
|
|
<p>Plain text is any sequence of characters that doesn't contain a <code><b>'{'</b></code>,
|
|
<code><b>'}'</b></code>, <code><b>'$'</b></code>, or <code><b>'\'</b></code>
|
|
character, which are the syntax control characters.</p>
|
|
<p>The special variables are found in between a <code><b>"${"</b></code>
|
|
prefix, and end with a <code><b>"}"</b></code> suffix. Variables can be a simple name
|
|
or they can refer to complex objects that have subitems themselves.
|
|
In other words, a variable looks like <code>"<b>${object}</b>"</code> or
|
|
<code>"<b>${object.child.otherchild}</b>"</code>. A variable can also be prefixed or
|
|
suffixed with other symbols meant to change the way its value is handled. An example is
|
|
<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>
|
|
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
|
|
path</i>. In the previous example, the expression path
|
|
for the field <code>float y</code> is simply <code>.y</code>.
|
|
Thus, to ask the summary string to display <code>y</code>
|
|
you would type <code>${var.y}</code>.</p>
|
|
<p>If you have code like the following: <br>
|
|
<code> <font color="blue">struct</font> A {<br>
|
|
<font color="blue">int</font> x;<br>
|
|
<font color="blue">int</font> y;<br>
|
|
};<br>
|
|
<font color="blue">struct</font> B {<br>
|
|
A x;<br>
|
|
A y;<br>
|
|
<font color="blue">int</font> *z;<br>
|
|
};<br>
|
|
</code> the expression path for the <code>y</code>
|
|
member of the <code>x</code> member of an object of
|
|
type <code>B</code> would be <code>.x.y</code> and you
|
|
would type <code>${var.x.y}</code> to display it in a
|
|
summary string for type <code>B</code>. </p>
|
|
<p>By default, a summary defined for type <code>T</code>, also works for types
|
|
<code>T*</code> and <code>T&</code> (you can disable this behavior if desired).
|
|
For this reason, expression paths do not differentiate between <code>.</code>
|
|
and <code>-></code>, and the above expression path <code>.x.y</code>
|
|
would be just as good if you were displaying a <code>B*</code>,
|
|
or even if the actual definition of <code>B</code>
|
|
were: <code><br>
|
|
<font color="blue">struct</font> B {<br>
|
|
A *x;<br>
|
|
A y;<br>
|
|
<font color="blue">int</font> *z;<br>
|
|
};<br>
|
|
</code> </p>
|
|
<p>This is unlike the behavior of <code>frame variable</code>
|
|
which, on the contrary, will enforce the distinction. As
|
|
hinted above, the rationale for this choice is that
|
|
waiving this distinction enables you to write a summary
|
|
string once for type <code>T</code> and use it for both
|
|
<code>T</code> and <code>T*</code> instances. As a
|
|
summary string is mostly about extracting nested
|
|
members' information, a pointer to an object is just as
|
|
good as the object itself for the purpose.</p>
|
|
<p>If you need to access the value of the integer pointed to by <code>B::z</code>, you
|
|
cannot simply say <code>${var.z}</code> because that symbol refers to the pointer <code>z</code>.
|
|
In order to dereference it and get the pointed value, you should say <code>${*var.z}</code>. The <code>${*var</code>
|
|
tells LLDB to get the object that the expression paths leads to, and then dereference it. In this example is it
|
|
equivalent to <code>*(bObject.z)</code> in C/C++ syntax. Because <code>.</code> and <code>-></code> operators can both be
|
|
used, there is no need to have dereferences in the middle of an expression path (e.g. you do not need to type
|
|
<code>${*(var.x).x})</code> to read <code>A::x</code> as contained in <code>*(B::x)</code>. To achieve that effect
|
|
you can simply write <code>${var.x->x}</code>, or even <code>${var.x.x}</code>. The <code>*</code> operator only binds
|
|
to the result of the whole expression path, rather than piecewise, and there is no way to use parentheses to change
|
|
that behavior.</p>
|
|
<p>Of course, a summary string can contain more than one <code>${var</code> specifier,
|
|
and can use <code>${var</code> and <code>${*var</code> specifiers together.</p>
|
|
</div>
|
|
</div>
|
|
<div class="post">
|
|
<h1 class="postheader">Formatting summary elements</h1>
|
|
<div class="postcontent">
|
|
<p>An expression path can include formatting codes.
|
|
Much like the type formats discussed previously, you can also customize
|
|
the way variables are displayed in summary strings, regardless of the format they have
|
|
applied to their types. To do that, you can use <code>%<i>format</i></code> inside an expression path,
|
|
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 formats themselves, but which carry a special meaning when used in this
|
|
context:</p>
|
|
|
|
<table border="1">
|
|
<tbody>
|
|
<tr valign="top">
|
|
<td width="23%"><b>Symbol</b></td>
|
|
<td><b>Description</b></td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>%S</b></td>
|
|
<td>Use this object's summary (the default for aggregate types)</td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>%V</b></td>
|
|
<td>Use this object's value (the default for non-aggregate types)</td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>%@</b></td>
|
|
<td>Use a language-runtime specific description (for C++ this does nothing,
|
|
for Objective-C it calls the NSPrintForDebugger API)</td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>%L</b></td>
|
|
<td>Use this object's location (memory address, register name, ...)</td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>%#</b></td>
|
|
<td>Use the count of the children of this object</td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td><b>%T</b></td>
|
|
<td>Use this object's datatype name</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
|
|
<p>Option <code>--inline-children</code> (<code>-c</code>) to <code>type summary add</code>
|
|
tells LLDB not to look for a summary string, but instead
|
|
to just print a listing of all the object's children on
|
|
one line.</p>
|
|
<p> As an example, given a type <code>pair</code>:
|
|
<code> <br>
|
|
<b>(lldb)</b> frame variable --show-types a_pair<br>
|
|
(pair) a_pair = {<br>
|
|
(int) first = 1;<br/>
|
|
(int) second = 2;<br/>
|
|
}<br>
|
|
</code><br>
|
|
If one types the following commands:
|
|
<table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> type summary add --inline-children pair<br>
|
|
</td>
|
|
<table>
|
|
the output becomes: <br><code>
|
|
|
|
<b>(lldb)</b> frame variable a_pair<br>
|
|
(pair) a_pair = (first=1, second=2)<br>
|
|
</code> </p>
|
|
|
|
Of course, one can obtain the same effect by typing
|
|
<table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> type summary add pair --summary-string "(first=${var.first}, second=${var.second})"<br>
|
|
</td>
|
|
<table>
|
|
|
|
While the final result is the same, using <code>--inline-children</code> can often save time. If one does not need to
|
|
see the names of the variables, but just their values, the option <code>--omit-names</code> (<code>-O</code>, uppercase letter o), can be combined with <code>--inline-children</code> to obtain:
|
|
<br><code>
|
|
|
|
<b>(lldb)</b> frame variable a_pair<br>
|
|
(pair) a_pair = (1, 2)<br>
|
|
</code> </p>
|
|
|
|
which is of course the same as
|
|
typing
|
|
<table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> type summary add pair --summary-string "(${var.first}, ${var.second})"<br>
|
|
</td>
|
|
<table>
|
|
</div>
|
|
</div>
|
|
<div class="post">
|
|
<h1 class="postheader">Bitfields and array syntax</h1>
|
|
<div class="postcontent">
|
|
<p>Sometimes, a basic type's value actually represents
|
|
several different values packed together in a bitfield.<br/>
|
|
With the classical view, there is no way to look at
|
|
them. Hexadecimal display can help, but if the bits
|
|
actually span nibble boundaries, the help is limited.<br/>
|
|
Binary view would show it all without ambiguity, but is
|
|
often too detailed and hard to read for real-life
|
|
scenarios.
|
|
<p>
|
|
To cope with the issue, LLDB supports native
|
|
bitfield formatting in summary strings. If your
|
|
expression paths leads to a so-called <i>scalar type</i>
|
|
(the usual int, float, char, double, short, long, long
|
|
long, double, long double and unsigned variants), you
|
|
can ask LLDB to only grab some bits out of the value and
|
|
display them in any format you like. If you only need one bit
|
|
you can use the <code>[</code><i>n</i><code>]</code>, just like
|
|
indexing an array. To extract multiple bits, you can use
|
|
a slice-like syntax: <code>[</code><i>n</i>-<i>m</i><code>]</code>, e.g. <br><p>
|
|
<code> <b>(lldb)</b> frame variable float_point<br>
|
|
(float) float_point = -3.14159<br> </code>
|
|
<table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> type summary add --summary-string "Sign: ${var[31]%B}
|
|
Exponent: ${var[30-23]%x} Mantissa: ${var[0-22]%u}"
|
|
float
|
|
</td>
|
|
</table><br></code>
|
|
|
|
<code>
|
|
<b>(lldb)</b> frame variable float_point<br>
|
|
(float) float_point = -3.14159 Sign: true Exponent:
|
|
0x00000080 Mantissa: 4788184<br>
|
|
</code> In this example, LLDB shows the internal
|
|
representation of a <code>float</code> variable by
|
|
extracting bitfields out of a float object.</p>
|
|
|
|
<p> When typing a range, the extremes <i>n</i> and <i>m</i> are always
|
|
included, and the order of the indices is irrelevant. </p>
|
|
|
|
<p>LLDB also allows to use a similar syntax to display
|
|
array members inside a summary string. For instance, you
|
|
may want to display all arrays of a given type using a
|
|
more compact notation than the default, and then just
|
|
delve into individual array members that prove
|
|
interesting to your debugging task. You can tell
|
|
LLDB to format arrays in special ways, possibly
|
|
independent of the way the array members' datatype is formatted. <br>
|
|
e.g. <br>
|
|
<code> <b>(lldb)</b> frame variable sarray<br>
|
|
(Simple [3]) sarray = {<br>
|
|
[0] = {<br>
|
|
x = 1<br>
|
|
y = 2<br>
|
|
z = '\x03'<br>
|
|
}<br>
|
|
[1] = {<br>
|
|
x = 4<br>
|
|
y = 5<br>
|
|
z = '\x06'<br>
|
|
}<br>
|
|
[2] = {<br>
|
|
x = 7<br>
|
|
y = 8<br>
|
|
z = '\t'<br>
|
|
}<br>
|
|
}<br></code>
|
|
|
|
<table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> type summary add --summary-string "${var[].x}" "Simple
|
|
[3]"
|
|
</td>
|
|
<table><br>
|
|
|
|
<code>
|
|
<b>(lldb)</b> frame variable sarray<br>
|
|
(Simple [3]) sarray = [1,4,7]<br></code></p>
|
|
|
|
<p>The <code>[]</code> symbol amounts to: <i>if <code>var</code>
|
|
is an array and I know its size, apply this summary
|
|
string to every element of the array</i>. Here, we are
|
|
asking LLDB to display <code>.x</code> for every
|
|
element of the array, and in fact this is what happens.
|
|
If you find some of those integers anomalous, you can
|
|
then inspect that one item in greater detail, without
|
|
the array format getting in the way: <br>
|
|
<code> <b>(lldb)</b> frame variable sarray[1]<br>
|
|
(Simple) sarray[1] = {<br>
|
|
x = 4<br>
|
|
y = 5<br>
|
|
z = '\x06'<br>
|
|
}<br>
|
|
</code> </p>
|
|
<p>You can also ask LLDB to only print a subset of the
|
|
array range by using the same syntax used to extract bit
|
|
for bitfields:
|
|
<table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> type summary add --summary-string "${var[1-2].x}" "Simple
|
|
[3]"
|
|
</td>
|
|
<table><br>
|
|
<code>
|
|
<b>(lldb)</b> frame variable sarray<br>
|
|
(Simple [3]) sarray = [4,7]<br></code></p>
|
|
|
|
<p>If you are dealing with a pointer that you know is an array, you can use this
|
|
syntax to display the elements contained in the pointed array instead of just
|
|
the pointer value. However, because pointers have no notion of their size, the
|
|
empty brackets <code>[]</code> operator does not work, and you must explicitly provide
|
|
higher and lower bounds.</p>
|
|
|
|
<p>In general, LLDB needs the square brackets operator <code>[]</code> in
|
|
order to handle arrays and pointers correctly, and for pointers it also
|
|
needs a range. However, a few special cases are defined to make your life easier:
|
|
<ul>
|
|
<li>you can print a 0-terminated string (<i>C-string</i>) using the %s format,
|
|
omitting square brackets, as in:
|
|
<table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> type summary add --summary-string "${var%s}" "char *"
|
|
</td>
|
|
<table>
|
|
<p>
|
|
This syntax works for <code>char*</code> as well as for <code>char[]</code>
|
|
because LLDB can rely on the final <code>\0</code> terminator to know when the string
|
|
has ended.</p>
|
|
LLDB has default summary strings for <code>char*</code> and <code>char[]</code> that use
|
|
this special case. On debugger startup, the following are defined automatically:
|
|
<table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> type summary add --summary-string "${var%s}" "char *"<br/>
|
|
<b>(lldb)</b> type summary add --summary-string "${var%s}" -x "char \[[0-9]+]"<br/>
|
|
</td>
|
|
<table>
|
|
</li>
|
|
</ul>
|
|
<ul>
|
|
|
|
<li>any of the array formats (<code>int8_t[]</code>,
|
|
<code>float32{}</code>, ...), and the <code>y</code>, <code>Y</code>
|
|
and <code>a</code> formats
|
|
work to print an array of a non-aggregate
|
|
type, even if square brackets are omitted.
|
|
<table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> type summary add --summary-string "${var%int32_t[]}" "int [10]"
|
|
</td>
|
|
<table>
|
|
|
|
</ul>
|
|
This feature, however, is not enabled for pointers because there is no
|
|
way for LLDB to detect the end of the pointed data.
|
|
<br>
|
|
This also does not work for other formats (e.g. <code>boolean</code>), and you must
|
|
specify the square brackets operator to get the expected output.
|
|
</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="post">
|
|
<h1 class="postheader">Python scripting</h1>
|
|
<div class="postcontent">
|
|
|
|
<p>Most of the times, summary strings prove good enough for the job of summarizing
|
|
the contents of a variable. However, as soon as you need to do more than picking
|
|
some values and rearranging them for display, summary strings stop being an
|
|
effective tool. This is because summary strings lack the power to actually perform
|
|
any kind of computation on the value of variables.</p>
|
|
<p>To solve this issue, you can bind some Python scripting code as a summary for
|
|
your datatype, and that script has the ability to both extract children variables
|
|
as the summary strings do and to perform active computation on the extracted
|
|
values. As a small example, let's say we have a Rectangle class:</p>
|
|
|
|
<code>
|
|
<font color="blue">class</font> Rectangle<br/>
|
|
{<br/>
|
|
<font color="blue">private</font>:<br/>
|
|
<font color="blue">int</font> height;<br/>
|
|
<font color="blue">int</font> width;<br/>
|
|
<font color="blue">public</font>:<br/>
|
|
Rectangle() : height(3), width(5) {}<br/>
|
|
Rectangle(<font color="blue">int</font> H) : height(H), width(H*2-1) {}<br/>
|
|
Rectangle(<font color="blue">int</font> H, <font color="blue">int</font> W) : height(H), width(W) {}<br/>
|
|
|
|
<font color="blue">int</font> GetHeight() { return height; }<br/>
|
|
<font color="blue">int</font> GetWidth() { return width; }<br/>
|
|
|
|
};<br/>
|
|
</code>
|
|
|
|
<p>Summary strings are effective to reduce the screen real estate used by
|
|
the default viewing mode, but are not effective if we want to display the
|
|
area and perimeter of <code>Rectangle</code> objects</p>
|
|
|
|
<p>To obtain this, we can simply attach a small Python script to the <code>Rectangle</code>
|
|
class, as shown in this example:</p>
|
|
|
|
<table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> type summary add -P Rectangle<br/>
|
|
Enter your Python command(s). Type 'DONE' to end.<br/>
|
|
def function (valobj,internal_dict):<br/>
|
|
height_val = valobj.GetChildMemberWithName('height')<br/>
|
|
width_val = valobj.GetChildMemberWithName('width')<br/>
|
|
height = height_val.GetValueAsUnsigned(0)<br/>
|
|
width = width_val.GetValueAsUnsigned(0)<br/>
|
|
area = height*width<br/>
|
|
perimeter = 2*(height + width)<br/>
|
|
return 'Area: ' + str(area) + ', Perimeter: ' + str(perimeter)<br/>
|
|
DONE<br/>
|
|
<b>(lldb)</b> frame variable<br/>
|
|
(Rectangle) r1 = Area: 20, Perimeter: 18<br/>
|
|
(Rectangle) r2 = Area: 72, Perimeter: 36<br/>
|
|
(Rectangle) r3 = Area: 16, Perimeter: 16<br/>
|
|
</td>
|
|
</table>
|
|
|
|
<p>In order to write effective summary scripts, you need to know the LLDB public
|
|
API, which is the way Python code can access the LLDB object model. For further
|
|
details on the API you should look at <a href="scripting.html">this page</a>, or at
|
|
the LLDB <a href="docs.html">doxygen documentation</a> when it becomes available.</p>
|
|
|
|
<p>As a brief introduction, your script is encapsulated into a function that is
|
|
passed two parameters: <code>valobj</code> and <code>internal_dict</code>.</p>
|
|
|
|
<p><code>internal_dict</code> is an internal support parameter used by LLDB and you should
|
|
not touch it.<br/><code>valobj</code> is the object encapsulating the actual
|
|
variable being displayed, and its type is <a href="http://llvm.org/svn/llvm-project/lldb/trunk/include/lldb/API/SBValue.h">SBValue</a>.
|
|
Out of the many possible operations on an SBValue, the basic one is retrieve the children objects
|
|
it contains (essentially, the fields of the object wrapped by it), by calling
|
|
<code>GetChildMemberWithName()</code>, passing it the child's name as a string.<br/>
|
|
If the variable has a value, you can ask for it, and return it as a string using <code>GetValue()</code>,
|
|
or as a signed/unsigned number using <code>GetValueAsSigned()</code>, <code>GetValueAsUnsigned()</code>.
|
|
It is also possible to retrieve an <a href="http://llvm.org/svn/llvm-project/lldb/trunk/include/lldb/API/SBData.h"><code>SBData</code></a> object by calling <code>GetData()</code> and then read
|
|
the object's contents out of the <code>SBData</code>.
|
|
|
|
<p>If you need to delve into several levels of hierarchy, as you can do with summary
|
|
strings, you can use the method <code>GetValueForExpressionPath()</code>, passing it
|
|
an expression path just like those you could use for summary strings (one of the differences
|
|
is that dereferencing a pointer does not occur by prefixing the path with a <code>*</code>,
|
|
but by calling the <code>Dereference()</code> method on the returned SBValue).
|
|
If you need to access array slices, you cannot do that (yet) via this method call, and you must
|
|
use <code>GetChildAtIndex()</code> querying it for the array items one by one.
|
|
Also, handling custom formats is something you have to deal with on your own.
|
|
|
|
<p>Other than interactively typing a Python script there are two other ways for you
|
|
to input a Python script as a summary:
|
|
|
|
<ul>
|
|
<li> using the --python-script option to <code>type summary add </code> and typing the script
|
|
code as an option argument; as in: </ul>
|
|
|
|
<table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> type summary add --python-script "height =
|
|
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>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>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div class="post">
|
|
<h1 class="postheader">Regular expression typenames</h1>
|
|
<div class="postcontent">
|
|
<p>As you noticed, in order to associate the custom
|
|
summary string to the array types, one must give the
|
|
array size as part of the typename. This can long become
|
|
tiresome when using arrays of different sizes, <code>Simple
|
|
|
|
[3]</code>, <code>Simple [9]</code>, <code>Simple
|
|
[12]</code>, ...</p>
|
|
<p>If you use the <code>-x</code> option, type names are
|
|
treated as regular expressions instead of type names.
|
|
This would let you rephrase the above example
|
|
for arrays of type <code>Simple [3]</code> as: <br>
|
|
|
|
<table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> type summary add --summary-string "${var[].x}"
|
|
-x "Simple \[[0-9]+\]"
|
|
</td>
|
|
<table>
|
|
|
|
<code>
|
|
<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>
|
|
<p>While this feature is mostly useful for arrays, you
|
|
could also use regular expressions to catch other type
|
|
sets grouped by name. However, as regular expression
|
|
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. </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. 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.
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div class="post">
|
|
<h1 class="postheader">Named summaries</h1>
|
|
<div class="postcontent">
|
|
<p>For a given type, there may be different meaningful summary
|
|
representations. However, currently, only one summary can be associated
|
|
to a type at each moment. If you need to temporarily override the association
|
|
for a variable, without changing the summary string for to its type,
|
|
you can use named summaries.</p>
|
|
|
|
<p>Named summaries work by attaching a name to a summary when creating
|
|
it. Then, when there is a need to attach the summary to a variable, the
|
|
<code>frame variable</code> command, supports a <code>--summary</code> option
|
|
that tells LLDB to use the named summary given instead of the default one.</p>
|
|
|
|
<table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> type summary add --summary-string "x=${var.integer}" --name NamedSummary
|
|
</td>
|
|
<table>
|
|
<code> <b>(lldb)</b> frame variable one<br>
|
|
(i_am_cool) one = int = 3, float = 3.14159, char = 69<br>
|
|
<b>(lldb)</b> frame variable one --summary NamedSummary<br>
|
|
(i_am_cool) one = x=3<br>
|
|
</code> </p>
|
|
|
|
<p>When defining a named summmary, binding it to one or more types becomes optional.
|
|
Even if you bind the named summary to a type, and later change the summary string
|
|
for that type, the named summary will not be changed by that. You can delete
|
|
named summaries by using the <code>type summary delete</code> command, as if the
|
|
summary name was the datatype that the summary is applied to</p>
|
|
|
|
<p>A summary attached to a variable using the </code>--summary</code> option,
|
|
has the same semantics that a custom format attached using the <code>-f</code>
|
|
option has: it stays attached till you attach a new one, or till you let
|
|
your program run again.</p>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
<div class="post">
|
|
<h1 class="postheader">Synthetic children</h1>
|
|
<div class="postcontent">
|
|
<p>Summaries work well when one is able to navigate through an expression path.
|
|
In order for LLDB to do so, appropriate debugging information must be available.</p>
|
|
<p>Some types are <i>opaque</i>, i.e. no knowledge of their internals is provided.
|
|
When that's the case, expression paths do not work correctly.</p>
|
|
<p>In other cases, the internals are available to use in expression paths, but they
|
|
do not provide a user-friendly representation of the object's value.</p>
|
|
<p>For instance, consider an STL vector, as implemented by the <a href="http://gcc.gnu.org/onlinedocs/libstdc++/">GNU C++ Library</a>:</p>
|
|
<code>
|
|
<b>(lldb)</b> frame variable numbers -T<br/>
|
|
(std::vector<int>) numbers = {<br/>
|
|
(std::_Vector_base<int, std::allocator<int> >) std::_Vector_base<int, std::allocator<int> > = {<br/>
|
|
(std::_Vector_base<int, std::allocator&tl;int> >::_Vector_impl) _M_impl = {<br/>
|
|
(int *) _M_start = 0x00000001001008a0<br/>
|
|
(int *) _M_finish = 0x00000001001008a8<br/>
|
|
(int *) _M_end_of_storage = 0x00000001001008a8<br/>
|
|
}<br/>
|
|
}<br/>
|
|
}<br/>
|
|
</code>
|
|
<p>Here, you can see how the type is implemented, and you can write a summary for that implementation
|
|
but that is not going to help you infer what items are actually stored in the vector.</p>
|
|
<p>What you would like to see is probably something like:</p>
|
|
<code>
|
|
<b>(lldb)</b> frame variable numbers -T<br/>
|
|
(std::vector<int>) numbers = {<br/>
|
|
(int) [0] = 1<br/>
|
|
(int) [1] = 12<br/>
|
|
(int) [2] = 123<br/>
|
|
(int) [3] = 1234<br/>
|
|
}<br/>
|
|
</code>
|
|
<p>Synthetic children are a way to get that result.</p>
|
|
<p>The feature is based upon the idea of providing a new set of children for a variable that replaces the ones
|
|
available by default through the debug information. In the example, we can use synthetic children to provide
|
|
the vector items as children for the std::vector object.</p>
|
|
<p>In order to create synthetic children, you need to provide a Python class that adheres to a given <i>interface</i>
|
|
(the word is italicized because <a href="http://en.wikipedia.org/wiki/Duck_typing">Python has no explicit notion of interface</a>, by that word we mean a given set of methods
|
|
must be implemented by the Python class):</p>
|
|
<code>
|
|
<font color=blue>class</font> SyntheticChildrenProvider:<br/>
|
|
<font color=blue>def</font> __init__(self, valobj, internal_dict):<br/>
|
|
<i>this call should initialize the Python object using valobj as the variable to provide synthetic children for</i> <br/>
|
|
<font color=blue>def</font> num_children(self): <br/>
|
|
<i>this call should return the number of children that you want your object to have</i> <br/>
|
|
<font color=blue>def</font> get_child_index(self,name): <br/>
|
|
<i>this call should return the index of the synthetic child whose name is given as argument</i> <br/>
|
|
<font color=blue>def</font> get_child_at_index(self,index): <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 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
|
|
is to use the <code>__init__</code> to store the SBValue instance as a part of <code>self</code>. The <code>update</code> function is then used
|
|
to perform the actual initialization.
|
|
|
|
|
|
<p>Once a synthetic children provider is written, one must load it into LLDB before it can be used.
|
|
Currently, one can use the LLDB <code>script</code> command to type Python code interactively,
|
|
or use the <code>command script import <i>fileName </i></code> command to load Python code from a Python module
|
|
(ordinary rules apply to importing modules this way). A third option is to type the code for
|
|
the provider class interactively while adding it.</p>
|
|
|
|
<p>For example, let's pretend we have a class <code>Foo</code> for which a synthetic children provider class
|
|
<code>Foo_Provider</code> is available, in a Python module contained in file <code>~/Foo_Tools.py</code>. The following interaction
|
|
sets <code>Foo_Provider</code> as a synthetic children provider in LLDB:</p>
|
|
|
|
<table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> command script import ~/Foo_Tools.py<br/>
|
|
<b>(lldb)</b> type synthetic add Foo --python-class Foo_Tools.Foo_Provider
|
|
</td>
|
|
<table>
|
|
<code> <b>(lldb)</b> frame variable a_foo<br/>
|
|
(Foo) a_foo = {<br/>
|
|
x = 1<br/>
|
|
y = "Hello world"<br/>
|
|
} <br/>
|
|
</code> </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
|
|
synthetic children instead of the real ones. For instance,</p>
|
|
|
|
<table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> type summary add --expand -x "std::vector<" --summary-string "${svar%#} items"
|
|
</td>
|
|
</table>
|
|
<code> <b>(lldb)</b> frame variable numbers<br/>
|
|
(std::vector<int>) numbers = 4 items {<br/>
|
|
(int) [0] = 1<br/>
|
|
(int) [1] = 12<br/>
|
|
(int) [2] = 123<br/>
|
|
(int) [3] = 1234<br/>
|
|
}<br/>
|
|
</code> </p>
|
|
<p>In some cases, if LLDB is unable to use the real object to get a child specified in an expression path, it will automatically refer to the
|
|
synthetic children. While in summaries it is best to always use <code>${svar</code> to make your intentions clearer, interactive debugging
|
|
can benefit from this behavior, as in:
|
|
<code> <b>(lldb)</b> frame variable numbers[0] numbers[1]<br/>
|
|
(int) numbers[0] = 1<br/>
|
|
(int) numbers[1] = 12<br/>
|
|
</code> </p>
|
|
Unlike many other visualization features, however, the access to synthetic children only works when using <code>frame variable</code>, and is
|
|
not supported in <code>expression</code>:<br/>
|
|
<code> <b>(lldb)</b> expression numbers[0]<br/>
|
|
Error [IRForTarget]: Call to a function '_ZNSt33vector<int, std::allocator<int> >ixEm' that is not present in the target<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 chooses to ignore synthetic children in the interest of equivalency with code you asked to have compiled from source.
|
|
</div>
|
|
</div>
|
|
|
|
<div class="post">
|
|
<h1 class="postheader">Filters</h1>
|
|
<div class="postcontent">
|
|
<p>Filters are a solution to the display of complex classes.
|
|
At times, classes have many member variables but not all of these are actually
|
|
necessary for the user to see.</p>
|
|
<p>A filter will solve this issue by only letting the user see those member
|
|
variables he cares about. Of course, the equivalent of a filter can be implemented easily
|
|
using synthetic children, but a filter lets you get the job done without having to write
|
|
Python code.</p>
|
|
<p>For instance, if your class <code>Foobar</code> has member variables named <code>A</code> thru <code>Z</code>, but you only need to see
|
|
the ones named <code>B</code>, <code>H</code> and <code>Q</code>, you can define a filter:
|
|
<table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> type filter add Foobar --child B --child H --child Q
|
|
</td>
|
|
</table>
|
|
<code> <b>(lldb)</b> frame variable a_foobar<br/>
|
|
(Foobar) a_foobar = {<br/>
|
|
(int) B = 1<br/>
|
|
(char) H = 'H'<br/>
|
|
(std::string) Q = "Hello world"<br/>
|
|
}<br/>
|
|
</code> </p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="post">
|
|
<h1 class="postheader">Objective-C dynamic type discovery</h1>
|
|
<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>).
|
|
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 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>
|
|
<li><code>no-run-target</code>: enables dynamic type discovery as long as running
|
|
code on the target is not required</li>
|
|
<li><code>run-target</code>: enables code execution on the target in order to perform
|
|
dynamic type discovery</li>
|
|
</ul>
|
|
</p>
|
|
<p>
|
|
If you specify a value of either <code>no-run-target</code> or <code>run-target</code>,
|
|
LLDB will detect the dynamic type of your variables and show the appropriate formatters
|
|
for them. As an example:
|
|
</p>
|
|
<p><table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<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 *) $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.</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>
|
|
|
|
<div class="post">
|
|
<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 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:
|
|
<ul>
|
|
<li><code>default</code>: this is the category where every formatter ends up, unless another category is specified
|
|
<li><code>objc</code>: formatters for basic and common Objective-C types that do not specifically depend on Mac OS X
|
|
<li><code>gnu-libstdc++</code>: formatters for std::string, std::vector, std::list and std::map as implemented by libstdcpp
|
|
<li><code>libcxx</code>: formatters for std::string, std::vector, std::list and std::map as implemented by <a href="http://libcxx.llvm.org/">libcxx</a>
|
|
<li><code>system</code>: truly basic types for which a formatter is required
|
|
<li><a href="https://developer.apple.com/library/mac/#documentation/Cocoa/Reference/Foundation/ObjC_classic/_index.html#//apple_ref/doc/uid/20001091"><code>AppKit</code></a>: Cocoa classes
|
|
<li><a href="https://developer.apple.com/corefoundation/"><code>CoreFoundation</code></a>: CF classes
|
|
<li><a href="https://developer.apple.com/library/mac/#documentation/CoreGraphics/Reference/CoreGraphicsConstantsRef/Reference/reference.html"><code>CoreGraphics</code></a>: CG classes
|
|
<li><a href="http://developer.apple.com/library/mac/#documentation/Carbon/reference/CoreServicesReferenceCollection/_index.html"><code>CoreServices</code></a>: CS classes
|
|
<li><code>VectorTypes</code>: compact display for several vector types
|
|
</ul>
|
|
If you want to use a custom category for your formatters, all the <code>type ... add</code> (except for <code>type format add</code>),
|
|
provide a <code>--category</code> (<code>-w</code>) option, that names the category to add the formatter to.
|
|
To delete the formatter, you then have to specify the correct category.</p>
|
|
<p>Categories can be in one of two states: enabled and disabled. A category is initially disabled,
|
|
and can be enabled using the <code>type category enable</code> command. To disable an enabled category,
|
|
the command to use is <code>type category disable</code>.
|
|
<p>The order in which categories are enabled or disabled
|
|
is significant, in that LLDB uses that order when looking for formatters. Therefore, when you enable a category, it becomes
|
|
the second one to be searched (after <code>default</code>, which always stays on top of the list). The default categories are enabled in such a way that the search order is:
|
|
<ul>
|
|
<li>default</li>
|
|
<li>objc</li>
|
|
<li>CoreFoundation</li>
|
|
<li>AppKit</li>
|
|
<li>CoreServices</li>
|
|
<li>CoreGraphics</li>
|
|
<li>gnu-libstdc++</li>
|
|
<li>libcxx</li>
|
|
<li>VectorTypes</li>
|
|
<li>system</li>
|
|
</ul>
|
|
<p>As said, <code>gnu-libstdc++</code> and <code>libcxx</code> contain formatters for C++ STL
|
|
data types. <code>system</code> contains formatters for <code>char*</code> and <code>char[]</code>, which reflect the behavior
|
|
of older versions of LLDB which had built-in formatters for these types. Because now these are formatters, you can even
|
|
replace them with your own if so you wish.</p>
|
|
<p>There is no special command to create a category. When you place a formatter in a category, if that category does not
|
|
exist, it is automatically created. For instance,</p>
|
|
<p><table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> type summary add Foobar --summary-string "a foobar" --category newcategory
|
|
</td>
|
|
</table>
|
|
automatically creates a (disabled) category named newcategory.</p>
|
|
<p>Another way to create a new (empty) category, is to enable it, as in:</p>
|
|
<p><table class="stats" width="620" cellspacing="0">
|
|
<td class="content">
|
|
<b>(lldb)</b> type category enable newcategory
|
|
</td>
|
|
</table>
|
|
<p>However, in this case LLDB warns you that enabling an empty category has no effect. If you add formatters to the
|
|
category after enabling it, they will be honored. But an empty category <i>per se</i> does not change the way any
|
|
type is displayed. The reason the debugger warns you is that enabling an empty category might be a typo, and you
|
|
effectively wanted to enable a similarly-named but not-empty category.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="post">
|
|
<h1 class="postheader">Finding formatters 101</h1>
|
|
<div class="postcontent">
|
|
<p>While the rules for finding an appropriate format for a
|
|
type are relatively simple (just go through typedef
|
|
hierarchies), searching other formatters goes through
|
|
a rather intricate set of rules. Namely, what happens is that LLDB
|
|
starts looking in each enabled category, according to the order in which
|
|
they were enabled (latest enabled first). In each category, LLDB does
|
|
the following:</p>
|
|
<ul>
|
|
<li>If there is a formatter for the type of the variable,
|
|
use it</li>
|
|
<li>If this object is a pointer, and there is a formatter
|
|
for the pointee type that does not skip pointers, use
|
|
it</li>
|
|
<li>If this object is a reference, and there is a
|
|
formatter for the referred type that does not skip
|
|
references, use it</li>
|
|
<li>If this object is an Objective-C class and dynamic types are enabled,
|
|
look for a formatter for the dynamic type of the object. If dynamic types are disabled,
|
|
or the search failed, look for a formatter for the declared type of the object</li>
|
|
<li>If this object's type is a typedef, go through
|
|
typedef hierarchy (LLDB might not be able to do this if
|
|
the compiler has not emitted enough information. If the
|
|
required information to traverse typedef hierarchies is
|
|
missing, type cascading will not work. The
|
|
<a href="http://clang.llvm.org/">clang compiler</a>,
|
|
part of the LLVM project, emits the correct debugging
|
|
information for LLDB to cascade). If at any level of the hierarchy
|
|
there is a valid formatter that can cascade, use it.</li>
|
|
<li>If everything has failed, repeat the above search,
|
|
looking for regular expressions instead of exact
|
|
matches</li>
|
|
</ul>
|
|
<p>If any of those attempts returned a valid formatter to be used,
|
|
that one is used, and the search is terminated (without going to look
|
|
in other categories). If nothing was found in the current category, the next
|
|
enabled category is scanned according to the same algorithm. If there are no
|
|
more enabled categories, the search has failed.</p>
|
|
<p><font color=red>Warning</font>: previous versions of LLDB defined cascading to mean
|
|
not only going through typedef chains, but also through inheritance chains.
|
|
This feature has been removed since it significantly degrades performance.
|
|
You need to set up your formatters for every type in inheritance chains to which
|
|
you want the formatter to apply.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|