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

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

[diff] [blame]

930

Enrico Granata

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

[diff] [blame]

931

</div>

932

</div>

Enrico Granata

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

[diff] [blame]

933

934

935

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

936

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

937

For a given type, there may be different meaningful summary

Enrico Granata

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

[diff] [blame]

938

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

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

939

to a type at each moment. If you need to temporarily override the association

940

for a variable, without changing the summary string for to its type,

Enrico Granata

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

[diff] [blame]

941

you can use named summaries.

942

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

943

Named summaries work by attaching a name to a summary when creating

944

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

Enrico Granata

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

[diff] [blame]

945

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

946

that tells LLDB to use the named summary given instead of the default one.

Enrico Granata

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

[diff] [blame]

950

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

Enrico Granata

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

[diff] [blame]

951

</td>

952

<table>

Enrico Granata

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

[diff] [blame]

953

<code> (lldb) frame variable one

Enrico Granata

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

[diff] [blame]

954

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

Enrico Granata

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

[diff] [blame]

955

(lldb) frame variable one --summary NamedSummary

Enrico Granata

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

[diff] [blame]

956

(i_am_cool) one = x=3

957

</code>

958

Enrico Granata

f7a9b14

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

[diff] [blame]

959

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

960

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

961

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

962

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

963

summary name was the datatype that the summary is applied to

964

965

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

966

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

967

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

968

your program run again.

969

Enrico Granata

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

[diff] [blame]

</div>

</div>

Enrico Granata

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

[diff] [blame]

973

974

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

975

976

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

977

In order for LLDB to do so, appropriate debugging information must be available.

978

Some types are opaque, i.e. no knowledge of their internals is provided.

979

When that's the case, expression paths do not work correctly.

980

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

981

do not provide a user-friendly representation of the object's value.

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

982

For instance, consider an STL vector, as implemented by the <a href="http://gcc.gnu.org/onlinedocs/libstdc++/">GNU C++ Library</a>:

Enrico Granata

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

[diff] [blame]

983

<code>

984

(lldb) frame variable numbers -T

Enrico Granata

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

[diff] [blame]

985

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

986

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

987

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

Enrico Granata

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

[diff] [blame]

988

(int *) _M_start = 0x00000001001008a0

989

(int *) _M_finish = 0x00000001001008a8

990

(int *) _M_end_of_storage = 0x00000001001008a8

}

}

}

</code>

Here, you can see how the type is implemented, and you can write a summary for that implementation

996

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

997

What you would like to see is probably something like:

998

<code>

999

(lldb) frame variable numbers -T

Enrico Granata

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

[diff] [blame]

1000

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

Enrico Granata

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

[diff] [blame]

(int) [0] = 1

(int) [1] = 12

(int) [2] = 123

(int) [3] = 1234

}

</code>

Synthetic children are a way to get that result.

1008

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

1009

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

1010

the vector items as children for the std::vector object.

1011

In order to create synthetic children, you need to provide a Python class that adheres to a given interface

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1012

(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

Enrico Granata

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

[diff] [blame]

1013

must be implemented by the Python class):

1014

<code>

1015

class SyntheticChildrenProvider:

1016

def __init__(self, valobj, dict):

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1017

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

Enrico Granata

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

[diff] [blame]

1018

def num_children(self):

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1019

this call should return the number of children that you want your object to have

Enrico Granata

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

[diff] [blame]

1020

def get_child_index(self,name):

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1021

this call should return the index of the synthetic child whose name is given as argument

Enrico Granata

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

[diff] [blame]

1022

def get_child_at_index(self,index):

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1023

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

Enrico Granata

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

[diff] [blame]

1024

def update(self):

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1025

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

Enrico Granata

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

[diff] [blame]

1026

</code>

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1027

[1] 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 of LLDB.

Enrico Granata

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

[diff] [blame]

1028

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.

1029

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

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1030

a feel for this feature, as it is a relatively easy and well commented example.

Enrico Granata

2011-08-24 17:12:47 +0000

[diff] [blame]

1031

While the <code>update</code> method is optional, the design pattern consistently used in synthetic providers shipping with LLDB

1032

is to use the <code>__init__</code> to store the SBValue instance as a part of <code>self</code>, and then call <code>update</code>

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1033

to perform the actual initialization. This pattern should make for a transparent transition to a future version of LLDB that persists synthetic children. For example:

1034

<code>

1035

def __init__(self, valobj, dict):

1036

self.valobj = valobj;

1037

    self.update()

1038

</code>

Enrico Granata

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

[diff] [blame]

1039

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

1040

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

1041

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

1042

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

1043

the provider class interactively while adding it.

1044

Enrico Granata

2011-08-24 17:12:47 +0000

[diff] [blame]

1045

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

1046

<code>Foo_Provider</code> is available, in a Python module named <code>Foo_Tools</code>. The following interaction

1047

sets <code>Foo_Provider</code> as a synthetic children provider in LLDB:

Enrico Granata

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

[diff] [blame]

(lldb) script import Foo_Tools

1052

(lldb) type synthetic add Foo --python-class Foo_Tools.Foo_Provider

1053

</td>

1054

<table>

1055

<code> (lldb) frame variable a_foo

(Foo) a_foo = {

x = 1

y = "Hello world"

}

</code>

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

1063

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

1064

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1065

Synthetic children extend summary strings by enabling a new special variable: <code>${svar</code>.

1066

This symbol tells LLDB to refer expression paths to the

1067

synthetic children instead of the real ones. For instance,

Enrico Granata

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

[diff] [blame]

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

1072

</td>

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1073

</table>

Enrico Granata

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

[diff] [blame]

1074

<code> (lldb) frame variable numbers

1075

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

(int) [0] = 1

(int) [1] = 12

(int) [2] = 123

(int) [3] = 1234

}

</code>

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1082

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

1083

synthetic children. While in summaries it is best to always use <code>${svar</code> to make your intentions clearer, interactive debugging

1084

can benefit from this behavior, as in:

1085

<code> (lldb) frame variable numbers[0] numbers[1]

1086

(int) numbers[0] = 1

1087

(int) numbers[1] = 12

1088

</code>

1089

Unlike many other visualization features, however, the access to synthetic children only works when using <code>frame variable</code>, and is

1090

not supported in <code>expression</code>:

1091

<code> (lldb) expression numbers[0]

1092

Error [IRForTarget]: Call to a function '_ZNSt33vector<int, std::allocator<int> >ixEm' that is not present in the target

1093

error: Couldn't convert the expression to DWARF

1094

</code>

1095

The reason for this is that classes might have an overloaded <code>operator []</code>, or other special provisions

1096

and the <code>expression</code> command ignores synthetic children when evaluating its arguments.

Enrico Granata

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

[diff] [blame]

1097

</div>

1098

</div>

Enrico Granata

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

[diff] [blame]

1099

1100

1101

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

1102

Enrico Granata

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

[diff] [blame]

1103

Filters are a solution to the display of complex classes.

1104

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

1105

necessary for the user to see.

1106

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

1107

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

1108

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

1109

Python code.

1110

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

1111

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

1112

1113

Enrico Granata

2011-08-24 17:12:47 +0000

[diff] [blame]

1114

(lldb) type filter add Foobar --child B --child H --child Q

Enrico Granata

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

[diff] [blame]

1115

</td>

Enrico Granata

097e555

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

[diff] [blame]

1116

</table>

Enrico Granata

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

[diff] [blame]

1117

<code> (lldb) frame variable a_foobar

1118

(Foobar) a_foobar = {

1119

(int) B = 1

1120

(char) H = 'H'

1121

(std::string) Q = "Hello world"

1122

}

1123

</code>

Enrico Granata

097e555

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

[diff] [blame]

</div>

</div>

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

1129

1130

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

Enrico Granata

2011-09-07 19:20:42 +0000

[diff] [blame]

1131

come out as of type <code>id</code> (for instance, items extracted from <code>NSArray</code>).

1132

While this does not influence the ability of the runtime to send messages to them, it could make it impossible for LLDB

1133

to determine the actual formatters for that object, given its type-based algorithm.

Enrico Granata

097e555

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

[diff] [blame]

1134

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

1135

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

1136

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

1137

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

1138

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

1139

<ul>

1140

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

1141

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

1142

code on the target is not required</li>

1143

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

1144

dynamic type discovery</li>

</ul>

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

1149

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

1150

for them. As an example:

(lldb) frame variable ns_string --dynamic-type no-run-target --show-types

1155

</td>

1156

</table>

1157

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

1158

</code>

1159

1160

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

1161

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

1162

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

1163

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

1164

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

1165

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

1166

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

1167

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

1168

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

1169

Enrico Granata

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

[diff] [blame]

</div>

</div>

Enrico Granata

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

[diff] [blame]

1173

1174

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

1175

1176

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

1177

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

1178

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

1179

or OS release.

1180

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

1181

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

1182

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

1183

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

1184

To delete the formatter, you then have to specify the correct category.

1185

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

1186

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

1187

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

1188

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

Enrico Granata

0c5c9a2

2011-09-08 00:50:01 +0000

[diff] [blame]

1189

the first one to be searched. The default categories are enabled in such a way that the search order is: <code>default</code>

1190

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

1191

data types. <code>system</code> contains formatters for <code>char*</code> and <code>char[]</code>, which reflect the behavior

1192

of previous versions of LLDB which had built-in formatters for these types. Because now these are formatters, you can even

1193

replace them with your own if so you wish.

Enrico Granata

2011-08-24 17:12:47 +0000

[diff] [blame]

1194

There is no special command to create a category. When you place a formatter in a category, if that category does not

1195

exist, it is automatically created. For instance,

1196

1197

1198

(lldb) type summary add Foobar --summary-string "a foobar" --category newcategory

1199

</td>

1200

</table>

1201

automatically creates a (disabled) category named newcategory.

1202

Another way to create a new (empty) category, is to enable it, as in:

1203

1204

1205

(lldb) type category enable newcategory

1206

</td>

1207

</table>

1208

However, in this case LLDB warns you that enabling an empty category has no effect. If you add formatters to the

1209

category after enabling it, they will be honored. But an empty category per se does not change the way any

1210

type is displayed. The reason the debugger warns you is that enabling an empty category might be a typo, and you

1211

effectively wanted to enable a similarly-named but not-empty category.

Enrico Granata

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

[diff] [blame]

</div>

</div>

Enrico Granata

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

[diff] [blame]

1215

Enrico Granata

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

[diff] [blame]

1216

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

Enrico Granata

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

[diff] [blame]

1217

1218

While the rules for finding an appropriate format for a

1219

type are relatively simple (just go through typedef

Enrico Granata

2011-08-24 17:12:47 +0000

[diff] [blame]

1220

hierarchies), searching other formatters goes through

Enrico Granata

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

[diff] [blame]

1221

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

1222

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

1223

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

1224

the following:

Enrico Granata

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

[diff] [blame]

1225

<ul>

Enrico Granata

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

[diff] [blame]

1226

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

Enrico Granata

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

[diff] [blame]

1227

use it</li>

Enrico Granata

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

[diff] [blame]

1228

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

Enrico Granata

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

[diff] [blame]

1229

for the pointee type that does not skip pointers, use

1230

it</li>

1231

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

Enrico Granata

0c5c9a2

2011-09-08 00:50:01 +0000

[diff] [blame]

1232

formatter for the referred type that does not skip

Enrico Granata

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

[diff] [blame]

1233

references, use it</li>

1234

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

1235

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

Enrico Granata

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

[diff] [blame]

1236

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

1237

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

1238

pointer, or upon the debugging information inferred by the

1239

debugger. The user can use the dynamic typing settings to

1240

elect one or the other behavior.</li>

Enrico Granata

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

[diff] [blame]

1241

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

1242

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

1243

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

1244

classes, look at the virtual base classes (and bases

1245

of bases, ...)</li>

1246

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

Enrico Granata

86e7c3e

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

[diff] [blame]

1247

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

1248

the compiler has not emitted enough information. If the

1249

required information to traverse typedef hierarchies is

1250

missing, type cascading will not work. The

1251

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

1252

part of the LLVM project, emits the correct debugging

1253

information for LLDB to cascade)</li>

Enrico Granata

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

[diff] [blame]

1254

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

1255

looking for regular expressions instead of exact

1256

matches</li>

1257

</ul>

Enrico Granata

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

[diff] [blame]

1258

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

1259

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

1260

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

1261

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

1262

more enabled categories, the search has failed.

Enrico Granata

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

[diff] [blame]

</div>

</div>

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

1267

1268

<ul>

1269

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

1270

need to be careful what the dereferencing operation is

1271

binding to in complicated scenarios</li>

Enrico Granata

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

[diff] [blame]

1272

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

Enrico Granata

2011-08-24 17:12:47 +0000

[diff] [blame]

1273

<li>Smarter algorithm to detect possible typos in category names</li>

Enrico Granata

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

[diff] [blame]

1274

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

1275

option</li>

Enrico Granata