Blame - www/varformats.html - platform/external/lldb

2011-07-08 02:51:01 +0000

[diff] [blame]

919

</div>

920

</div>

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

921

922

923

<h1 class="postheader">Named summaries</h1>

924

925

<p>For a given datatype, there may be different meaningful summary

926

representations. However, currently, only one summary can be associated

927

to a given datatype. If you need to temporarily override the association

928

for a variable, without changing the summary string bound to the datatype,

929

you can use named summaries.</p>

930

931

<p>Named summaries work by attaching a name to a summary string when creating

932

it. Then, when there is a need to attach the summary string to a variable, the

933

<code>frame variable</code> command, supports a <code>--summary</code> option

934

that tells LLDB to use the named summary given instead of the default one.</p>

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

938

<b>(lldb)</b> type summary add --summary-string "x=${var.integer}" --name NamedSummary

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

939

</td>

940

<table>

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

941

<code> <b>(lldb)</b> frame variable one<br>

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

942

(i_am_cool) one = int = 3, float = 3.14159, char = 69<br>

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

943

<b>(lldb)</b> frame variable one --summary NamedSummary<br>

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

944

(i_am_cool) one = x=3<br>

945

</code> </p>

946

Enrico Granata

f7a9b14

2011-07-15 02:26:42 +0000

[diff] [blame]

947

<p>When defining a named summmary, binding it to one or more types becomes optional.

948

Even if you bind the named summary to a type, and later change the summary string

949

for that type, the named summary will not be changed by that. You can delete

950

named summaries by using the <code>type summary delete</code> command, as if the

951

summary name was the datatype that the summary is applied to</p>

952

953

<p>A summary attached to a variable using the </code>--summary</code> option,

954

has the same semantics that a custom format attached using the <code>-f</code>

955

option has: it stays attached till you attach a new one, or till you let

956

your program run again.</p>

957

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

</div>

</div>

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

961

962

<h1 class="postheader">Synthetic children</h1>

963

964

<p>Summaries work well when one is able to navigate through an expression path.

965

In order for LLDB to do so, appropriate debugging information must be available.</p>

966

<p>Some types are <i>opaque</i>, i.e. no knowledge of their internals is provided.

967

When that's the case, expression paths do not work correctly.</p>

968

<p>In other cases, the internals are available to use in expression paths, but they

969

do not provide a user-friendly representation of the object's value.</p>

970

<p>For instance, consider an STL vector:</p>

971

<code>

972

<b>(lldb)</b> frame variable numbers -T<br/>

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

973

(std::vector<int>) numbers = {<br/>

974

    (std::_Vector_base<int, std::allocator<int> >) std::_Vector_base<int, std::allocator<int> > = {<br/>

975

        (std::_Vector_base<int, std::allocator&tl;int> >::_Vector_impl) _M_impl = {<br/>

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

976

            (int *) _M_start = 0x00000001001008a0<br/>

977

            (int *) _M_finish = 0x00000001001008a8<br/>

978

            (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

984

but that is not going to help you infer what items are actually stored in the vector.</p>

985

<p>What you would like to see is probably something like:</p>

986

<code>

987

<b>(lldb)</b> frame variable numbers -T<br/>

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

988

(std::vector<int>) numbers = {<br/>

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

989

    (int) [0] = 1<br/>

990

    (int) [1] = 12<br/>

991

    (int) [2] = 123<br/>

992

    (int) [3] = 1234<br/>

993

}<br/>

994

</code>

995

<p>Synthetic children are a way to get that result.</p>

996

<p>The feature is based upon the idea of providing a new set of children for a variable that replaces the ones

997

available by default through the debug information. In the example, we can use synthetic children to provide

998

the vector items as children for the std::vector object.</p>

999

<p>In order to create synthetic children, you need to provide a Python class that adheres to a given <i>interface</i>

1000

(the word is italicized because Python has no explicit notion of interface. By that word we mean a given set of methods

1001

must be implemented by the Python class):</p>

1002

<code>

1003

<font color=blue>class</font> SyntheticChildrenProvider:<br/>

1004

    <font color=blue>def</font> __init__(self, valobj, dict):<br/>

1005

        this call should initialize the Python object using valobj as the variable to provide synthetic children for <br/>

1006

    <font color=blue>def</font> num_children(self): <br/>

1007

        this call should return the number of children that you want your object to have <br/>

1008

    <font color=blue>def</font> get_child_index(self,name): <br/>

1009

        this call should return the index of the synthetic child whose name is given as argument <br/>

1010

    <font color=blue>def</font> get_child_at_index(self,index): <br/>

1011

        this call should return a new LLDB SBValue object representing the child at the index given as argument <br/>

1012

    <font color=blue>def</font> update(self): <br/>

1013

        this call should be used to update the internal state of this Python object whenever the state of the variables in LLDB changes.

1014

Currently this method is optional, because the internal state of synthetic children providers will not be preserved. However, this is meant to change in future versions

1015

of LLDB.<br/>

1016

</code>

Enrico Granata

7e65503

2011-08-24 01:32:46 +0000

[diff] [blame]

1017

<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.

1018

You may especially want to begin looking at <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/synthetic/StdVectorSynthProvider.py">StdVector</a> to get

1019

a feel for this feature.</p>

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

1020

1021

<p>Once a synthetic children provider is written, one must load it into LLDB before it can be used.

1022

Currently, one can use the LLDB <code>script</code> command to type Python code interactively,

1023

or use the <code>script import <i>module</i></code> command to load Python code from a Python module

1024

(ordinary rules apply to importing modules this way). A third option is to type the code for

1025

the provider class interactively while adding it.</p>

1026

1027

<p>For example, let's pretend we have a class Foo for which a synthetic children provider class Foo_Provider

1028

is available, in a Python module named Foo_Tools. The following interaction sets Foo_Provider as a synthetic

1029

children provider in LLDB:</p>

<b>(lldb)</b> script import Foo_Tools<br/>

1034

<b>(lldb)</b> type synthetic add Foo --python-class Foo_Tools.Foo_Provider

1035

</td>

1036

<table>

1037

<code> <b>(lldb)</b> frame variable a_foo<br/>

1038

(Foo) a_foo = {<br/>

1039

    x = 1<br/>

1040

    y = "Hello world"<br/>

} <br/>

</code> </p>

<p>Currently, in LLDB <a href="http://llvm.org/svn/llvm-project/lldb/trunk/">top of tree</a>, synthetic children providers are enabled for

1045

<code>std::vector<T></code>, <code>std::list<T></code> and <code>std::map<K,V></code>.</p>

1046

1047

<p>Synthetic children enable a new symbol for summary strings, <code>${svar</code>. This symbol tells LLDB to refer expression paths to the

1048

synthetic children instead of the real ones. While in certain cases, you can use <code>${var.<i>synthetic-child-path</i>}</code> and LLDB will

1049

access the synthetic child correctly, it is best to always use <code>${svar</code> to refer to synthetic children. For instance,</p>

<b>(lldb)</b> type summary add --expand -x "std::vector<" --summary-string "${svar%#} items"

1054

</td>

1055

<table>

1056

<code> <b>(lldb)</b> frame variable numbers<br/>

1057

(std::vector<int>) numbers = 4 items {<br/>

1058

    (int) [0] = 1<br/>

1059

    (int) [1] = 12<br/>

1060

    (int) [2] = 123<br/>

1061

    (int) [3] = 1234<br/>

}<br/>

</code> </p>

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

1065

</div>

1066

</div>

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

1067

1068

1069

<h1 class="postheader">Filters</h1>

1070

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

1071

<p>Filters are a solution to the display of complex classes.

1072

At times, classes have many member variables but not all of these are actually

1073

necessary for the user to see.</p>

1074

<p>A filter will solve this issue by only letting the user see those member

1075

variables he cares about. Of course, the equivalent of a filter can be implemented easily

1076

using synthetic children, but a filter lets you get the job done without having to write

1077

Python code.</p>

1078

<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

1079

the ones named <code>B</code>, <code>H</code> and <code>Q</code>, you can define a filter:

1080

1081

1082

<b>(lldb)</b> type filter add Foo --child B --child H --child Q

1083

</td>

Enrico Granata

097e555

2011-08-24 04:53:31 +0000

[diff] [blame^]

1084

</table>

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

1085

<code> <b>(lldb)</b> frame variable a_foobar<br/>

1086

(Foobar) a_foobar = {<br/>

1087

    (int) B = 1<br/>

1088

    (char) H = 'H'<br/>

1089

    (std::string) Q = "Hello world"<br/>

1090

}<br/>

1091

</code> </p>

Enrico Granata

097e555

2011-08-24 04:53:31 +0000

[diff] [blame^]

</div>

</div>

<h1 class="postheader">Objective-C dynamic type discovery</h1>

1097

1098

<p>When doing Objective-C development, you may notice that some of your variables

1099

come out as of type <code>id</code>. While this does not influence the ability

1100

of the runtime to send messages to them, it can make it impossible for LLDB

1101

to determine the actual formatters for that object.</p>

1102

<p>The debugger, however, can dynamically discover the type of an Objective-C

1103

variable, much like the runtime itself does when invoking a selector. In order

1104

to let LLDB do that, however, a special option to <code>frame variable</code> is

1105

required: <code>--dynamic-type</code>.</p>

1106

<p><code>--dynamic-type</code> can have one of three values:

1107

<ul>

1108

<li><code>no-dynamic-values</code>: the default, prevents dynamic type discovery</li>

1109

<li><code>no-run-target</code>: enables dynamic type discovery as long as running

1110

code on the target is not required</li>

1111

<li><code>run-target</code>: enables code execution on the target in order to perform

1112

dynamic type discovery</li>

</ul>

</p>

<p>

If you specify a value of either <code>no-run-target</code> or <code>run-target</code>,

1117

LLDB will detect the dynamic type of your variables and show the appropriate formatters

1118

for them. As an example:

</p>

<b>(lldb)</b> frame variable ns_string --dynamic-type no-run-target --show-types

1123

</td>

1124

</table>

1125

<code>(id, dynamic type: __NSCFString) ns_string = 0x00000001001183d0 @"An NSString saying hello world"<br/>

1126

</code>

1127

<p>

1128

Because LLDB uses a detection algorithm that does not need to invoke any functions

1129

on the target process, <code>no-run-target</code> is enough for this to work.

1130

As a final sidenote on this, LLDB is currently able to provide a summary string for <code>NSString</code>

1131

that shows the content of the string, without requiring you to run code on the target

1132

process. <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/synthetic/CFString.py">

1133

CFString.py</a> contains the code for such a Python summary provider (the code is well commented,

1134

but you may find it hard to follow if it is your first time dealing with LLDB formatting features)

1135

and <a href="http://llvm.org/svn/llvm-project/lldb/trunk/test/functionalities/data-formatter/data-formatter-objc/">

1136

this test case</a> contains an usage example.

1137

</p>

Enrico Granata

2011-08-23 21:26:09 +0000

[diff] [blame]

</div>

</div>

Enrico Granata

2011-08-24 01:32:46 +0000

[diff] [blame]

1141

1142

<h1 class="postheader">Categories</h1>

1143

1144

<p>Categories are a way to group related formatters. For instance, LLDB itself groups

1145

the formatters for the C++ STL objects in a category named <code>gnu-libstdc++</code>.

1146

Basically, categories act like containers in which to store formatters for a same library

1147

or OS release.</p>

1148

<p>By default, three categories are created in LLDB: <code>system</code>, <code>gnu-libstdc++</code> and <code>default</code>.

1149

Every formatter that is not created inside a category, is by default a part of the <code>default</code> category.

1150

If you want to use a custom category for your formatters, all the <code>type ... add</code> (except for <code>type format add</code>),

1151

provide a <code>--category</code> (<code>-w</code>) option, that names the category to add the formatter to.

1152

To delete the formatter, you then have to specify the correct category.</p>

1153

<p>Categories can be in one of two states: enabled and disabled. A category is initially disabled,

1154

and can be enabled using the <code>type category enable</code> command. To disable an enabled category,

1155

the command to use is <code>type category disable</code>. The order in which categories are enabled or disabled

1156

is significant, in that LLDB uses that order when looking for formatters. Therefore, when you enable a category, it becomes

1157

the first one to be searched. The default categories are enabled in the order: <code>default</code> as first, then

1158

<code>gnu-libstdc++</code>, and finally <code>system</code>. As said, <code>gnu-libstdc++</code> contains formatters for C++ STL

1159

data types. <code>system</code> contains formatters for <code>char*</code> and <code>char[]</code>, which are expected to be

1160

consistent throughout libraries and systems, and replace </p>

1161

<p>Categories are a way to group related formatters. For instance, LLDB itself groups

1162

the formatters for the C++ STL objects in a category named <code>gnu-libstdc++</code></p>

</div>

</div>

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

1166

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

1167

<h1 class="postheader">Finding formatters 101</h1>

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

1168

1169

<p>While the rules for finding an appropriate format for a

1170

type are relatively simple (just go through typedef

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

1171

hierarchies), searching formatters for a type goes through

Enrico Granata

7e65503

2011-08-24 01:32:46 +0000

[diff] [blame]

1172

a rather intricate set of rules. Namely, what happens is that LLDB

1173

starts looking in each enabled category, according to the order in which

1174

they were enabled (latest enabled first). In each category, LLDB does

1175

the following:</p>

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

1176

<ul>

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

1177

<li>If there is a formatter for the type of the variable,

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

1178

use it</li>

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

1179

<li>If this object is a pointer, and there is a formatter

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

1180

for the pointee type that does not skip pointers, use

1181

it</li>

1182

<li>If this object is a reference, and there is a

1183

summary for the pointee type that does not skip

1184

references, use it</li>

1185

<li>If this object is an Objective-C class with a parent

1186

class, look at the parent class (and parent of parent,

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

1187

...). This phase can be based upon the actual type of

1188

the object as inferred by the value of its <code>isa</code>

1189

pointer, or upon the debugging information inferred by the

1190

debugger. The user can use the dynamic typing settings to

1191

elect one or the other behavior.</li>

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

1192

<li>If this object is a C++ class with base classes,

1193

look at base classes (and bases of bases, ...)</li>

1194

<li>If this object is a C++ class with virtual base

1195

classes, look at the virtual base classes (and bases

1196

of bases, ...)</li>

1197

<li>If this object's type is a typedef, go through

Enrico Granata

86e7c3e

2011-07-12 22:56:10 +0000

[diff] [blame]

1198

typedef hierarchy (LLDB might not be able to do this if

1199

the compiler has not emitted enough information. If the

1200

required information to traverse typedef hierarchies is

1201

missing, type cascading will not work. The

1202

<a href="http://clang.llvm.org/">clang compiler</a>,

1203

part of the LLVM project, emits the correct debugging

1204

information for LLDB to cascade)</li>

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

1205

<li>If everything has failed, repeat the above search,

1206

looking for regular expressions instead of exact

1207

matches</li>

1208

</ul>

Enrico Granata

7e65503

2011-08-24 01:32:46 +0000

[diff] [blame]

1209

<p>If any of those attempts returned a valid formatter to be used,

1210

that one is used, and the search is terminated (without going to look

1211

in other categories). If nothing was found in the current category, the next

1212

enabled category is scanned according to the same algorithm. If there are no

1213

more enabled categories, the search has failed.</p>

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

</div>

</div>

<h1 class="postheader">TODOs</h1>

1218

1219

<ul>

1220

<li>There's no way to do multiple dereferencing, and you

1221

need to be careful what the dereferencing operation is

1222

binding to in complicated scenarios</li>

Enrico Granata

2011-08-22 16:10:25 +0000

[diff] [blame]

1223

<li>Synthetic children providers cannot have a permanent state</li>

Enrico Granata

2011-07-08 02:51:01 +0000

[diff] [blame]

1224

<li><code>type format add</code> does not support the <code>-x</code>

1225

option</li>

Enrico Granata

8a717e5

2011-07-19 02:34:21 +0000

[diff] [blame]

1226

<strike><li>Object location cannot be printed in the summary

1227

string</li></strike>

Enrico Granata