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

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

[diff] [blame]

100

This is done by typing

101

102

103

(lldb) type format add -f hex int

104

</td>

105

<table>

106

at the LLDB command line.

Enrico Granata

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

[diff] [blame]

107

108

The <code>-f</code> option accepts a <a

109

href="#formatstable">format name</a>, and a list of

110

types to which you want the new format applied.

111

112

A frequent scenario is that your program has a <code>typedef</code>

113

for a numeric type that you know represents something

114

that must be printed in a certain way. Again, you can

115

add a format just to that typedef by using <code>type

116

format add</code> with the name alias.

117

118

But things can quickly get hierarchical. Let's say you

119

have a situation like the following:

<code>typedef int A;

typedef A B;

typedef B C;

typedef C D;

</code>

and you want to show all <code>A</code>'s as hex, all

128

<code>C'</code>s as pointers and leave the defaults

129

untouched for other types.

130

131

If you simply type

Enrico Granata

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

[diff] [blame]

132

133

134

(lldb) type format add -f hex A

135

(lldb) type format add -f pointer C

136

</td>

137

<table>

Enrico Granata

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

[diff] [blame]

138

139

values of type <code>B</code> will be shown as hex

140

and values of type <code>D</code> as pointers.

141

142

This is because by default LLDB cascades

143

formats through typedef chains. In order to avoid that

144

you can use the option <code>-C no</code> to prevent

145

cascading, thus making the two commands required to

146

achieve your goal:

Enrico Granata

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

[diff] [blame]

147

148

149

(lldb) type format add -C no -f hex A

150

(lldb) type format add -C no -f pointer C

151

</td>

152

<table>

Enrico Granata

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

[diff] [blame]

153

154

Two additional options that you will want to look at

155

are <code>-p</code> and <code>-r</code>. These two

156

options prevent LLDB from applying a format for type <code>T</code>

157

to values of type <code>T*</code> and <code>T&</code>

158

respectively.

159

160

<code> (lldb) type format add -f float32[]

161

int

162

(lldb) fr var pointer *pointer -T

163

(int *) pointer = {1.46991e-39 1.4013e-45}

164

(int) *pointer = {1.53302e-42}

165

(lldb) type format add -f float32[] int -p

166

(lldb) fr var pointer *pointer -T

167

(int *) pointer = 0x0000000100100180

168

(int) *pointer = {1.53302e-42}

169

</code>

170

171

As the previous example highlights, you will most

172

probably want to use <code>-p</code> for your formats.

173

174

If you need to delete a custom format simply type <code>type

175

format delete</code> followed by the name of the type

176

to which the format applies. To delete ALL formats, use

177

<code>type format clear</code>. To see all the formats

178

defined, type <code>type format list</code>.

179

180

181

If all you need to do, however, is display one variable

182

in a custom format, while leaving the others of the same

183

type untouched, you can simply type:

184

Enrico Granata

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

[diff] [blame]

185

186

187

(lldb) frame variable counter -f hex

188

</td>

189

<table>

Enrico Granata

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

[diff] [blame]

190

191

This has the effect of displaying the value of <code>counter</code>

192

as an hexadecimal number, and will keep showing it this

193

way until you either pick a different format or till you

194

let your program run again.

195

196

Finally, this is a list of formatting options available

197

out of

198

which you can pick:<a name="formatstable"></a>

<tbody>

<td width="23%">Format name</td>

203

<td>Abbreviation</td>

<td>Description</td>

</tr>

<td>default</td>

<td>

</td>

<td>the default LLDB algorithm is used to pick a

format</td>

</tr>

<td>boolean</td>

<td>show this as a true/false boolean, using the

217

customary rule that 0 is false and everything else

is true</td>

</tr>

<td>binary</td>

<td>show this as a sequence of bits</td>

</tr>

<td>bytes</td>

<td>show the bytes one after the other

229

e.g. <code>(int) s.x = 07 00 00 00</code></td>

230

</tr>

231

232

<td>bytes with ASCII</td>

233

234

<td>show the bytes, but try to print them as ASCII

235

characters

236

e.g. <code>(int *) c.sp.x = 50 f8 bf 5f ff 7f 00

237

00 P.._....</code></td>

</tr>

<td>character</td>

<td>show the bytes printed as ASCII characters

243

e.g. <code>(int *) c.sp.x =

244

P\xf8\xbf_\xff\x7f\0\0</code></td>

245

</tr>

246

247

<td>printable character</td>

248

249

<td>show the bytes printed as printable ASCII

250

characters

251

e.g. <code>(int *) c.sp.x = P.._....</code></td>

252

</tr>

253

254

<td>complex float</td>

255

256

<td>interpret this value as the real and imaginary

257

part of a complex floating-point number

258

e.g. <code>(int *) c.sp.x = 2.76658e+19 +

259

4.59163e-41i</code></td>

</tr>

<td>c-string</td>

<td>show this as a 0-terminated C string</td>

265

</tr>

266

267

<td>signed decimal</td>

268

269

<td>show this as a signed integer number (this does

270

not perform a cast, it simply shows the bytes as

signed integer)</td>

</tr>

<td>enumeration</td>

<td>show this as an enumeration, printing the

277

value's name if available or the integer value

278

otherwise

279

e.g. <code>(enum enumType) val_type = eValue2</code></td>

</tr>

<td>show this as in hexadecimal notation (this does

285

not perform a cast, it simply shows the bytes as

hex)</td>

</tr>

<td>float</td>

<td>show this as a floating-point number (this does

292

not perform a cast, it simply interprets the bytes

293

as an IEEE754 floating-point value)</td>

</tr>

<td>octal</td>

<td>show this in octal notation</td>

</tr>

<td>OSType</td>

<td>show this as a MacOS OSType

304

e.g. <code>(float) *c.sp.y = '\n\x1f\xd7\n'</code></td>

</tr>

<td>unicode16</td>

<td>show this as UTF-16 characters

310

e.g. <code>(float) *c.sp.y = 0xd70a 0x411f</code></td>

</tr>

<td>unicode32</td>

<td>

</td>

<td>show this as UTF-32 characters

317

e.g. <code>(float) *c.sp.y = 0x411fd70a</code></td>

318

</tr>

319

320

<td>unsigned decimal</td>

321

322

<td>show this as an unsigned integer number (this

323

does not perform a cast, it simply shows the bytes

324

as unsigned integer)</td>

</tr>

<td>pointer</td>

<td>show this as a native pointer (unless this is

330

really a pointer, the resulting address will

331

probably be invalid)</td>

</tr>

<td>

</td>

<td>show this as an array of characters

338

e.g. <code>(char) *c.sp.z = {X}</code></td>

339

</tr>

340

341

<td>int8_t[], uint8_t[]

342

int16_t[], uint16_t[]

343

int32_t[], uint32_t[]

344

int64_t[], uint64_t[]

uint128_t[]</td>

<td>

</td>

<td>show this as an array of the corresponding

349

integer type

350

e.g.

351

<code>(int) sarray[0].x = {1 0 0 0}</code>

352

<code>(int) sarray[0].x = {0x00000001}</code></td>

353

</tr>

354

355

<td>float32[], float64[]</td>

356

<td>

357

</td>

358

<td>show this as an array of the corresponding

359

floating-point type

360

e.g. <code>(int *) pointer = {1.46991e-39

361

1.4013e-45}</code></td>

362

</tr>

363

364

<td>complex integer</td>

365

366

<td>interpret this value as the real and imaginary

367

part of a complex integer number

368

e.g. <code>(int *) pointer = 1048960 + 1i</code></td>

369

</tr>

370

371

<td>character array</td>

372

373

<td>show this as a character array

374

e.g. <code>(int *) pointer =

375

\x80\x01\x10\0\x01\0\0\0</code></td>

</tr>

</tbody>

</table>

</div>

</div>

<h1 class="postheader">type summary</h1>

384

Enrico Granata

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

[diff] [blame]

385

Type formats work by showing a different kind of display for

386

the value of a variable. However, they only work for basic types.

387

When you want to display a class or struct in a custom format, you

388

cannot do that using formats.

389

A different feature, type summaries, works by extracting

390

information from classes, structures, ... (aggregate types)

391

and arranging it in a user-defined format, as in the following example:

Enrico Granata

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

[diff] [blame]

392

before adding a summary...

393

<code> (lldb) fr var -T one

394

(i_am_cool) one = {

Enrico Granata

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

[diff] [blame]

395

(int) integer = 3

396

(float) floating = 3.14159

397

(char) character = 'E'

Enrico Granata

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

[diff] [blame]

398

}

399

</code>

400

after adding a summary...

401

<code> (lldb) fr var one

402

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

403

</code>

Enrico Granata

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

[diff] [blame^]

404

405

There are two ways to use type summaries: the first one is to bind a

406

summary string to the datatype; the second is to bind a Python script to the

407

datatype. Both options are enabled by the <code>type summary add</code>

Enrico Granata

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

[diff] [blame]

408

command.

Enrico Granata

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

[diff] [blame]

409

In the example, the command we type was:

410

411

Enrico Granata

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

[diff] [blame]

412

(lldb) type summary add -f "int = ${var.integer}, float = ${var.floating}, char = ${var.character%u}" i_am_cool

Enrico Granata

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

[diff] [blame]

413

</td>

414

<table>

Enrico Granata

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

[diff] [blame^]

415

416

Initially, we will focus on summary strings, and then describe the Python binding

417

mechanism.

418

Enrico Granata

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

[diff] [blame]

</div>

</div>

<h1 class="postheader">Summary Strings</h1>

423

Enrico Granata

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

[diff] [blame]

424

While you may already have guessed a lot about the format of

425

summary strings from the above example, a detailed description

426

of their format follows.

427

428

Summary strings can contain plain text, control characters and

Enrico Granata

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

[diff] [blame]

429

special symbols that have access to information about

430

the current object and the overall program state.

431

Normal characters are any text that doesn't contain a <code>'{'</code>,

432

433

character.

434

Variable names are found in between a <code>"${"</code>

435

prefix, and end with a <code>"}"</code> suffix.

436

In other words, a variable looks like <code>"${frame.pc}"</code>.

437

Basically, all the variables described in <a

438

href="formats.html">Frame and Thread Formatting</a>

439

are accepted. Also acceptable are the control characters

440

and scoping features described in that page.

441

Additionally, <code>${var</code> and <code>${*var</code>

442

become acceptable symbols in this scenario.

443

The simplest thing you can do is grab a member variable

444

of a class or structure by typing its expression

445

path. In the previous example, the expression path

Enrico Granata

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

[diff] [blame]

446

for the floating member is simply <code>.floating</code>.

447

Thus, to ask the summary string to display <code>floating</code>

Enrico Granata

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

[diff] [blame]

448

you would type <code>${var.floating}</code> (<code>${var</code>

449

is a placeholder token replaced with whatever variable

450

is being displayed).

451

If you have code like the following:

452

<code> struct A {

Enrico Granata

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

[diff] [blame]

453

int x;

454

int y;

Enrico Granata

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

[diff] [blame]

455

};

456

struct B {

Enrico Granata

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

[diff] [blame]

457

A x;

458

A y;

459

int z;

Enrico Granata

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

[diff] [blame]

460

};

461

</code> the expression path for the <code>y</code>

462

member of the <code>x</code> member of an object of

463

type <code>B</code> would be <code>.x.y</code> and you

464

would type <code>${var.x.y}</code> to display it in a

465

summary string for type <code>B</code>.

466

As you could be using a summary string for both

467

displaying objects of type <code>T</code> or <code>T*</code>

468

(unless <code>-p</code> is used to prevent this), the

469

expression paths do not differentiate between <code>.</code>

470

and <code>-></code>, and the above expression path <code>.x.y</code>

471

would be just as good if you were displaying a <code>B*</code>,

472

or even if the actual definition of <code>B</code>

473

were: <code>

474

struct B {

Enrico Granata

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

[diff] [blame]

475

A *x;

476

A y;

477

int z;

Enrico Granata

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

[diff] [blame]

478

};

479

</code>

480

This is unlike the behaviour of <code>frame variable</code>

481

which, on the contrary, will enforce the distinction. As

482

hinted above, the rationale for this choice is that

483

waiving this distinction enables one to write a summary

484

string once for type <code>T</code> and use it for both

485

<code>T</code> and <code>T*</code> instances. As a

486

summary string is mostly about extracting nested

487

members' information, a pointer to an object is just as

488

good as the object itself for the purpose.

489

Of course, you can have multiple entries in one summary

Enrico Granata

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

[diff] [blame]

490

string, as shown in the previous example.

Enrico Granata

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

[diff] [blame]

491

As you can see, the last expression path also contains

492

a <code>%u</code> symbol which is nowhere to be found

493

in the actual member variable name. The symbol is

494

reminding of a <code>printf()</code> format symbol, and

495

in fact it has a similar effect. If you add a % sign

496

followed by any one format name or abbreviation from the

497

above table after an expression path, the resulting

Enrico Granata

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

[diff] [blame]

498

object will be displyed using the chosen format (this is

499

applicable to non-aggregate types only, with a few

500

special exceptions discussed below).

Enrico Granata

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

[diff] [blame]

501

There are two more special format symbols that you can

502

use only as part of a summary string: <code>%V</code>

503

and <code>%@</code>. The first one tells LLDB to ignore

504

summary strings for the type of the object referred by

505

the expression path and instead print the object's

506

value. The second is only applicable to Objective-C

507

classes, and tells LLDB to get the object's description

508

from the Objective-C runtime. By default, if no format

509

is provided, LLDB will try to get the object's summary,

510

and if empty the object's value. If neither can be

511

obtained, nothing will be displayed.

512

As previously said, pointers and values are treated the

513

same way when getting to their members in an expression

514

path. However, if your expression path leads to a

515

pointer, LLDB will not automatically dereference it. In

516

order to obtain The deferenced value for a pointer, your

517

expression path must start with <code>${*var</code>

518

instead of <code>${var</code>. Because there is no need

519

to dereference pointers along your way, the

520

dereferencing symbol only applies to the result of the

521

whole expression path traversing.

522

e.g. <code>

523

(lldb) fr var -T c

524

(Couple) c = {

Enrico Granata

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

[diff] [blame]

525

(SimpleWithPointers) sp = {

526

(int *) x = 0x00000001001000b0

527

(float *) y = 0x00000001001000c0

528

(char *) z = 0x00000001001000d0 "X"

529

}

530

(Simple *) s = 0x00000001001000e0

Enrico Granata

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

[diff] [blame]

531

}

Enrico Granata

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

[diff] [blame]

532

</code>

533

534

If one types the following commands:

(lldb) type summary add -f "int = ${*var.sp.x},

Enrico Granata

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

[diff] [blame]

539

float = ${*var.sp.y}, char = ${*var.sp.z%u}, Simple =

540

${*var.s}" Couple

Enrico Granata

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

[diff] [blame]

541

(lldb) type summary add -c -p Simple

</td>

<table>

the output becomes: <code>

546

Enrico Granata

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

[diff] [blame]

547

(lldb) fr var c

548

(Couple) c = int = 9, float = 9.99, char = 88, Simple

549

= (x=9, y=9.99, z='X')

550

</code>

551

Option <code>-c</code> to <code>type summary add</code>

552

tells LLDB not to look for a summary string, but instead

553

to just print a listing of all the object's children on

Enrico Granata

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

[diff] [blame]

554

one line, as shown in the summary for object Simple.

555

We are using the <code>-p</code> flag here to show that

556

aggregate types can be dereferenced as well as basic types.

557

The following command sequence would work just as well and

558

produce the same output:

559

560

561

(lldb) type summary add -f "int = ${*var.sp.x},

562

float = ${*var.sp.y}, char = ${*var.sp.z%u}, Simple =

563

${var.s}" Couple

564

(lldb) type summary add -c Simple

565

</td>

566

<table>

Enrico Granata

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

[diff] [blame]

</div>

</div>

Enrico Granata

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

[diff] [blame]

570

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

Enrico Granata

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

[diff] [blame]

571

Enrico Granata

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

[diff] [blame]

572

Sometimes, a basic type's value actually represents

573

several different values packed together in a bitfield.

574

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

575

them. Hexadecimal display can help, but if the bits

576

actually span byte boundaries, the help is limited.

577

Binary view would show it all without ambiguity, but is

578

often too detailed and hard to read for real-life

579

scenarios. To cope with the issue, LLDB supports native

580

bitfield formatting in summary strings. If your

581

expression paths leads to a so-called scalar type

582

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

583

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

584

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

585

display them in any format you like. The syntax is

586

similar to that used for arrays, just you can also give

587

a pair of indices separated by a <code>-</code>.

588

e.g.

589

<code> (lldb) fr var float_point

Enrico Granata

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

[diff] [blame]

590

(float) float_point = -3.14159 </code>

591

592

593

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

Enrico Granata

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

[diff] [blame]

594

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

Enrico Granata

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

[diff] [blame]

float

</td>

<table>

<code>

Enrico Granata

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

[diff] [blame]

600

(lldb) fr var float_point

601

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

602

0x00000080 Mantissa: 4788184

603

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

604

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

Enrico Granata

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

[diff] [blame]

605

extracting bitfields out of a float object.

606

607

As far as the syntax is concerned, it looks

608

much like the normal C array syntax, but also allows you

609

to specify 2 indices, separated by a - symbol (a range).

610

Ranges can be given either with the lower or the higher index

611

first, and range extremes are always included in the bits extracted.

612

613

LLDB also allows to use a similar syntax to display

Enrico Granata

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

[diff] [blame]

614

array members inside a summary string. For instance, you

615

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

616

more compact notation than the default, and then just

617

delve into individual array members that prove

Enrico Granata

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

[diff] [blame]

618

interesting to your debugging task. You can tell

619

LLDB to format arrays in special ways, possibly

620

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

Enrico Granata

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

[diff] [blame]

621

e.g.

622

<code> (lldb) fr var sarray

623

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

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

[3]"

</td>

<table>

<code>

Enrico Granata

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

[diff] [blame]

649

(lldb) fr var sarray

Enrico Granata

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

[diff] [blame]

650

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

651

652

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

Enrico Granata

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

[diff] [blame]

653

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

654

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

655

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

656

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

657

If you find some of those integers anomalous, you can

658

then inspect that one item in greater detail, without

659

the array format getting in the way:

660

<code> (lldb) fr var sarray[1]

661

(Simple) sarray[1] = {

Enrico Granata

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

[diff] [blame]

662

x = 4

663

y = 5

664

z = '\x06'

Enrico Granata

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

[diff] [blame]

665

}

666

</code>

667

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

668

array range by using the same syntax used to extract bit

Enrico Granata

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

[diff] [blame]

for bitfields:

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

[3]"

</td>

<table>

<code>

(lldb) fr var sarray

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

679

Enrico Granata

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

[diff] [blame]

680

The same logic works if you are printing a pointer

Enrico Granata

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

[diff] [blame]

681

instead of an array, however in this latter case, the empty

682

square brackets operator <code>[]</code>

Enrico Granata

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

[diff] [blame]

683

cannot be used and you need to give exact range limits.

Enrico Granata

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

[diff] [blame]

684

685

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

686

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

687

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

688

<ul>

689

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

690

omitting square brackets, as in:

691

692

693

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

</td>

<table>

This works for <code>char*</code> and <code>char[]</code> objects, and uses the

698

<code>\0</code> terminator

699

when possible to terminate the string, instead of relying on array length.

</li> </ul>

<ul>

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

705

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

706

and <code>a</code> formats

707

work to print an array of a non-aggregate

708

type, even if square brackets are omitted.

709

710

711

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

</td>

<table>

</ul>

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

717

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

718

719

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

720

specify the square brackets operator to get the expected output.

</div>

</div>

Enrico Granata

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

[diff] [blame^]

726

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

Enrico Granata

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

[diff] [blame]

727

Enrico Granata

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

[diff] [blame^]

728

729

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

730

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

731

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

732

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

733

some computation on the value of variables.

734

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

735

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

736

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

737

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

<code>

class Rectangle

{

private:

int height;

int width;

public:

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

747

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

748

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

749

750

int GetHeight() { return height; }

751

int GetWidth() { return width; }

};

</code>

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

757

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

758

area, perimeter and length of diagonal of <code>Rectangle</code> objects

759

760

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

761

class, as shown in this example:

(lldb) type summary add -P Rectangle

766

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

767

def function (valobj,dict):

768

height_val = valobj.GetChildMemberWithName('height')

769

width_val = valobj.GetChildMemberWithName('width')

770

height_str = height_val.GetValue()

771

width_str = width_val.GetValue()

772

height = int(height_str)

773

width = int(width_str)

774

area = height*width

775

perimeter = 2*height + 2*width

776

diag = sqrt(height*height+width*width)

777

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

778

DONE

779

(lldb) script

780

Python Interactive Interpreter. To exit, type 'quit()', 'exit()' or Ctrl-D.

781

>>> from math import sqrt

782

>>> quit()

783

(lldb) frame variable

784

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

785

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

786

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

</td>

</table>

In this scenario, you need to enter the interactive interpreter to import the

791

function sqrt() from the math library. As the example shows, everything you enter

792

into the interactive interpreter is saved for you to use it in scripts. This way

793

you can define your own utility functions and use them in your summary scripts if

794

necessary.

795

796

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

797

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

798

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

799

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

800

801

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

802

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

803

804

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

805

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

806

variable being displayed, and its type is SBValue. The most important thing you can

807

do with an SBValue is retrieve its children objects, by calling

808

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

809

it for its value, by calling <code>GetValue()</code>, which returns a Python string.

810

811

812

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

813

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

814

an expression path just like those you could use for summary strings. However, if you need

815

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

816

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

817

818

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

819

to input a Python script as a summary:

820

821

<ul>

822

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

823

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

(lldb) type summary add -s "height =

828

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

829

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

830

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

</td>

</table>

<ul>

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

835

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

836

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

837

loaded it from a file.

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

845

846

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

847

Enrico Granata

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

[diff] [blame]

848

As you noticed, in order to associate the custom

849

summary string to the array types, one must give the

850

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

851

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

852

853

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

854

[12]</code>, ...

855

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

856

treated as regular expressions instead of type names.

Enrico Granata

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

[diff] [blame]

857

This would let you rephrase the above example

858

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

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

863

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

</td>

<table>

<code>

Enrico Granata

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

[diff] [blame]

868

(lldb) fr var sarray

869

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

870

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

871

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

872

objects.

873

While this feature is mostly useful for arrays, you

874

could also use regular expressions to catch other type

875

sets grouped by name. However, as regular expression

876

matching is slower than normal name matching, LLDB will

877

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

878

when this fails, will it resort to regular expression

879

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

880

cascading summary, this will be preferred over any

881

regular expression match for your type itself.

882

</div>

883

</div>

Enrico Granata

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

[diff] [blame]

884

885

886

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

887

888

For a given datatype, there may be different meaningful summary

889

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

890

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

891

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

892

you can use named summaries.

893

894

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

895

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

896

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

897

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

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

902

</td>

903

<table>

904

<code> (lldb) fr var one

905

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

906

(lldb) fr var one --summary NamedSummary

907

(i_am_cool) one = x=3

908

</code>

909

Enrico Granata

f7a9b14

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

[diff] [blame]

910

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

911

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

912

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

913

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

914

summary name was the datatype that the summary is applied to

915

916

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

917

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

918

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

919

your program run again.

920

Enrico Granata

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

[diff] [blame]

</div>

</div>

Enrico Granata

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

[diff] [blame]

925

926

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

927

928

While the rules for finding an appropriate format for a

929

type are relatively simple (just go through typedef

930

hierarchies), summaries follow a more complicated

931

process in finding the right summary string for a

932

variable. Namely, what happens is:

933

<ul>

934

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

935

use it</li>

936

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

937

for the pointee type that does not skip pointers, use

938

it</li>

939

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

940

summary for the pointee type that does not skip

941

references, use it</li>

942

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

943

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

944

...)</li>

945

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

946

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

947

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

948

classes, look at the virtual base classes (and bases

949

of bases, ...)</li>

950

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

Enrico Granata

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

[diff] [blame]

951

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

952

the compiler has not emitted enough information. If the

953

required information to traverse typedef hierarchies is

954

missing, type cascading will not work. The

955

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

956

part of the LLVM project, emits the correct debugging

957

information for LLDB to cascade)</li>

Enrico Granata

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

[diff] [blame]

958

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

959

looking for regular expressions instead of exact

matches</li>

</ul>

</div>

</div>

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

966

967

<ul>

968

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

969

need to be careful what the dereferencing operation is

970

binding to in complicated scenarios</li>

Enrico Granata

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

[diff] [blame]

971

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

972

option</li>

Enrico Granata

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

[diff] [blame^]

973

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

974

string</li></strike>

Enrico Granata