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

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

[diff] [blame]

911

</div>

912

</div>

Enrico Granata

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

[diff] [blame]

913

914

915

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

916

917

For a given datatype, there may be different meaningful summary

918

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

919

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

920

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

921

you can use named summaries.

922

923

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

924

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

925

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

926

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^]

930

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

Enrico Granata

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

[diff] [blame]

931

</td>

932

<table>

Enrico Granata

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

[diff] [blame^]

933

<code> (lldb) frame variable one

Enrico Granata

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

[diff] [blame]

934

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

Enrico Granata

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

[diff] [blame^]

935

(lldb) frame variable one --summary NamedSummary

Enrico Granata

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

[diff] [blame]

936

(i_am_cool) one = x=3

937

</code>

938

Enrico Granata

f7a9b14

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

[diff] [blame]

939

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

940

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

941

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

942

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

943

summary name was the datatype that the summary is applied to

944

945

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

946

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

947

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

948

your program run again.

949

Enrico Granata

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

[diff] [blame]

</div>

</div>

Enrico Granata

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

[diff] [blame]

953

954

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

955

956

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

957

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

958

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

959

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

960

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

961

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

962

For instance, consider an STL vector:

963

<code>

964

(lldb) frame variable numbers -T

Enrico Granata

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

[diff] [blame^]

965

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

966

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

967

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

Enrico Granata

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

[diff] [blame]

968

(int *) _M_start = 0x00000001001008a0

969

(int *) _M_finish = 0x00000001001008a8

970

(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

976

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

977

What you would like to see is probably something like:

978

<code>

979

(lldb) frame variable numbers -T

Enrico Granata

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

[diff] [blame^]

980

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

988

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

989

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

990

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

991

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

992

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

993

must be implemented by the Python class):

994

<code>

995

class SyntheticChildrenProvider:

996

def __init__(self, valobj, dict):

997

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

998

def num_children(self):

999

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

1000

def get_child_index(self,name):

1001

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

1002

def get_child_at_index(self,index):

1003

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

1004

def update(self):

1005

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

1006

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

1007

of LLDB.

1008

</code>

1009

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.

Enrico Granata

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

[diff] [blame^]

1010

1011

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

1012

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

1013

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

1014

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

1015

the provider class interactively while adding it.

1016

1017

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

1018

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

1019

children provider in LLDB:

(lldb) script import Foo_Tools

1024

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

1025

</td>

1026

<table>

1027

<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

1035

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

1036

1037

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

1038

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

1039

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

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

1044

</td>

1045

<table>

1046

<code> (lldb) frame variable numbers

1047

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

(int) [0] = 1

(int) [1] = 12

(int) [2] = 123

(int) [3] = 1234

}

</code>

Enrico Granata

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

[diff] [blame]

1055

</div>

1056

</div>

Enrico Granata

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

[diff] [blame^]

1057

1058

1059

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

1060

1061

1062

Filters are a solution to the display of complex classes.

1063

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

1064

necessary for the user to see.

1065

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

1066

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

1067

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

1068

Python code.

1069

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

1070

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

1071

1072

1073

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

1074

</td>

1075

<table>

1076

<code> (lldb) frame variable a_foobar

1077

(Foobar) a_foobar = {

1078

(int) B = 1

1079

(char) H = 'H'

1080

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

}

</code>

</div>

</div>

Enrico Granata

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

[diff] [blame]

1087

Enrico Granata

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

[diff] [blame]

1088

Enrico Granata

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

[diff] [blame]

1089

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

Enrico Granata

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

[diff] [blame]

1090

1091

While the rules for finding an appropriate format for a

1092

type are relatively simple (just go through typedef

Enrico Granata

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

[diff] [blame]

1093

hierarchies), searching formatters for a type goes through

1094

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

Enrico Granata

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

[diff] [blame]

1095

<ul>

Enrico Granata

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

[diff] [blame]

1096

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

Enrico Granata

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

[diff] [blame]

1097

use it</li>

Enrico Granata

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

[diff] [blame]

1098

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

Enrico Granata

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

[diff] [blame]

1099

for the pointee type that does not skip pointers, use

1100

it</li>

1101

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

1102

summary for the pointee type that does not skip

1103

references, use it</li>

1104

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

1105

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

Enrico Granata

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

[diff] [blame]

1106

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

1107

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

1108

pointer, or upon the debugging information inferred by the

1109

debugger. The user can use the dynamic typing settings to

1110

elect one or the other behavior.</li>

Enrico Granata

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

[diff] [blame]

1111

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

1112

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

1113

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

1114

classes, look at the virtual base classes (and bases

1115

of bases, ...)</li>

1116

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

Enrico Granata

86e7c3e

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

[diff] [blame]

1117

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

1118

the compiler has not emitted enough information. If the

1119

required information to traverse typedef hierarchies is

1120

missing, type cascading will not work. The

1121

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

1122

part of the LLVM project, emits the correct debugging

1123

information for LLDB to cascade)</li>

Enrico Granata

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

[diff] [blame]

1124

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

1125

looking for regular expressions instead of exact

matches</li>

</ul>

</div>

</div>

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

1132

1133

<ul>

1134

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

1135

need to be careful what the dereferencing operation is

1136

binding to in complicated scenarios</li>

Enrico Granata

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

[diff] [blame]

1137

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

Enrico Granata

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

[diff] [blame]

1138

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

1139

option</li>

Enrico Granata

8a717e5

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

[diff] [blame]

1140

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

1141

string</li></strike>

Enrico Granata