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

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

[diff] [blame]

</div>

</div>

Enrico Granata

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

[diff] [blame]

617

<h1 class="postheader">Bitfields and array syntax</h1>

Enrico Granata

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

[diff] [blame]

618

Enrico Granata

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

[diff] [blame]

619

Sometimes, a basic type's value actually represents

Enrico Granata

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

[diff] [blame]

620

several different values packed together in a bitfield.

Enrico Granata

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

[diff] [blame]

621

With the classical view, there is no way to look at

622

them. Hexadecimal display can help, but if the bits

Enrico Granata

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

[diff] [blame]

623

actually span nibble boundaries, the help is limited.

Enrico Granata

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

[diff] [blame]

624

Binary view would show it all without ambiguity, but is

625

often too detailed and hard to read for real-life

Enrico Granata

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

[diff] [blame]

626

scenarios.

627

628

To cope with the issue, LLDB supports native

Enrico Granata

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

[diff] [blame]

629

bitfield formatting in summary strings. If your

630

expression paths leads to a so-called scalar type

631

(the usual int, float, char, double, short, long, long

632

long, double, long double and unsigned variants), you

633

can ask LLDB to only grab some bits out of the value and

Enrico Granata

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

[diff] [blame]

634

display them in any format you like. If you only need one bit

635

you can use the <code>[</code>n<code>]</code>, just like

636

indexing an array. To extract multiple bits, you can use

637

a slice-like syntax: <code>[</code>n-m<code>]</code>, e.g.

Enrico Granata

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

[diff] [blame]

638

<code> (lldb) frame variable float_point

Enrico Granata

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

[diff] [blame]

639

(float) float_point = -3.14159 </code>

640

641

Enrico Granata

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

[diff] [blame]

642

(lldb) type summary add --summary-string "Sign: ${var[31]%B}

Enrico Granata

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

[diff] [blame]

643

Exponent: ${var[30-23]%x} Mantissa: ${var[0-22]%u}"

Enrico Granata

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

[diff] [blame]

644

float

645

</td>

Enrico Granata

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

[diff] [blame]

646

</table> </code>

Enrico Granata

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

[diff] [blame]

647

648

<code>

Enrico Granata

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

[diff] [blame]

649

(lldb) frame variable float_point

Enrico Granata

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

[diff] [blame]

650

(float) float_point = -3.14159 Sign: true Exponent:

651

0x00000080 Mantissa: 4788184

652

</code> In this example, LLDB shows the internal

653

representation of a <code>float</code> variable by

Enrico Granata

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

[diff] [blame]

654

extracting bitfields out of a float object.

655

Enrico Granata

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

[diff] [blame]

656

When typing a range, the extremes n and m are always

657

included, and the order of the indices is irrelevant.

Enrico Granata

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

[diff] [blame]

658

659

LLDB also allows to use a similar syntax to display

Enrico Granata

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

[diff] [blame]

660

array members inside a summary string. For instance, you

661

may want to display all arrays of a given type using a

662

more compact notation than the default, and then just

663

delve into individual array members that prove

Enrico Granata

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

[diff] [blame]

664

interesting to your debugging task. You can tell

665

LLDB to format arrays in special ways, possibly

666

independent of the way the array members' datatype is formatted.

Enrico Granata

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

[diff] [blame]

667

e.g.

Enrico Granata

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

[diff] [blame]

668

<code> (lldb) frame variable sarray

Enrico Granata

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

[diff] [blame]

669

(Simple [3]) sarray = {

Enrico Granata

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

[diff] [blame]

[0] = {

x = 1

y = 2

z = '\x03'

}

[1] = {

x = 4

y = 5

z = '\x06'

}

[2] = {

x = 7

y = 8

z = '\t'

}

} </code>

Enrico Granata

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

[diff] [blame]

689

(lldb) type summary add --summary-string "${var[].x}" "Simple

Enrico Granata

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

[diff] [blame]

[3]"

</td>

<table>

<code>

Enrico Granata

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

[diff] [blame]

695

(lldb) frame variable sarray

Enrico Granata

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

[diff] [blame]

696

(Simple [3]) sarray = [1,4,7] </code>

697

698

The <code>[]</code> symbol amounts to: if <code>var</code>

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

699

is an array and I know its size, apply this summary

Enrico Granata

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

[diff] [blame]

700

string to every element of the array. Here, we are

701

asking LLDB to display <code>.x</code> for every

702

element of the array, and in fact this is what happens.

703

If you find some of those integers anomalous, you can

704

then inspect that one item in greater detail, without

705

the array format getting in the way:

Enrico Granata

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

[diff] [blame]

706

<code> (lldb) frame variable sarray[1]

Enrico Granata

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

[diff] [blame]

707

(Simple) sarray[1] = {

Enrico Granata

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

[diff] [blame]

708

x = 4

709

y = 5

710

z = '\x06'

Enrico Granata

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

[diff] [blame]

711

}

712

</code>

713

You can also ask LLDB to only print a subset of the

714

array range by using the same syntax used to extract bit

Enrico Granata

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

[diff] [blame]

for bitfields:

Enrico Granata

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

[diff] [blame]

718

(lldb) type summary add --summary-string "${var[1-2].x}" "Simple

Enrico Granata

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

[diff] [blame]

[3]"

</td>

<table>

<code>

Enrico Granata

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

[diff] [blame]

723

(lldb) frame variable sarray

Enrico Granata

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

[diff] [blame]

724

(Simple [3]) sarray = [4,7] </code>

725

Enrico Granata

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

[diff] [blame]

726

If you are dealing with a pointer that you know is an array, you can use this

727

syntax to display the elements contained in the pointed array instead of just

728

the pointer value. However, because pointers have no notion of their size, the

729

empty brackets <code>[]</code> operator does not work, and you must explicitly provide

730

higher and lower bounds.

Enrico Granata

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

[diff] [blame]

731

732

In general, LLDB needs the square brackets operator <code>[]</code> in

733

order to handle arrays and pointers correctly, and for pointers it also

734

needs a range. However, a few special cases are defined to make your life easier:

735

<ul>

736

<li>you can print a 0-terminated string (C-string) using the %s format,

737

omitting square brackets, as in:

738

739

Enrico Granata

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

[diff] [blame]

740

(lldb) type summary add --summary-string "${var%s}" "char *"

Enrico Granata

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

[diff] [blame]

741

</td>

742

<table>

Enrico Granata

de51233

2011-08-24 01:49:09 +0000

[diff] [blame]

743

744

This syntax works for <code>char*</code> as well as for <code>char[]</code>

745

because LLDB can rely on the final <code>\0</code> terminator to know when the string

746

has ended.

747

LLDB has default summary strings for <code>char*</code> and <code>char[]</code> that use

748

this special case. On debugger startup, the following are defined automatically:

749

750

751

(lldb) type summary add --summary-string "${var%s}" "char *"

752

(lldb) type summary add --summary-string "${var%s}" -x "char \[[0-9]+]"

</td>

<table>

</li>

</ul>

Enrico Granata

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

[diff] [blame]

757

<ul>

758

Enrico Granata

de51233

2011-08-24 01:49:09 +0000

[diff] [blame]

759

<li>any of the array formats (<code>int8_t[]</code>,

Enrico Granata

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

[diff] [blame]

760

<code>float32{}</code>, ...), and the <code>y</code>, <code>Y</code>

761

and <code>a</code> formats

762

work to print an array of a non-aggregate

763

type, even if square brackets are omitted.

764

765

Enrico Granata

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

[diff] [blame]

766

(lldb) type summary add --summary-string "${var%int32_t[]}" "int [10]"

Enrico Granata

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

[diff] [blame]

</td>

<table>

</ul>

This feature, however, is not enabled for pointers because there is no

772

way for LLDB to detect the end of the pointed data.

773

774

This also does not work for other formats (e.g. <code>boolean</code>), and you must

775

specify the square brackets operator to get the expected output.

</div>

</div>

Enrico Granata

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

[diff] [blame]

781

<h1 class="postheader">Python scripting</h1>

Enrico Granata

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

[diff] [blame]

782

Enrico Granata

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

[diff] [blame]

783

784

Most of the times, summary strings prove good enough for the job of summarizing

785

the contents of a variable. However, as soon as you need to do more than picking

786

some values and rearranging them for display, summary strings stop being an

787

effective tool. This is because summary strings lack the power to actually perform

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

788

any kind of computation on the value of variables.

Enrico Granata

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

[diff] [blame]

789

To solve this issue, you can bind some Python scripting code as a summary for

790

your datatype, and that script has the ability to both extract children variables

791

as the summary strings do and to perform active computation on the extracted

792

values. As a small example, let's say we have a Rectangle class:

793

794

<code>

Enrico Granata

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

[diff] [blame]

795

class Rectangle

Enrico Granata

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

[diff] [blame]

796

{

Enrico Granata

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

[diff] [blame]

private:

int height;

int width;

public:

Enrico Granata

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

[diff] [blame]

801

Rectangle() : height(3), width(5) {}

Enrico Granata

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

[diff] [blame]

802

Rectangle(int H) : height(H), width(H*2-1) {}

803

Rectangle(int H, int W) : height(H), width(W) {}

Enrico Granata

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

[diff] [blame]

804

Enrico Granata

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

[diff] [blame]

805

int GetHeight() { return height; }

806

int GetWidth() { return width; }

Enrico Granata

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

[diff] [blame]

};

</code>

Summary strings are effective to reduce the screen real estate used by

812

the default viewing mode, but are not effective if we want to display the

Enrico Granata

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

[diff] [blame]

813

area and perimeter of <code>Rectangle</code> objects

Enrico Granata

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

[diff] [blame]

814

815

To obtain this, we can simply attach a small Python script to the <code>Rectangle</code>

816

class, as shown in this example:

(lldb) type summary add -P Rectangle

821

Enter your Python command(s). Type 'DONE' to end.

822

def function (valobj,dict):

823

height_val = valobj.GetChildMemberWithName('height')

824

width_val = valobj.GetChildMemberWithName('width')

Enrico Granata

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

[diff] [blame]

825

height = height_val.GetValueAsUnsigned(0)

826

width = width_val.GetValueAsUnsigned(0)

Enrico Granata

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

[diff] [blame]

827

area = height*width

Enrico Granata

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

[diff] [blame]

828

perimeter = 2*(height + width)

829

return 'Area: ' + str(area) + ', Perimeter: ' + str(perimeter)

Enrico Granata

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

[diff] [blame]

830

DONE

Enrico Granata

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

[diff] [blame]

831

(lldb) frame variable

Enrico Granata

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

[diff] [blame]

832

(Rectangle) r1 = Area: 20, Perimeter: 18

833

(Rectangle) r2 = Area: 72, Perimeter: 36

834

(Rectangle) r3 = Area: 16, Perimeter: 16

Enrico Granata

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

[diff] [blame]

</td>

</table>

Enrico Granata

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

[diff] [blame]

838

In order to write effective summary scripts, you need to know the LLDB public

839

API, which is the way Python code can access the LLDB object model. For further

840

details on the API you should look at <a href="scripting.html">this page</a>, or at

841

the LLDB <a href="docs.html">doxygen documentation</a> when it becomes available.

842

843

As a brief introduction, your script is encapsulated into a function that is

844

passed two parameters: <code>valobj</code> and <code>dict</code>.

845

846

<code>dict</code> is an internal support parameter used by LLDB and you should

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

847

not touch it. <code>valobj</code> is the object encapsulating the actual

Enrico Granata

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

[diff] [blame]

848

variable being displayed, and its type is <a href="http://llvm.org/svn/llvm-project/lldb/trunk/include/lldb/API/SBValue.h">SBValue</a>.

849

Out of the many possible operations on an SBValue, the basic one is retrieve the children objects

850

it contains (essentially, the fields of the object wrapped by it), by calling

851

<code>GetChildMemberWithName()</code>, passing it the child's name as a string.

852

If the variable has a value, you can ask for it, and return it as a string using <code>GetValue()</code>,

853

or as a signed/unsigned number using <code>GetValueAsSigned()</code>, <code>GetValueAsUnsigned()</code>.

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

854

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

855

the object's contents out of the <code>SBData</code>.

Enrico Granata

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

[diff] [blame]

856

857

If you need to delve into several levels of hierarchy, as you can do with summary

Enrico Granata

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

[diff] [blame]

858

strings, you can use the method <code>GetValueForExpressionPath()</code>, passing it

Enrico Granata

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

[diff] [blame]

859

an expression path just like those you could use for summary strings (one of the differences

860

is that dereferencing a pointer does not occur by prefixing the path with a <code>*</code>,

861

but by calling the <code>Dereference()</code> method on the returned SBValue).

862

If you need to access array slices, you cannot do that (yet) via this method call, and you must

Enrico Granata

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

[diff] [blame]

863

use <code>GetChildAtIndex()</code> querying it for the array items one by one.

Enrico Granata

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

[diff] [blame]

864

Also, handling custom formats is something you have to deal with on your own.

Enrico Granata

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

[diff] [blame]

865

866

Other than interactively typing a Python script there are two other ways for you

867

to input a Python script as a summary:

868

869

<ul>

Enrico Granata

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

[diff] [blame]

870

<li> using the --python-script option to <code>type summary add </code> and typing the script

Enrico Granata

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

[diff] [blame]

871

code as an option argument; as in: </ul>

Enrico Granata

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

[diff] [blame]

875

(lldb) type summary add --python-script "height =

Enrico Granata

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

[diff] [blame]

876

int(valobj.GetChildMemberWithName('height').GetValue());width =

877

int(valobj.GetChildMemberWithName('width').GetValue());

878

return 'Area: ' + str(height*width)" Rectangle

879

</td>

880

</table>

881

<ul>

Enrico Granata

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

[diff] [blame]

882

<li> using the <code>--python-function</code> (<code>-F</code>) option to <code>type summary add </code> and giving the name of a

Enrico Granata

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

[diff] [blame]

883

Python function with the correct prototype. Most probably, you will define (or have

884

already defined) the function in the interactive interpreter, or somehow

Enrico Granata

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

[diff] [blame]

885

loaded it from a file, using the <code>script import</code> command. LLDB will not make any attempt at determining whether

886

the function is defined and syntactically correct, until you try to call it. Any errors will be shown at that stage, as if

887

you were executing your function inside the Python interactive interpreter itself.

Enrico Granata

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

[diff] [blame]

</ul>

Enrico Granata

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

[diff] [blame]

</div>

</div>

Enrico Granata

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

[diff] [blame]

895

896

<h1 class="postheader">Regular expression typenames</h1>

897

Enrico Granata

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

[diff] [blame]

898

As you noticed, in order to associate the custom

899

summary string to the array types, one must give the

900

array size as part of the typename. This can long become

901

tiresome when using arrays of different sizes, <code>Simple

902

903

[3]</code>, <code>Simple [9]</code>, <code>Simple

904

[12]</code>, ...

905

If you use the <code>-x</code> option, type names are

906

treated as regular expressions instead of type names.

Enrico Granata

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

[diff] [blame]

907

This would let you rephrase the above example

908

for arrays of type <code>Simple [3]</code> as:

Enrico Granata

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

[diff] [blame]

912

(lldb) type summary add --summary-string "${var[].x}"

Enrico Granata

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

[diff] [blame]

913

-x "Simple \[[0-9]+\]"

</td>

<table>

<code>

Enrico Granata

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

[diff] [blame]

918

(lldb) frame variable sarray

Enrico Granata

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

[diff] [blame]

919

(Simple [3]) sarray = [1,4,7]

920

</code> The above scenario works for <code>Simple [3]</code>

921

as well as for any other array of <code>Simple</code>

922

objects.

923

While this feature is mostly useful for arrays, you

924

could also use regular expressions to catch other type

925

sets grouped by name. However, as regular expression

926

matching is slower than normal name matching, LLDB will

927

first try to match by name in any way it can, and only

928

when this fails, will it resort to regular expression

929

matching. Thus, if your type has a base class with a

930

cascading summary, this will be preferred over any

931

regular expression match for your type itself.

Enrico Granata

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

[diff] [blame]

932

One of the ways LLDB uses this feature internally, is to match

933

the names of STL container classes, regardless of the template

934

arguments provided (e.g. <code>std::vector<T></code> for any

Enrico Granata

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

[diff] [blame]

935

type argument <code>T</code>). The regular expressions used for this are:

936

937

<ul>

938

<li><code>^(std::)?vector<.+>$</code> for <code>std::vector<T></code></li>

</ul>

As you can see, the actual template arguments are ignored by the regular expression.

Enrico Granata

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

[diff] [blame]

943

Enrico Granata

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

[diff] [blame]

944

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

945

compliant implementation.

Enrico Granata

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

[diff] [blame]

946

Enrico Granata

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

[diff] [blame]

947

</div>

948

</div>

Enrico Granata

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

[diff] [blame]

949

950

951

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

952

Enrico Granata

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

[diff] [blame]

953

For a given type, there may be different meaningful summary

Enrico Granata

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

[diff] [blame]

954

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

Enrico Granata

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

[diff] [blame]

955

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

956

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

Enrico Granata

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

[diff] [blame]

957

you can use named summaries.

958

Enrico Granata

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

[diff] [blame]

959

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

960

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]

961

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

962

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]

966

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

Enrico Granata

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

[diff] [blame]

967

</td>

968

<table>

Enrico Granata

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

[diff] [blame]

969

<code> (lldb) frame variable one

Enrico Granata

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

[diff] [blame]

970

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

Enrico Granata

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

[diff] [blame]

971

(lldb) frame variable one --summary NamedSummary

Enrico Granata

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

[diff] [blame]

972

(i_am_cool) one = x=3

973

</code>

974

Enrico Granata

f7a9b14

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

[diff] [blame]

975

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

976

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

977

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

978

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

979

summary name was the datatype that the summary is applied to

980

981

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

982

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

983

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

984

your program run again.

985

Enrico Granata

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

[diff] [blame]

</div>

</div>

Enrico Granata

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

[diff] [blame]

989

990

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

991

992

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

993

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

994

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

995

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

996

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

997

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

Enrico Granata

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

[diff] [blame]

998

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]

999

<code>

1000

(lldb) frame variable numbers -T

Enrico Granata

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

[diff] [blame]

1001

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

1002

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

1003

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

Enrico Granata

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

[diff] [blame]

1004

(int *) _M_start = 0x00000001001008a0

1005

(int *) _M_finish = 0x00000001001008a8

1006

(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

1012

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

1013

What you would like to see is probably something like:

1014

<code>

1015

(lldb) frame variable numbers -T

Enrico Granata

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

[diff] [blame]

1016

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

1024

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

1025

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

1026

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

1027

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]

1028

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

1029

must be implemented by the Python class):

1030

<code>

1031

class SyntheticChildrenProvider:

1032

def __init__(self, valobj, dict):

Enrico Granata

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

[diff] [blame]

1033

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]

1034

def num_children(self):

Enrico Granata

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

[diff] [blame]

1035

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]

1036

def get_child_index(self,name):

Enrico Granata

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

[diff] [blame]

1037

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]

1038

def get_child_at_index(self,index):

Enrico Granata

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

[diff] [blame]

1039

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]

1040

def update(self):

Enrico Granata

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

[diff] [blame]

1041

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]

1042

</code>

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1043

[1] This method is optional. Also, it may optionally choose to return a value (starting with LLDB SVN rev153061/LLDB-134). If it returns a value, and that value is <code>True</code>, 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, <code>None</code>, or anything other than <code>True</code> is returned, LLDB will discard the cached information and ask. Regardless, whenever necessary LLDB will call <code>update</code>.

Enrico Granata

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

[diff] [blame]

1044

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

415bb57

2012-03-17 02:04:20 +0000

[diff] [blame]

1045

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

1046

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

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1047

The design pattern consistently used in synthetic providers shipping with LLDB

1048

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

1049

to perform the actual initialization.

1050

1051

Enrico Granata

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

[diff] [blame]

1052

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

1053

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

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1054

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

Enrico Granata

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

[diff] [blame]

1055

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

1056

the provider class interactively while adding it.

1057

Enrico Granata

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

[diff] [blame]

1058

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

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1059

<code>Foo_Provider</code> is available, in a Python module contained in file <code>~/Foo_Tools.py</code>. The following interaction

Enrico Granata

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

[diff] [blame]

1060

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

Enrico Granata

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

[diff] [blame]

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1064

(lldb) command script import ~/Foo_Tools.py

Enrico Granata

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

[diff] [blame]

1065

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

1066

</td>

1067

<table>

1068

<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

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1076

<code>std::vector<T></code>, <code>std::list<T></code> and <code>std::map<K,V></code> 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>.

Enrico Granata

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

[diff] [blame]

1077

Enrico Granata

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

[diff] [blame]

1078

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

1079

This symbol tells LLDB to refer expression paths to the

1080

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"

1085

</td>

Enrico Granata

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

[diff] [blame]

1086

</table>

Enrico Granata

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

[diff] [blame]

1087

<code> (lldb) frame variable numbers

1088

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

1095

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

1096

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

1097

can benefit from this behavior, as in:

1098

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

1099

(int) numbers[0] = 1

1100

(int) numbers[1] = 12

1101

</code>

1102

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

1103

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

1104

<code> (lldb) expression numbers[0]

1105

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

1106

error: Couldn't convert the expression to DWARF

1107

</code>

1108

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

1109

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

Enrico Granata

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

[diff] [blame]

1110

</div>

1111

</div>

Enrico Granata

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

[diff] [blame]

1112

1113

1114

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

1115

Enrico Granata

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

[diff] [blame]

1116

Filters are a solution to the display of complex classes.

1117

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

1118

necessary for the user to see.

1119

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

1120

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

1121

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

1122

Python code.

1123

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

1124

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

1125

1126

Enrico Granata

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

[diff] [blame]

1127

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

Enrico Granata

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

[diff] [blame]

1128

</td>

Enrico Granata

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

[diff] [blame]

1129

</table>

Enrico Granata

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

[diff] [blame]

1130

<code> (lldb) frame variable a_foobar

1131

(Foobar) a_foobar = {

1132

(int) B = 1

1133

(char) H = 'H'

1134

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

1135

}

1136

</code>

Enrico Granata

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

[diff] [blame]

</div>

</div>

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

1142

1143

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

Enrico Granata

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

[diff] [blame]

1144

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

1145

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

1146

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

Enrico Granata

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

[diff] [blame]

1147

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

1148

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

1149

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

1150

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

1151

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

1152

<ul>

1153

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

1154

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

1155

code on the target is not required</li>

1156

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

1157

dynamic type discovery</li>

</ul>

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

1162

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

1163

for them. As an example:

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

1168

</td>

1169

</table>

1170

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

1171

</code>

1172

1173

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

1174

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

1175

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

1176

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

Enrico Granata

b62598b

2012-03-17 02:14:46 +0000

[diff] [blame]

1177

process. This features requires you to enable the AppKit category (see below for details). The

1178

Python code for this formatter is at <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/summaries/cocoa/CFString.py">

1179

CFString.py</a> (the script is well commented, but intricate and might not be obvious, lacking

1180

working experience with Cocoa and the LLDB API).

Enrico Granata

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

[diff] [blame]

1181

Enrico Granata

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

[diff] [blame]

</div>

</div>

Enrico Granata

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

[diff] [blame]

1185

1186

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

1187

1188

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

1189

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

1190

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

1191

or OS release.

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1192

By default, several categories are created in LLDB:

1193

<ul>

Enrico Granata

2012-05-02 21:13:16 +0000

[diff] [blame]

1194

<li><code>default</code>: this is the category where every formatter ends up, unless another category is specified

1195

<li><code>objc</code>: formatters for basic and common Objective-C types that do not specifically depend on Mac OS X

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1196

<li><code>gnu-libstdc++</code>: formatters for std::string, std::vector, std::list and std::map as implemented by libstdcpp

Enrico Granata

2012-05-02 21:13:16 +0000

[diff] [blame]

1197

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

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1198

<li><code>system</code>: truly basic types for which a formatter is required

Enrico Granata

2012-05-02 21:13:16 +0000

[diff] [blame]

1199

<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

1200

<li><a href="https://developer.apple.com/corefoundation/"><code>CoreFoundation</code></a>: CF classes

1201

<li><a href="https://developer.apple.com/library/mac/#documentation/CoreGraphics/Reference/CoreGraphicsConstantsRef/Reference/reference.html"><code>CoreGraphics</code></a>: CG classes

1202

<li><a href="http://developer.apple.com/library/mac/#documentation/Carbon/reference/CoreServicesReferenceCollection/_index.html"><code>CoreServices</code></a>: CS classes

1203

<li><code>VectorTypes</code>: compact display for several vector types

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1204

</ul>

Enrico Granata

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

[diff] [blame]

1205

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

1206

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

1207

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

1208

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

1209

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

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1210

the command to use is <code>type category disable</code>.

1211

The order in which categories are enabled or disabled

Enrico Granata

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

[diff] [blame]

1212

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

Enrico Granata

2012-05-02 21:13:16 +0000

[diff] [blame]

1213

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>CoreFoundation</li>

1218

<li>AppKit</li>

1219

<li>CoreServices</li>

1220

<li>CoreGraphics</li>

1221

<li>gnu-libstdc++</li>

<li>libcxx</li>

<li>VectorTypes</li>

<li>system</li>

</ul>

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1226

As said, <code>gnu-libstdc++</code> and <code>libcxx</code> contain formatters for C++ STL

Enrico Granata

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

[diff] [blame]

1227

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

Enrico Granata

2012-03-19 23:57:06 +0000

[diff] [blame]

1228

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

Enrico Granata

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

[diff] [blame]

1229

replace them with your own if so you wish.

Enrico Granata

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

[diff] [blame]

1230

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

1231

exist, it is automatically created. For instance,

1232

1233

1234

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

1235

</td>

1236

</table>

1237

automatically creates a (disabled) category named newcategory.

1238

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

1239

1240

1241

(lldb) type category enable newcategory

1242

</td>

1243

</table>

1244

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

1245

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

1246

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

1247

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]

1251

Enrico Granata

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

[diff] [blame]

1252

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

Enrico Granata

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

[diff] [blame]

1253

1254

While the rules for finding an appropriate format for a

1255

type are relatively simple (just go through typedef

Enrico Granata

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

[diff] [blame]

1256

hierarchies), searching other formatters goes through

Enrico Granata

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

[diff] [blame]

1257

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

1258

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

1259

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

1260

the following:

Enrico Granata

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

[diff] [blame]

1261

<ul>

Enrico Granata

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

[diff] [blame]

1262

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

Enrico Granata

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

[diff] [blame]

1263

use it</li>

Enrico Granata

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

[diff] [blame]

1264

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

Enrico Granata

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

[diff] [blame]

1265

for the pointee type that does not skip pointers, use

1266

it</li>

1267

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

Enrico Granata

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

[diff] [blame]

1268

formatter for the referred type that does not skip

Enrico Granata

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

[diff] [blame]

1269

references, use it</li>

Enrico Granata

f2cb7f2

2012-03-22 19:55:55 +0000

[diff] [blame]

1270

<li>If this object is an Objective-C class and dynamic types are enabled,

1271

look for a formatter for the dynamic type of the object. If dynamic types are disabled,

1272

or the search failed, look for a formatter for the declared type of the object</li>

Enrico Granata

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

[diff] [blame]

1273

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

Enrico Granata

86e7c3e

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

[diff] [blame]

1274

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

1275

the compiler has not emitted enough information. If the

1276

required information to traverse typedef hierarchies is

1277

missing, type cascading will not work. The

1278

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

1279

part of the LLVM project, emits the correct debugging

Enrico Granata

f2cb7f2

2012-03-22 19:55:55 +0000

[diff] [blame]

1280

information for LLDB to cascade). If at any level of the hierarchy

1281

there is a valid formatter that can cascade, use it.</li>

Enrico Granata

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

[diff] [blame]

1282

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

1283

looking for regular expressions instead of exact

1284

matches</li>

1285

</ul>

Enrico Granata

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

[diff] [blame]

1286

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

1287

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

1288

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

1289

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

1290

more enabled categories, the search has failed.

Enrico Granata

f2cb7f2

2012-03-22 19:55:55 +0000

[diff] [blame]

1291

Warning: previous versions of LLDB defined cascading to mean

1292

not only going through typedef chains, but also through inheritance chains.

1293

This feature has been removed since it significantly degrades performance.

1294

You need to set up your formatters for every type in inheritance chains to which

1295

you want the formatter to apply.

Enrico Granata

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

[diff] [blame]

1296

</div>

1297

</div>

Enrico Granata