Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| 2 | <html xmlns="http://www.w3.org/1999/xhtml"> |
| 3 | <head> |
| 4 | <meta http-equiv="Content-Type" content="text/html; |
| 5 | charset=ISO-8859-1"> |
| 6 | <link href="style.css" rel="stylesheet" type="text/css"> |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 7 | <title>LLDB Data Formatters</title> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 8 | </head> |
| 9 | <body> |
| 10 | <div class="www_title"> The <strong>LLDB</strong> Debugger </div> |
| 11 | <div id="container"> |
| 12 | <div id="content"> |
| 13 | <!--#include virtual="sidebar.incl"--> |
| 14 | <div id="middle"> |
| 15 | <div class="post"> |
| 16 | <h1 class="postheader">Variable display</h1> |
| 17 | <div class="postcontent"> |
| 18 | |
| 19 | <p>LLDB was recently modified to allow users to define custom |
| 20 | formatting options for the variables display.</p> |
| 21 | |
| 22 | <p>Usually, when you type <code>frame variable</code> or |
| 23 | run some <code>expression</code> LLDB will |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 24 | automatically choose the way to display your results on |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 25 | a per-type basis, as in the following example:</p> |
| 26 | |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 27 | <p> <code> <b>(lldb)</b> frame variable<br> |
| 28 | (uint8_t) x = 'a'<br> |
| 29 | (intptr_t) y = 124752287<br> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 30 | </code> </p> |
| 31 | |
| 32 | <p>However, in certain cases, you may want to associate a |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 33 | different style to the display for certain datatypes. |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 34 | To do so, you need to give hints to the debugger as to |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 35 | how variables should be displayed.<br> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 36 | A new <b>type</b> command has been introduced in LLDB |
| 37 | which allows to do just that.<br> |
| 38 | </p> |
| 39 | |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 40 | <p>Using it you can change your visualization to look like this: </p> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 41 | |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 42 | <p> <code> <b>(lldb)</b> frame variable<br> |
| 43 | (uint8_t) x = chr='a' dec=65 hex=0x41<br> |
| 44 | (intptr_t) y = 0x76f919f<br> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 45 | </code> </p> |
| 46 | |
Enrico Granata | 68506fb | 2011-08-22 16:10:25 +0000 | [diff] [blame] | 47 | <p>There are several features related to data visualization: <span |
| 48 | style="font-style: italic;">formats</span>, <span |
| 49 | style="font-style: italic;">summaries</span>, <span |
| 50 | style="font-style: italic;">filters</span>, <span |
| 51 | style="font-style: italic;">synthetic children</span>.</p> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 52 | |
Enrico Granata | 0c5c9a2 | 2011-09-08 00:50:01 +0000 | [diff] [blame] | 53 | <p>To reflect this, the <b>type</b> command has four |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 54 | subcommands:<br> |
| 55 | </p> |
| 56 | |
| 57 | <p><code>type format</code></p> |
| 58 | <p><code>type summary</code></p> |
Enrico Granata | 68506fb | 2011-08-22 16:10:25 +0000 | [diff] [blame] | 59 | <p><code>type filter</code></p> |
| 60 | <p><code>type synthetic</code></p> |
| 61 | |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 62 | |
| 63 | <p>These commands are meant to bind printing options to |
| 64 | types. When variables are printed, LLDB will first check |
| 65 | if custom printing options have been associated to a |
| 66 | variable's type and, if so, use them instead of picking |
| 67 | the default choices.<br> |
| 68 | </p> |
| 69 | |
Enrico Granata | 68506fb | 2011-08-22 16:10:25 +0000 | [diff] [blame] | 70 | <p>Each of the commands has four subcommands available:<br> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 71 | </p> |
| 72 | <p><code>add</code>: associates a new printing option to one |
| 73 | or more types</p> |
| 74 | <p><code>delete</code>: deletes an existing association</p> |
| 75 | <p><code>list</code>: provides a listing of all |
| 76 | associations</p> |
| 77 | <p><code>clear</code>: deletes all associations</p> |
| 78 | </div> |
| 79 | </div> |
| 80 | |
| 81 | <div class="post"> |
| 82 | <h1 class="postheader">type format</h1> |
| 83 | <div class="postcontent"> |
| 84 | |
| 85 | <p>Type formats enable you to quickly override the default |
| 86 | format for displaying primitive types (the usual basic |
Enrico Granata | 0c5c9a2 | 2011-09-08 00:50:01 +0000 | [diff] [blame] | 87 | C/C++/ObjC types: <code><font color="blue">int</font></code>, <code><font color="blue">float</font></code>, <code><font color="blue">char</font></code>, ...).</p> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 88 | |
| 89 | <p>If for some reason you want all <code>int</code> |
| 90 | variables in your program to print out as hex, you can add |
| 91 | a format to the <code>int</code> type.<br></p> |
| 92 | |
Enrico Granata | 86e7c3e | 2011-07-12 22:56:10 +0000 | [diff] [blame] | 93 | <p>This is done by typing |
| 94 | <table class="stats" width="620" cellspacing="0"> |
| 95 | <td class="content"> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 96 | <b>(lldb)</b> type format add --format hex int |
Enrico Granata | 86e7c3e | 2011-07-12 22:56:10 +0000 | [diff] [blame] | 97 | </td> |
| 98 | <table> |
| 99 | at the LLDB command line.</p> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 100 | |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 101 | <p>The <code>--format</code> (which you can shorten to <code>-f</code>) option accepts a <a |
| 102 | href="#formatstable">format name</a>. Then, you provide one or more |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 103 | types to which you want the new format applied.</p> |
| 104 | |
| 105 | <p>A frequent scenario is that your program has a <code>typedef</code> |
| 106 | for a numeric type that you know represents something |
| 107 | that must be printed in a certain way. Again, you can |
| 108 | add a format just to that typedef by using <code>type |
| 109 | format add</code> with the name alias.</p> |
| 110 | |
| 111 | <p>But things can quickly get hierarchical. Let's say you |
| 112 | have a situation like the following:</p> |
| 113 | |
Enrico Granata | 0c5c9a2 | 2011-09-08 00:50:01 +0000 | [diff] [blame] | 114 | <p><code><font color="blue">typedef int</font> A;<br> |
| 115 | <font color="blue">typedef</font> A B;<br> |
| 116 | <font color="blue">typedef</font> B C;<br> |
| 117 | <font color="blue">typedef</font> C D;<br> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 118 | </code></p> |
| 119 | |
| 120 | <p>and you want to show all <code>A</code>'s as hex, all |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 121 | <code>C'</code>s as byte arrays and leave the defaults |
Enrico Granata | 0c5c9a2 | 2011-09-08 00:50:01 +0000 | [diff] [blame] | 122 | untouched for other types (albeit its contrived look, the example is far |
| 123 | from unrealistic in large software systems).</p> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 124 | |
| 125 | <p>If you simply type <br> |
Enrico Granata | 86e7c3e | 2011-07-12 22:56:10 +0000 | [diff] [blame] | 126 | <table class="stats" width="620" cellspacing="0"> |
| 127 | <td class="content"> |
| 128 | <b>(lldb)</b> type format add -f hex A<br> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 129 | <b>(lldb)</b> type format add -f uint8_t[] C |
Enrico Granata | 86e7c3e | 2011-07-12 22:56:10 +0000 | [diff] [blame] | 130 | </td> |
| 131 | <table> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 132 | <br> |
| 133 | values of type <code>B</code> will be shown as hex |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 134 | and values of type <code>D</code> as byte arrays, as in:</p> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 135 | |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 136 | <p> <code> |
| 137 | <b>(lldb)</b> frame variable -T<br/> |
| 138 | (A) a = 0x00000001<br/> |
| 139 | (B) b = 0x00000002<br/> |
| 140 | (C) c = {0x03 0x00 0x00 0x00}<br/> |
| 141 | (D) d = {0x04 0x00 0x00 0x00}<br/> |
| 142 | </code> </p> |
| 143 | |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 144 | <p>This is because by default LLDB <i>cascades</i> |
| 145 | formats through typedef chains. In order to avoid that |
| 146 | you can use the option <code>-C no</code> to prevent |
| 147 | cascading, thus making the two commands required to |
| 148 | achieve your goal:<br> |
Enrico Granata | 86e7c3e | 2011-07-12 22:56:10 +0000 | [diff] [blame] | 149 | <table class="stats" width="620" cellspacing="0"> |
| 150 | <td class="content"> |
| 151 | <b>(lldb)</b> type format add -C no -f hex A<br> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 152 | <b>(lldb)</b> type format add -C no -f uint8_t[] C |
Enrico Granata | 86e7c3e | 2011-07-12 22:56:10 +0000 | [diff] [blame] | 153 | </td> |
| 154 | <table> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 155 | |
| 156 | <p>which provides the desired output:</p> |
| 157 | <p> <code> |
| 158 | <b>(lldb)</b> frame variable -T<br/> |
| 159 | (A) a = 0x00000001<br/> |
| 160 | (B) b = 2<br/> |
| 161 | (C) c = {0x03 0x00 0x00 0x00}<br/> |
| 162 | (D) d = 4<br/> |
| 163 | </code> </p> |
| 164 | |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 165 | <p>Two additional options that you will want to look at |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 166 | are <code>--skip-pointers</code> (<code>-p</code>) and <code>--skip-references</code> (<code>-r</code>). These two |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 167 | options prevent LLDB from applying a format for type <code>T</code> |
| 168 | to values of type <code>T*</code> and <code>T&</code> |
| 169 | respectively.</p> |
| 170 | |
| 171 | <p> <code> <b>(lldb)</b> type format add -f float32[] |
| 172 | int<br> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 173 | <b>(lldb)</b> frame variable pointer *pointer -T<br> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 174 | (int *) pointer = {1.46991e-39 1.4013e-45}<br> |
| 175 | (int) *pointer = {1.53302e-42}<br> |
| 176 | <b>(lldb)</b> type format add -f float32[] int -p<br> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 177 | <b>(lldb)</b> frame variable pointer *pointer -T<br> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 178 | (int *) pointer = 0x0000000100100180<br> |
| 179 | (int) *pointer = {1.53302e-42}<br> |
| 180 | </code> </p> |
| 181 | |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 182 | <p>While they can be applied to pointers and references, formats will make no attempt |
| 183 | to dereference the pointer and extract the value before applying the format, which means you |
| 184 | are effectively formatting the address stored in the pointer rather than the pointee value. |
Enrico Granata | 0c5c9a2 | 2011-09-08 00:50:01 +0000 | [diff] [blame] | 185 | For this reason, you may want to use the <code>-p</code> option when defining formats.</p> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 186 | |
| 187 | <p>If you need to delete a custom format simply type <code>type |
| 188 | format delete</code> followed by the name of the type |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 189 | to which the format applies.Even if you |
| 190 | defined the same format for multiple types on the same command, |
| 191 | <code>type format delete</code> will only remove the format for |
| 192 | the type name passed as argument.<br> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 193 | </p> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 194 | <p> |
| 195 | To delete ALL formats, use |
| 196 | <code>type format clear</code>. To see all the formats |
| 197 | defined, use <code>type format list</code>.</p> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 198 | |
| 199 | <p>If all you need to do, however, is display one variable |
| 200 | in a custom format, while leaving the others of the same |
| 201 | type untouched, you can simply type:<br> |
| 202 | <br> |
Enrico Granata | 86e7c3e | 2011-07-12 22:56:10 +0000 | [diff] [blame] | 203 | <table class="stats" width="620" cellspacing="0"> |
| 204 | <td class="content"> |
| 205 | <b>(lldb)</b> frame variable counter -f hex |
| 206 | </td> |
| 207 | <table> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 208 | |
| 209 | <p>This has the effect of displaying the value of <code>counter</code> |
| 210 | as an hexadecimal number, and will keep showing it this |
| 211 | way until you either pick a different format or till you |
| 212 | let your program run again.</p> |
| 213 | |
| 214 | <p>Finally, this is a list of formatting options available |
| 215 | out of |
| 216 | which you can pick:</p><a name="formatstable"></a> |
| 217 | <table border="1"> |
| 218 | <tbody> |
| 219 | <tr valign="top"> |
| 220 | <td width="23%"><b>Format name</b></td> |
| 221 | <td><b>Abbreviation</b></td> |
| 222 | <td><b>Description</b></td> |
| 223 | </tr> |
| 224 | <tr valign="top"> |
| 225 | <td><b>default</b></td> |
| 226 | <td><br> |
| 227 | </td> |
| 228 | <td>the default LLDB algorithm is used to pick a |
| 229 | format</td> |
| 230 | </tr> |
| 231 | <tr valign="top"> |
| 232 | <td><b>boolean</b></td> |
| 233 | <td>B</td> |
| 234 | <td>show this as a true/false boolean, using the |
| 235 | customary rule that 0 is false and everything else |
| 236 | is true</td> |
| 237 | </tr> |
| 238 | <tr valign="top"> |
| 239 | <td><b>binary</b></td> |
| 240 | <td>b</td> |
| 241 | <td>show this as a sequence of bits</td> |
| 242 | </tr> |
| 243 | <tr valign="top"> |
| 244 | <td><b>bytes</b></td> |
| 245 | <td>y</td> |
| 246 | <td>show the bytes one after the other<br> |
| 247 | e.g. <code>(int) s.x = 07 00 00 00</code></td> |
| 248 | </tr> |
| 249 | <tr valign="top"> |
| 250 | <td><b>bytes with ASCII</b></td> |
| 251 | <td>Y</td> |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 252 | <td>show the bytes, but try to display them as ASCII |
| 253 | characters as well<br> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 254 | e.g. <code>(int *) c.sp.x = 50 f8 bf 5f ff 7f 00 |
| 255 | 00 P.._....</code></td> |
| 256 | </tr> |
| 257 | <tr valign="top"> |
| 258 | <td><b>character</b></td> |
| 259 | <td>c</td> |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 260 | <td>show the bytes as ASCII characters<br> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 261 | e.g. <code>(int *) c.sp.x = |
| 262 | P\xf8\xbf_\xff\x7f\0\0</code></td> |
| 263 | </tr> |
| 264 | <tr valign="top"> |
| 265 | <td><b>printable character</b></td> |
| 266 | <td>C</td> |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 267 | <td>show the bytes as printable ASCII |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 268 | characters<br> |
| 269 | e.g. <code>(int *) c.sp.x = P.._....</code></td> |
| 270 | </tr> |
| 271 | <tr valign="top"> |
| 272 | <td><b>complex float</b></td> |
| 273 | <td>F</td> |
| 274 | <td>interpret this value as the real and imaginary |
| 275 | part of a complex floating-point number<br> |
| 276 | e.g. <code>(int *) c.sp.x = 2.76658e+19 + |
| 277 | 4.59163e-41i</code></td> |
| 278 | </tr> |
| 279 | <tr valign="top"> |
| 280 | <td><b>c-string</b></td> |
| 281 | <td>s</td> |
| 282 | <td>show this as a 0-terminated C string</td> |
| 283 | </tr> |
| 284 | <tr valign="top"> |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 285 | <td><b>decimal</b></td> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 286 | <td>i</td> |
| 287 | <td>show this as a signed integer number (this does |
| 288 | not perform a cast, it simply shows the bytes as |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 289 | an integer with sign)</td> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 290 | </tr> |
| 291 | <tr valign="top"> |
| 292 | <td><b>enumeration</b></td> |
| 293 | <td>E</td> |
| 294 | <td>show this as an enumeration, printing the |
| 295 | value's name if available or the integer value |
| 296 | otherwise<br> |
| 297 | e.g. <code>(enum enumType) val_type = eValue2</code></td> |
| 298 | </tr> |
| 299 | <tr valign="top"> |
| 300 | <td><b>hex</b></td> |
| 301 | <td>x</td> |
| 302 | <td>show this as in hexadecimal notation (this does |
| 303 | not perform a cast, it simply shows the bytes as |
| 304 | hex)</td> |
| 305 | </tr> |
| 306 | <tr valign="top"> |
| 307 | <td><b>float</b></td> |
| 308 | <td>f</td> |
| 309 | <td>show this as a floating-point number (this does |
| 310 | not perform a cast, it simply interprets the bytes |
| 311 | as an IEEE754 floating-point value)</td> |
| 312 | </tr> |
| 313 | <tr valign="top"> |
| 314 | <td><b>octal</b></td> |
| 315 | <td>o</td> |
| 316 | <td>show this in octal notation</td> |
| 317 | </tr> |
| 318 | <tr valign="top"> |
| 319 | <td><b>OSType</b></td> |
| 320 | <td>O</td> |
| 321 | <td>show this as a MacOS OSType<br> |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 322 | e.g. <code>(float) x = '\n\x1f\xd7\n'</code></td> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 323 | </tr> |
| 324 | <tr valign="top"> |
| 325 | <td><b>unicode16</b></td> |
| 326 | <td>U</td> |
| 327 | <td>show this as UTF-16 characters<br> |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 328 | e.g. <code>(float) x = 0xd70a 0x411f</code></td> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 329 | </tr> |
| 330 | <tr valign="top"> |
| 331 | <td><b>unicode32</b></td> |
| 332 | <td><br> |
| 333 | </td> |
| 334 | <td>show this as UTF-32 characters<br> |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 335 | e.g. <code>(float) x = 0x411fd70a</code></td> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 336 | </tr> |
| 337 | <tr valign="top"> |
| 338 | <td><b>unsigned decimal</b></td> |
| 339 | <td>u</td> |
| 340 | <td>show this as an unsigned integer number (this |
| 341 | does not perform a cast, it simply shows the bytes |
| 342 | as unsigned integer)</td> |
| 343 | </tr> |
| 344 | <tr valign="top"> |
| 345 | <td><b>pointer</b></td> |
| 346 | <td>p</td> |
| 347 | <td>show this as a native pointer (unless this is |
| 348 | really a pointer, the resulting address will |
| 349 | probably be invalid)</td> |
| 350 | </tr> |
| 351 | <tr valign="top"> |
| 352 | <td><b>char[]</b></td> |
| 353 | <td><br> |
| 354 | </td> |
| 355 | <td>show this as an array of characters<br> |
| 356 | e.g. <code>(char) *c.sp.z = {X}</code></td> |
| 357 | </tr> |
| 358 | <tr valign="top"> |
| 359 | <td><b>int8_t[], uint8_t[]<br> |
| 360 | int16_t[], uint16_t[]<br> |
| 361 | int32_t[], uint32_t[]<br> |
| 362 | int64_t[], uint64_t[]<br> |
| 363 | uint128_t[]</b></td> |
| 364 | <td><br> |
| 365 | </td> |
| 366 | <td>show this as an array of the corresponding |
| 367 | integer type<br> |
| 368 | e.g.<br> |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 369 | <code>(int) x = {1 0 0 0}</code> (with uint8_t[])<br> |
| 370 | <code>(int) y = {0x00000001}</code> (with uint32_t[])</td> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 371 | </tr> |
| 372 | <tr valign="top"> |
| 373 | <td><b>float32[], float64[]</b></td> |
| 374 | <td><br> |
| 375 | </td> |
| 376 | <td>show this as an array of the corresponding |
| 377 | floating-point type<br> |
| 378 | e.g. <code>(int *) pointer = {1.46991e-39 |
| 379 | 1.4013e-45}</code></td> |
| 380 | </tr> |
| 381 | <tr valign="top"> |
| 382 | <td><b>complex integer</b></td> |
| 383 | <td>I</td> |
| 384 | <td>interpret this value as the real and imaginary |
| 385 | part of a complex integer number<br> |
| 386 | e.g. <code>(int *) pointer = 1048960 + 1i</code></td> |
| 387 | </tr> |
| 388 | <tr valign="top"> |
| 389 | <td><b>character array</b></td> |
| 390 | <td>a</td> |
| 391 | <td>show this as a character array<br> |
| 392 | e.g. <code>(int *) pointer = |
| 393 | \x80\x01\x10\0\x01\0\0\0</code></td> |
| 394 | </tr> |
| 395 | </tbody> |
| 396 | </table> |
| 397 | </div> |
| 398 | </div> |
| 399 | |
| 400 | <div class="post"> |
| 401 | <h1 class="postheader">type summary</h1> |
| 402 | <div class="postcontent"> |
Enrico Granata | 86e7c3e | 2011-07-12 22:56:10 +0000 | [diff] [blame] | 403 | <p>Type formats work by showing a different kind of display for |
| 404 | the value of a variable. However, they only work for basic types. |
| 405 | When you want to display a class or struct in a custom format, you |
| 406 | cannot do that using formats.</p> |
| 407 | <p>A different feature, type summaries, works by extracting |
| 408 | information from classes, structures, ... (<i>aggregate types</i>) |
| 409 | and arranging it in a user-defined format, as in the following example:</p> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 410 | <p> <i>before adding a summary...</i><br> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 411 | <code> <b>(lldb)</b> frame variable -T one<br> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 412 | (i_am_cool) one = {<br> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 413 | (int) x = 3<br> |
| 414 | (float) y = 3.14159<br> |
| 415 | (char) z = 'E'<br> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 416 | }<br> |
| 417 | </code> <br> |
| 418 | <i>after adding a summary...</i><br> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 419 | <code> <b>(lldb)</b> frame variable one<br> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 420 | (i_am_cool) one = int = 3, float = 3.14159, char = 69<br> |
| 421 | </code> </p> |
Enrico Granata | 8a717e5 | 2011-07-19 02:34:21 +0000 | [diff] [blame] | 422 | |
| 423 | <p>There are two ways to use type summaries: the first one is to bind a <i> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 424 | summary string</i> to the type; the second is to write a Python script that returns |
| 425 | the string to be used as summary. Both options are enabled by the <code>type summary add</code> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 426 | command.</p> |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 427 | <p>The command to obtain the output shown in the example is:</p> |
Enrico Granata | 86e7c3e | 2011-07-12 22:56:10 +0000 | [diff] [blame] | 428 | <table class="stats" width="620" cellspacing="0"> |
| 429 | <td class="content"> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 430 | <b>(lldb)</b> type summary add --summary-string "int = ${var.x}, float = ${var.y}, char = ${var.z%u}" i_am_cool |
Enrico Granata | 86e7c3e | 2011-07-12 22:56:10 +0000 | [diff] [blame] | 431 | </td> |
| 432 | <table> |
Enrico Granata | 8a717e5 | 2011-07-19 02:34:21 +0000 | [diff] [blame] | 433 | |
| 434 | <p>Initially, we will focus on summary strings, and then describe the Python binding |
| 435 | mechanism.</p> |
| 436 | |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 437 | </div> |
| 438 | </div> |
| 439 | <div class="post"> |
| 440 | <h1 class="postheader">Summary Strings</h1> |
| 441 | <div class="postcontent"> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 442 | <p>Summary strings are written using a simple control language, exemplified by the snippet above. |
| 443 | A summary string contains a sequence of tokens that are processed by LLDB to generate the summary.</p> |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 444 | |
| 445 | <p>Summary strings can contain plain text, control characters and |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 446 | special variables that have access to information about |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 447 | the current object and the overall program state.</p> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 448 | <p>Plain text is any sequence of characters that doesn't contain a <code><b>'{'</b></code>, |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 449 | <code><b>'}'</b></code>, <code><b>'$'</b></code>, or <code><b>'\'</b></code> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 450 | character, which are the syntax control characters.</p> |
| 451 | <p>The special variables are found in between a <code><b>"${"</b></code> |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 452 | prefix, and end with a <code><b>"}"</b></code> suffix. Variables can be a simple name |
| 453 | or they can refer to complex objects that have subitems themselves. |
| 454 | In other words, a variable looks like <code>"<b>${object}</b>"</code> or |
| 455 | <code>"<b>${object.child.otherchild}</b>"</code>. A variable can also be prefixed or |
| 456 | suffixed with other symbols meant to change the way its value is handled. An example is |
| 457 | <code>"<b>${*var.int_pointer[0-3]}</b>".</code></p> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 458 | <p>Basically, the syntax is the same one described <a |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 459 | href="formats.html">Frame and Thread Formatting</a> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 460 | are accepted. |
| 461 | Beyond what's described there, additional symbols have become available |
| 462 | in the syntax for summary strings. The main of them is <code>${var</code>, |
| 463 | which is used refer to the variable that a summary is being created for.</p> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 464 | <p>The simplest thing you can do is grab a member variable |
| 465 | of a class or structure by typing its <i>expression |
| 466 | path</i>. In the previous example, the expression path |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 467 | for the field <code>float y</code> is simply <code>.y</code>. |
| 468 | Thus, to ask the summary string to display <code>y</code> |
| 469 | you would type <code>${var.y}</code>.</p> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 470 | <p>If you have code like the following: <br> |
Enrico Granata | 0c5c9a2 | 2011-09-08 00:50:01 +0000 | [diff] [blame] | 471 | <code> <font color="blue">struct</font> A {<br> |
| 472 | <font color="blue">int</font> x;<br> |
| 473 | <font color="blue">int</font> y;<br> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 474 | };<br> |
Enrico Granata | 0c5c9a2 | 2011-09-08 00:50:01 +0000 | [diff] [blame] | 475 | <font color="blue">struct</font> B {<br> |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 476 | A x;<br> |
| 477 | A y;<br> |
Enrico Granata | 0c5c9a2 | 2011-09-08 00:50:01 +0000 | [diff] [blame] | 478 | <font color="blue">int</font> *z;<br> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 479 | };<br> |
| 480 | </code> the expression path for the <code>y</code> |
| 481 | member of the <code>x</code> member of an object of |
| 482 | type <code>B</code> would be <code>.x.y</code> and you |
| 483 | would type <code>${var.x.y}</code> to display it in a |
| 484 | summary string for type <code>B</code>. </p> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 485 | <p>By default, a summary defined for type <code>T</code>, also works for types |
| 486 | <code>T*</code> and <code>T&</code> (you can disable this behavior if desired). |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 487 | For this reason, expression paths do not differentiate between <code>.</code> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 488 | and <code>-></code>, and the above expression path <code>.x.y</code> |
| 489 | would be just as good if you were displaying a <code>B*</code>, |
| 490 | or even if the actual definition of <code>B</code> |
| 491 | were: <code><br> |
Enrico Granata | 0c5c9a2 | 2011-09-08 00:50:01 +0000 | [diff] [blame] | 492 | <font color="blue">struct</font> B {<br> |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 493 | A *x;<br> |
| 494 | A y;<br> |
Enrico Granata | 0c5c9a2 | 2011-09-08 00:50:01 +0000 | [diff] [blame] | 495 | <font color="blue">int</font> *z;<br> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 496 | };<br> |
| 497 | </code> </p> |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 498 | <p>This is unlike the behavior of <code>frame variable</code> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 499 | which, on the contrary, will enforce the distinction. As |
| 500 | hinted above, the rationale for this choice is that |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 501 | waiving this distinction enables you to write a summary |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 502 | string once for type <code>T</code> and use it for both |
| 503 | <code>T</code> and <code>T*</code> instances. As a |
| 504 | summary string is mostly about extracting nested |
| 505 | members' information, a pointer to an object is just as |
| 506 | good as the object itself for the purpose.</p> |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 507 | <p>If you need to access the value of the integer pointed to by <code>B::z</code>, you |
| 508 | cannot simply say <code>${var.z}</code> because that symbol refers to the pointer <code>z</code>. |
| 509 | In order to dereference it and get the pointed value, you should say <code>${*var.z}</code>. The <code>${*var</code> |
| 510 | tells LLDB to get the object that the expression paths leads to, and then dereference it. In this example is it |
| 511 | equivalent to <code>*(bObject.z)</code> in C/C++ syntax. Because <code>.</code> and <code>-></code> operators can both be |
| 512 | used, there is no need to have dereferences in the middle of an expression path (e.g. you do not need to type |
| 513 | <code>${*(var.x).x})</code> to read <code>A::x</code> as contained in <code>*(B::x)</code>. To achieve that effect |
| 514 | you can simply write <code>${var.x->x}</code>, or even <code>${var.x.x}</code>. The <code>*</code> operator only binds |
| 515 | to the result of the whole expression path, rather than piecewise, and there is no way to use parentheses to change |
| 516 | that behavior.</p> |
| 517 | <p>Of course, a summary string can contain more than one <code>${var</code> specifier, |
| 518 | and can use <code>${var</code> and <code>${*var</code> specifiers together.</p> |
| 519 | </div> |
| 520 | </div> |
| 521 | <div class="post"> |
| 522 | <h1 class="postheader">Formatting summary elements</h1> |
| 523 | <div class="postcontent"> |
| 524 | <p>An expression path can include formatting codes. |
| 525 | Much like the type formats discussed previously, you can also customize |
| 526 | the way variables are displayed in summary strings, regardless of the format they have |
| 527 | applied to their types. To do that, you can use <code>%<i>format</i></code> inside an expression path, |
| 528 | as in <code>${var.x->x%u}</code>, which would display the value of <code>x</code> as an unsigned integer. |
Enrico Granata | e4e3e2c | 2011-07-22 00:16:08 +0000 | [diff] [blame] | 529 | |
| 530 | <p>You can also use some other special format markers, not available |
| 531 | for type formatters, but which carry a special meaning when used in this |
| 532 | context:</p> |
| 533 | |
| 534 | <table border="1"> |
| 535 | <tbody> |
| 536 | <tr valign="top"> |
| 537 | <td width="23%"><b>Symbol</b></td> |
| 538 | <td><b>Description</b></td> |
| 539 | </tr> |
| 540 | <tr valign="top"> |
| 541 | <td><b>%S</b></td> |
| 542 | <td>Use this object's summary (the default for aggregate types)</td> |
| 543 | </tr> |
| 544 | <tr valign="top"> |
| 545 | <td><b>%V</b></td> |
| 546 | <td>Use this object's value (the default for non-aggregate types)</td> |
| 547 | </tr> |
| 548 | <tr valign="top"> |
| 549 | <td><b>%@</b></td> |
| 550 | <td>Use a language-runtime specific description (for C++ this does nothing, |
| 551 | for Objective-C it calls the NSPrintForDebugger API)</td> |
| 552 | </tr> |
| 553 | <tr valign="top"> |
| 554 | <td><b>%L</b></td> |
| 555 | <td>Use this object's location (memory address, register name, ...)</td> |
| 556 | </tr> |
Enrico Granata | 68506fb | 2011-08-22 16:10:25 +0000 | [diff] [blame] | 557 | <tr valign="top"> |
| 558 | <td><b>%#</b></td> |
| 559 | <td>Use the count of the children of this object</td> |
| 560 | </tr> |
| 561 | <tr valign="top"> |
| 562 | <td><b>%T</b></td> |
| 563 | <td>Use this object's datatype name</td> |
| 564 | </tr> |
Enrico Granata | e4e3e2c | 2011-07-22 00:16:08 +0000 | [diff] [blame] | 565 | </tbody> |
| 566 | </table> |
| 567 | |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 568 | <p>Option <code>--inline-children</code> (<code>-c</code>) to <code>type summary add</code> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 569 | tells LLDB not to look for a summary string, but instead |
| 570 | to just print a listing of all the object's children on |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 571 | one line.</p> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 572 | <p> As an example, given a type <code>pair</code>: |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 573 | <code> <br> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 574 | <b>(lldb)</b> frame variable --show-types a_pair<br> |
| 575 | (pair) a_pair = {<br> |
| 576 | (int) first = 1;<br/> |
| 577 | (int) second = 2;<br/> |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 578 | }<br> |
| 579 | </code><br> |
| 580 | If one types the following commands: |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 581 | <table class="stats" width="620" cellspacing="0"> |
| 582 | <td class="content"> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 583 | <b>(lldb)</b> type summary add --inline-children pair<br> |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 584 | </td> |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 585 | <table> |
| 586 | the output becomes: <br><code> |
| 587 | |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 588 | <b>(lldb)</b> frame variable a_pair<br> |
| 589 | (pair) a_pair = (first=1, second=2)<br> |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 590 | </code> </p> |
Enrico Granata | 0c5c9a2 | 2011-09-08 00:50:01 +0000 | [diff] [blame] | 591 | |
| 592 | Of course, one can obtain the same effect by typing |
| 593 | <table class="stats" width="620" cellspacing="0"> |
| 594 | <td class="content"> |
| 595 | <b>(lldb)</b> type summary add pair --summary-string "(first=${var.first}, second=${var.second})"<br> |
| 596 | </td> |
| 597 | <table> |
| 598 | |
| 599 | While the final result is the same, using <code>--inline-children</code> can often save time. |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 600 | </div> |
| 601 | </div> |
| 602 | <div class="post"> |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 603 | <h1 class="postheader">Bitfields and array syntax</h1> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 604 | <div class="postcontent"> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 605 | <p>Sometimes, a basic type's value actually represents |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 606 | several different values packed together in a bitfield.<br/> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 607 | With the classical view, there is no way to look at |
| 608 | them. Hexadecimal display can help, but if the bits |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 609 | actually span nibble boundaries, the help is limited.<br/> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 610 | Binary view would show it all without ambiguity, but is |
| 611 | often too detailed and hard to read for real-life |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 612 | scenarios. |
| 613 | <p> |
| 614 | To cope with the issue, LLDB supports native |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 615 | bitfield formatting in summary strings. If your |
| 616 | expression paths leads to a so-called <i>scalar type</i> |
| 617 | (the usual int, float, char, double, short, long, long |
| 618 | long, double, long double and unsigned variants), you |
| 619 | can ask LLDB to only grab some bits out of the value and |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 620 | display them in any format you like. If you only need one bit |
| 621 | you can use the <code>[</code><i>n</i><code>]</code>, just like |
| 622 | indexing an array. To extract multiple bits, you can use |
| 623 | a slice-like syntax: <code>[</code><i>n</i>-<i>m</i><code>]</code>, e.g. <br><p> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 624 | <code> <b>(lldb)</b> frame variable float_point<br> |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 625 | (float) float_point = -3.14159<br> </code> |
| 626 | <table class="stats" width="620" cellspacing="0"> |
| 627 | <td class="content"> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 628 | <b>(lldb)</b> type summary add --summary-string "Sign: ${var[31]%B} |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 629 | Exponent: ${var[30-23]%x} Mantissa: ${var[0-22]%u}" |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 630 | float |
| 631 | </td> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 632 | </table><br></code> |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 633 | |
| 634 | <code> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 635 | <b>(lldb)</b> frame variable float_point<br> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 636 | (float) float_point = -3.14159 Sign: true Exponent: |
| 637 | 0x00000080 Mantissa: 4788184<br> |
| 638 | </code> In this example, LLDB shows the internal |
| 639 | representation of a <code>float</code> variable by |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 640 | extracting bitfields out of a float object.</p> |
| 641 | |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 642 | <p> When typing a range, the extremes <i>n</i> and <i>m</i> are always |
| 643 | included, and the order of the indices is irrelevant. </p> |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 644 | |
| 645 | <p>LLDB also allows to use a similar syntax to display |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 646 | array members inside a summary string. For instance, you |
| 647 | may want to display all arrays of a given type using a |
| 648 | more compact notation than the default, and then just |
| 649 | delve into individual array members that prove |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 650 | interesting to your debugging task. You can tell |
| 651 | LLDB to format arrays in special ways, possibly |
| 652 | independent of the way the array members' datatype is formatted. <br> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 653 | e.g. <br> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 654 | <code> <b>(lldb)</b> frame variable sarray<br> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 655 | (Simple [3]) sarray = {<br> |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 656 | [0] = {<br> |
| 657 | x = 1<br> |
| 658 | y = 2<br> |
| 659 | z = '\x03'<br> |
| 660 | }<br> |
| 661 | [1] = {<br> |
| 662 | x = 4<br> |
| 663 | y = 5<br> |
| 664 | z = '\x06'<br> |
| 665 | }<br> |
| 666 | [2] = {<br> |
| 667 | x = 7<br> |
| 668 | y = 8<br> |
| 669 | z = '\t'<br> |
| 670 | }<br> |
| 671 | }<br></code> |
| 672 | |
| 673 | <table class="stats" width="620" cellspacing="0"> |
| 674 | <td class="content"> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 675 | <b>(lldb)</b> type summary add --summary-string "${var[].x}" "Simple |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 676 | [3]" |
| 677 | </td> |
| 678 | <table><br> |
| 679 | |
| 680 | <code> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 681 | <b>(lldb)</b> frame variable sarray<br> |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 682 | (Simple [3]) sarray = [1,4,7]<br></code></p> |
| 683 | |
| 684 | <p>The <code>[]</code> symbol amounts to: <i>if <code>var</code> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 685 | is an array and I knows its size, apply this summary |
| 686 | string to every element of the array</i>. Here, we are |
| 687 | asking LLDB to display <code>.x</code> for every |
| 688 | element of the array, and in fact this is what happens. |
| 689 | If you find some of those integers anomalous, you can |
| 690 | then inspect that one item in greater detail, without |
| 691 | the array format getting in the way: <br> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 692 | <code> <b>(lldb)</b> frame variable sarray[1]<br> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 693 | (Simple) sarray[1] = {<br> |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 694 | x = 4<br> |
| 695 | y = 5<br> |
| 696 | z = '\x06'<br> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 697 | }<br> |
| 698 | </code> </p> |
| 699 | <p>You can also ask LLDB to only print a subset of the |
| 700 | array range by using the same syntax used to extract bit |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 701 | for bitfields: |
| 702 | <table class="stats" width="620" cellspacing="0"> |
| 703 | <td class="content"> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 704 | <b>(lldb)</b> type summary add --summary-string "${var[1-2].x}" "Simple |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 705 | [3]" |
| 706 | </td> |
| 707 | <table><br> |
| 708 | <code> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 709 | <b>(lldb)</b> frame variable sarray<br> |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 710 | (Simple [3]) sarray = [4,7]<br></code></p> |
| 711 | |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 712 | <p>If you are dealing with a pointer that you know is an array, you can use this |
| 713 | syntax to display the elements contained in the pointed array instead of just |
| 714 | the pointer value. However, because pointers have no notion of their size, the |
| 715 | empty brackets <code>[]</code> operator does not work, and you must explicitly provide |
| 716 | higher and lower bounds.</p> |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 717 | |
| 718 | <p>In general, LLDB needs the square brackets operator <code>[]</code> in |
| 719 | order to handle arrays and pointers correctly, and for pointers it also |
| 720 | needs a range. However, a few special cases are defined to make your life easier: |
| 721 | <ul> |
| 722 | <li>you can print a 0-terminated string (<i>C-string</i>) using the %s format, |
| 723 | omitting square brackets, as in: |
| 724 | <table class="stats" width="620" cellspacing="0"> |
| 725 | <td class="content"> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 726 | <b>(lldb)</b> type summary add --summary-string "${var%s}" "char *" |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 727 | </td> |
| 728 | <table> |
Enrico Granata | de51233 | 2011-08-24 01:49:09 +0000 | [diff] [blame] | 729 | <p> |
| 730 | This syntax works for <code>char*</code> as well as for <code>char[]</code> |
| 731 | because LLDB can rely on the final <code>\0</code> terminator to know when the string |
| 732 | has ended.</p> |
| 733 | LLDB has default summary strings for <code>char*</code> and <code>char[]</code> that use |
| 734 | this special case. On debugger startup, the following are defined automatically: |
| 735 | <table class="stats" width="620" cellspacing="0"> |
| 736 | <td class="content"> |
| 737 | <b>(lldb)</b> type summary add --summary-string "${var%s}" "char *"<br/> |
| 738 | <b>(lldb)</b> type summary add --summary-string "${var%s}" -x "char \[[0-9]+]"<br/> |
| 739 | </td> |
| 740 | <table> |
| 741 | </li> |
| 742 | </ul> |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 743 | <ul> |
| 744 | |
Enrico Granata | de51233 | 2011-08-24 01:49:09 +0000 | [diff] [blame] | 745 | <li>any of the array formats (<code>int8_t[]</code>, |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 746 | <code>float32{}</code>, ...), and the <code>y</code>, <code>Y</code> |
| 747 | and <code>a</code> formats |
| 748 | work to print an array of a non-aggregate |
| 749 | type, even if square brackets are omitted. |
| 750 | <table class="stats" width="620" cellspacing="0"> |
| 751 | <td class="content"> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 752 | <b>(lldb)</b> type summary add --summary-string "${var%int32_t[]}" "int [10]" |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 753 | </td> |
| 754 | <table> |
| 755 | |
| 756 | </ul> |
| 757 | This feature, however, is not enabled for pointers because there is no |
| 758 | way for LLDB to detect the end of the pointed data. |
| 759 | <br> |
| 760 | This also does not work for other formats (e.g. <code>boolean</code>), and you must |
| 761 | specify the square brackets operator to get the expected output. |
| 762 | </p> |
| 763 | </div> |
| 764 | </div> |
| 765 | |
| 766 | <div class="post"> |
Enrico Granata | 8a717e5 | 2011-07-19 02:34:21 +0000 | [diff] [blame] | 767 | <h1 class="postheader">Python scripting</h1> |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 768 | <div class="postcontent"> |
Enrico Granata | 8a717e5 | 2011-07-19 02:34:21 +0000 | [diff] [blame] | 769 | |
| 770 | <p>Most of the times, summary strings prove good enough for the job of summarizing |
| 771 | the contents of a variable. However, as soon as you need to do more than picking |
| 772 | some values and rearranging them for display, summary strings stop being an |
| 773 | effective tool. This is because summary strings lack the power to actually perform |
| 774 | some computation on the value of variables.</p> |
| 775 | <p>To solve this issue, you can bind some Python scripting code as a summary for |
| 776 | your datatype, and that script has the ability to both extract children variables |
| 777 | as the summary strings do and to perform active computation on the extracted |
| 778 | values. As a small example, let's say we have a Rectangle class:</p> |
| 779 | |
| 780 | <code> |
Enrico Granata | 0c5c9a2 | 2011-09-08 00:50:01 +0000 | [diff] [blame] | 781 | <font color="blue">class</font> Rectangle<br/> |
Enrico Granata | 8a717e5 | 2011-07-19 02:34:21 +0000 | [diff] [blame] | 782 | {<br/> |
Enrico Granata | 0c5c9a2 | 2011-09-08 00:50:01 +0000 | [diff] [blame] | 783 | <font color="blue">private</font>:<br/> |
| 784 | <font color="blue">int</font> height;<br/> |
| 785 | <font color="blue">int</font> width;<br/> |
| 786 | <font color="blue">public</font>:<br/> |
Enrico Granata | 8a717e5 | 2011-07-19 02:34:21 +0000 | [diff] [blame] | 787 | Rectangle() : height(3), width(5) {}<br/> |
Enrico Granata | 0c5c9a2 | 2011-09-08 00:50:01 +0000 | [diff] [blame] | 788 | Rectangle(<font color="blue">int</font> H) : height(H), width(H*2-1) {}<br/> |
| 789 | Rectangle(<font color="blue">int</font> H, <font color="blue">int</font> W) : height(H), width(W) {}<br/> |
Enrico Granata | 8a717e5 | 2011-07-19 02:34:21 +0000 | [diff] [blame] | 790 | |
Enrico Granata | 0c5c9a2 | 2011-09-08 00:50:01 +0000 | [diff] [blame] | 791 | <font color="blue">int</font> GetHeight() { return height; }<br/> |
| 792 | <font color="blue">int</font> GetWidth() { return width; }<br/> |
Enrico Granata | 8a717e5 | 2011-07-19 02:34:21 +0000 | [diff] [blame] | 793 | |
| 794 | };<br/> |
| 795 | </code> |
| 796 | |
| 797 | <p>Summary strings are effective to reduce the screen real estate used by |
| 798 | the default viewing mode, but are not effective if we want to display the |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 799 | area and perimeter of <code>Rectangle</code> objects</p> |
Enrico Granata | 8a717e5 | 2011-07-19 02:34:21 +0000 | [diff] [blame] | 800 | |
| 801 | <p>To obtain this, we can simply attach a small Python script to the <code>Rectangle</code> |
| 802 | class, as shown in this example:</p> |
| 803 | |
| 804 | <table class="stats" width="620" cellspacing="0"> |
| 805 | <td class="content"> |
| 806 | <b>(lldb)</b> type summary add -P Rectangle<br/> |
| 807 | Enter your Python command(s). Type 'DONE' to end.<br/> |
| 808 | def function (valobj,dict):<br/> |
| 809 | height_val = valobj.GetChildMemberWithName('height')<br/> |
| 810 | width_val = valobj.GetChildMemberWithName('width')<br/> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 811 | height = height_val.GetValueAsUnsigned(0)<br/> |
| 812 | width = width_val.GetValueAsUnsigned(0)<br/> |
Enrico Granata | 8a717e5 | 2011-07-19 02:34:21 +0000 | [diff] [blame] | 813 | area = height*width<br/> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 814 | perimeter = 2*(height + width)<br/> |
| 815 | return 'Area: ' + str(area) + ', Perimeter: ' + str(perimeter)<br/> |
Enrico Granata | 8a717e5 | 2011-07-19 02:34:21 +0000 | [diff] [blame] | 816 | DONE<br/> |
Enrico Granata | 8a717e5 | 2011-07-19 02:34:21 +0000 | [diff] [blame] | 817 | <b>(lldb)</b> frame variable<br/> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 818 | (Rectangle) r1 = Area: 20, Perimeter: 18<br/> |
| 819 | (Rectangle) r2 = Area: 72, Perimeter: 36<br/> |
| 820 | (Rectangle) r3 = Area: 16, Perimeter: 16<br/> |
Enrico Granata | 8a717e5 | 2011-07-19 02:34:21 +0000 | [diff] [blame] | 821 | </td> |
| 822 | </table> |
| 823 | |
Enrico Granata | 8a717e5 | 2011-07-19 02:34:21 +0000 | [diff] [blame] | 824 | <p>In order to write effective summary scripts, you need to know the LLDB public |
| 825 | API, which is the way Python code can access the LLDB object model. For further |
| 826 | details on the API you should look at <a href="scripting.html">this page</a>, or at |
| 827 | the LLDB <a href="docs.html">doxygen documentation</a> when it becomes available.</p> |
| 828 | |
| 829 | <p>As a brief introduction, your script is encapsulated into a function that is |
| 830 | passed two parameters: <code>valobj</code> and <code>dict</code>.</p> |
| 831 | |
| 832 | <p><code>dict</code> is an internal support parameter used by LLDB and you should |
| 833 | not use it.<br/><code>valobj</code> is the object encapsulating the actual |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 834 | variable being displayed, and its type is <a href="http://llvm.org/svn/llvm-project/lldb/trunk/include/lldb/API/SBValue.h">SBValue</a>. |
| 835 | Out of the many possible operations on an SBValue, the basic one is retrieve the children objects |
| 836 | it contains (essentially, the fields of the object wrapped by it), by calling |
| 837 | <code>GetChildMemberWithName()</code>, passing it the child's name as a string.<br/> |
| 838 | If the variable has a value, you can ask for it, and return it as a string using <code>GetValue()</code>, |
| 839 | or as a signed/unsigned number using <code>GetValueAsSigned()</code>, <code>GetValueAsUnsigned()</code>. |
Enrico Granata | 8a717e5 | 2011-07-19 02:34:21 +0000 | [diff] [blame] | 840 | |
| 841 | <p>If you need to delve into several levels of hierarchy, as you can do with summary |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 842 | strings, you can use the method <code>GetValueForExpressionPath()</code>, passing it |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 843 | an expression path just like those you could use for summary strings (one of the differences |
| 844 | is that dereferencing a pointer does not occur by prefixing the path with a <code>*</code>, |
| 845 | but by calling the <code>Dereference()</code> method on the returned SBValue). |
| 846 | If you need to access array slices, you cannot do that (yet) via this method call, and you must |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 847 | use <code>GetChildAtIndex()</code> querying it for the array items one by one. |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 848 | Also, handling custom formats is something you have to deal with on your own. |
Enrico Granata | 8a717e5 | 2011-07-19 02:34:21 +0000 | [diff] [blame] | 849 | |
| 850 | <p>Other than interactively typing a Python script there are two other ways for you |
| 851 | to input a Python script as a summary: |
| 852 | |
| 853 | <ul> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 854 | <li> using the --python-script option to <code>type summary add </code> and typing the script |
Enrico Granata | 8a717e5 | 2011-07-19 02:34:21 +0000 | [diff] [blame] | 855 | code as an option argument; as in: </ul> |
| 856 | |
| 857 | <table class="stats" width="620" cellspacing="0"> |
| 858 | <td class="content"> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 859 | <b>(lldb)</b> type summary add --python-script "height = |
Enrico Granata | 8a717e5 | 2011-07-19 02:34:21 +0000 | [diff] [blame] | 860 | int(valobj.GetChildMemberWithName('height').GetValue());width = |
| 861 | int(valobj.GetChildMemberWithName('width').GetValue()); |
| 862 | return 'Area: ' + str(height*width)" Rectangle<br/> |
| 863 | </td> |
| 864 | </table> |
| 865 | <ul> |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 866 | <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 | 8a717e5 | 2011-07-19 02:34:21 +0000 | [diff] [blame] | 867 | Python function with the correct prototype. Most probably, you will define (or have |
| 868 | already defined) the function in the interactive interpreter, or somehow |
Enrico Granata | 0c5c9a2 | 2011-09-08 00:50:01 +0000 | [diff] [blame] | 869 | loaded it from a file, using the <code>script import</code> command. LLDB will not make any attempt at determining whether |
| 870 | the function is defined and syntactically correct, until you try to call it. Any errors will be shown at that stage, as if |
| 871 | you were executing your function inside the Python interactive interpreter itself. |
Enrico Granata | 8a717e5 | 2011-07-19 02:34:21 +0000 | [diff] [blame] | 872 | </ul> |
| 873 | |
| 874 | </p> |
| 875 | |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 876 | </div> |
| 877 | </div> |
| 878 | |
Enrico Granata | 8a717e5 | 2011-07-19 02:34:21 +0000 | [diff] [blame] | 879 | <div class="post"> |
| 880 | <h1 class="postheader">Regular expression typenames</h1> |
| 881 | <div class="postcontent"> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 882 | <p>As you noticed, in order to associate the custom |
| 883 | summary string to the array types, one must give the |
| 884 | array size as part of the typename. This can long become |
| 885 | tiresome when using arrays of different sizes, <code>Simple |
| 886 | |
| 887 | [3]</code>, <code>Simple [9]</code>, <code>Simple |
| 888 | [12]</code>, ...</p> |
| 889 | <p>If you use the <code>-x</code> option, type names are |
| 890 | treated as regular expressions instead of type names. |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 891 | This would let you rephrase the above example |
| 892 | for arrays of type <code>Simple [3]</code> as: <br> |
| 893 | |
| 894 | <table class="stats" width="620" cellspacing="0"> |
| 895 | <td class="content"> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 896 | <b>(lldb)</b> type summary add --summary-string "${var[].x}" |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 897 | -x "Simple \[[0-9]+\]" |
| 898 | </td> |
| 899 | <table> |
| 900 | |
| 901 | <code> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 902 | <b>(lldb)</b> frame variable sarray<br> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 903 | (Simple [3]) sarray = [1,4,7]<br> |
| 904 | </code> The above scenario works for <code>Simple [3]</code> |
| 905 | as well as for any other array of <code>Simple</code> |
| 906 | objects. </p> |
| 907 | <p>While this feature is mostly useful for arrays, you |
| 908 | could also use regular expressions to catch other type |
| 909 | sets grouped by name. However, as regular expression |
| 910 | matching is slower than normal name matching, LLDB will |
| 911 | first try to match by name in any way it can, and only |
| 912 | when this fails, will it resort to regular expression |
| 913 | matching. Thus, if your type has a base class with a |
| 914 | cascading summary, this will be preferred over any |
| 915 | regular expression match for your type itself.</p> |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 916 | <p>One of the ways LLDB uses this feature internally, is to match |
| 917 | the names of STL container classes, regardless of the template |
| 918 | arguments provided (e.g. <code>std::vector<T></code> for any |
Enrico Granata | 0c5c9a2 | 2011-09-08 00:50:01 +0000 | [diff] [blame] | 919 | type argument <code>T</code>). The regular expressions used for this are: |
| 920 | </p> |
| 921 | <ul> |
| 922 | <li><code>^(std::)?vector<.+>$</code> for <code>std::vector<T></code></li> |
| 923 | <li><code>^(std::)?list<.+>$</code> for <code>std::list<T></code></li> |
| 924 | <li><code>^(std::)?map<.+> >$</code> for <code>std::map<K,V></code></li> |
| 925 | </ul> |
| 926 | As you can see, the actual template arguments are ignored by the regular expression. |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 927 | |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 928 | <p>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 |
| 929 | compliant implementation. |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 930 | |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 931 | </div> |
| 932 | </div> |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 933 | |
| 934 | <div class="post"> |
| 935 | <h1 class="postheader">Named summaries</h1> |
| 936 | <div class="postcontent"> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 937 | <p>For a given type, there may be different meaningful summary |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 938 | representations. However, currently, only one summary can be associated |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 939 | to a type at each moment. If you need to temporarily override the association |
| 940 | for a variable, without changing the summary string for to its type, |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 941 | you can use named summaries.</p> |
| 942 | |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 943 | <p>Named summaries work by attaching a name to a summary when creating |
| 944 | it. Then, when there is a need to attach the summary to a variable, the |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 945 | <code>frame variable</code> command, supports a <code>--summary</code> option |
| 946 | that tells LLDB to use the named summary given instead of the default one.</p> |
| 947 | |
| 948 | <table class="stats" width="620" cellspacing="0"> |
| 949 | <td class="content"> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 950 | <b>(lldb)</b> type summary add --summary-string "x=${var.integer}" --name NamedSummary |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 951 | </td> |
| 952 | <table> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 953 | <code> <b>(lldb)</b> frame variable one<br> |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 954 | (i_am_cool) one = int = 3, float = 3.14159, char = 69<br> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 955 | <b>(lldb)</b> frame variable one --summary NamedSummary<br> |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 956 | (i_am_cool) one = x=3<br> |
| 957 | </code> </p> |
| 958 | |
Enrico Granata | f7a9b14 | 2011-07-15 02:26:42 +0000 | [diff] [blame] | 959 | <p>When defining a named summmary, binding it to one or more types becomes optional. |
| 960 | Even if you bind the named summary to a type, and later change the summary string |
| 961 | for that type, the named summary will not be changed by that. You can delete |
| 962 | named summaries by using the <code>type summary delete</code> command, as if the |
| 963 | summary name was the datatype that the summary is applied to</p> |
| 964 | |
| 965 | <p>A summary attached to a variable using the </code>--summary</code> option, |
| 966 | has the same semantics that a custom format attached using the <code>-f</code> |
| 967 | option has: it stays attached till you attach a new one, or till you let |
| 968 | your program run again.</p> |
| 969 | |
Enrico Granata | ede7bdf | 2011-07-13 00:00:57 +0000 | [diff] [blame] | 970 | </div> |
| 971 | </div> |
| 972 | |
Enrico Granata | 68506fb | 2011-08-22 16:10:25 +0000 | [diff] [blame] | 973 | <div class="post"> |
| 974 | <h1 class="postheader">Synthetic children</h1> |
| 975 | <div class="postcontent"> |
| 976 | <p>Summaries work well when one is able to navigate through an expression path. |
| 977 | In order for LLDB to do so, appropriate debugging information must be available.</p> |
| 978 | <p>Some types are <i>opaque</i>, i.e. no knowledge of their internals is provided. |
| 979 | When that's the case, expression paths do not work correctly.</p> |
| 980 | <p>In other cases, the internals are available to use in expression paths, but they |
| 981 | do not provide a user-friendly representation of the object's value.</p> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 982 | <p>For instance, consider an STL vector, as implemented by the <a href="http://gcc.gnu.org/onlinedocs/libstdc++/">GNU C++ Library</a>:</p> |
Enrico Granata | 68506fb | 2011-08-22 16:10:25 +0000 | [diff] [blame] | 983 | <code> |
| 984 | <b>(lldb)</b> frame variable numbers -T<br/> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 985 | (std::vector<int>) numbers = {<br/> |
| 986 | (std::_Vector_base<int, std::allocator<int> >) std::_Vector_base<int, std::allocator<int> > = {<br/> |
| 987 | (std::_Vector_base<int, std::allocator&tl;int> >::_Vector_impl) _M_impl = {<br/> |
Enrico Granata | 68506fb | 2011-08-22 16:10:25 +0000 | [diff] [blame] | 988 | (int *) _M_start = 0x00000001001008a0<br/> |
| 989 | (int *) _M_finish = 0x00000001001008a8<br/> |
| 990 | (int *) _M_end_of_storage = 0x00000001001008a8<br/> |
| 991 | }<br/> |
| 992 | }<br/> |
| 993 | }<br/> |
| 994 | </code> |
| 995 | <p>Here, you can see how the type is implemented, and you can write a summary for that implementation |
| 996 | but that is not going to help you infer what items are actually stored in the vector.</p> |
| 997 | <p>What you would like to see is probably something like:</p> |
| 998 | <code> |
| 999 | <b>(lldb)</b> frame variable numbers -T<br/> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 1000 | (std::vector<int>) numbers = {<br/> |
Enrico Granata | 68506fb | 2011-08-22 16:10:25 +0000 | [diff] [blame] | 1001 | (int) [0] = 1<br/> |
| 1002 | (int) [1] = 12<br/> |
| 1003 | (int) [2] = 123<br/> |
| 1004 | (int) [3] = 1234<br/> |
| 1005 | }<br/> |
| 1006 | </code> |
| 1007 | <p>Synthetic children are a way to get that result.</p> |
| 1008 | <p>The feature is based upon the idea of providing a new set of children for a variable that replaces the ones |
| 1009 | available by default through the debug information. In the example, we can use synthetic children to provide |
| 1010 | the vector items as children for the std::vector object.</p> |
| 1011 | <p>In order to create synthetic children, you need to provide a Python class that adheres to a given <i>interface</i> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 1012 | (the word is italicized because <a href="http://en.wikipedia.org/wiki/Duck_typing">Python has no explicit notion of interface</a>, by that word we mean a given set of methods |
Enrico Granata | 68506fb | 2011-08-22 16:10:25 +0000 | [diff] [blame] | 1013 | must be implemented by the Python class):</p> |
| 1014 | <code> |
| 1015 | <font color=blue>class</font> SyntheticChildrenProvider:<br/> |
| 1016 | <font color=blue>def</font> __init__(self, valobj, dict):<br/> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 1017 | <i>this call should initialize the Python object using valobj as the variable to provide synthetic children for</i> <br/> |
Enrico Granata | 68506fb | 2011-08-22 16:10:25 +0000 | [diff] [blame] | 1018 | <font color=blue>def</font> num_children(self): <br/> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 1019 | <i>this call should return the number of children that you want your object to have</i> <br/> |
Enrico Granata | 68506fb | 2011-08-22 16:10:25 +0000 | [diff] [blame] | 1020 | <font color=blue>def</font> get_child_index(self,name): <br/> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 1021 | <i>this call should return the index of the synthetic child whose name is given as argument</i> <br/> |
Enrico Granata | 68506fb | 2011-08-22 16:10:25 +0000 | [diff] [blame] | 1022 | <font color=blue>def</font> get_child_at_index(self,index): <br/> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 1023 | <i>this call should return a new LLDB SBValue object representing the child at the index given as argument</i> <br/> |
Enrico Granata | 68506fb | 2011-08-22 16:10:25 +0000 | [diff] [blame] | 1024 | <font color=blue>def</font> update(self): <br/> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 1025 | <i>this call should be used to update the internal state of this Python object whenever the state of the variables in LLDB changes.</i><sup>[1]</sup><br/> |
Enrico Granata | 68506fb | 2011-08-22 16:10:25 +0000 | [diff] [blame] | 1026 | </code> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 1027 | <sup>[1]</sup> Currently this method is optional, because the internal state of synthetic children providers will not be preserved. However, this is meant to change in future versions of LLDB. |
Enrico Granata | 7e65503 | 2011-08-24 01:32:46 +0000 | [diff] [blame] | 1028 | <p>For examples of how synthetic children are created, you are encouraged to look at <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/synthetic/">examples/synthetic</a> in the LLDB trunk. |
| 1029 | You may especially want to begin looking at <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/synthetic/StdVectorSynthProvider.py">StdVector</a> to get |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 1030 | a feel for this feature, as it is a relatively easy and well commented example.</p> |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 1031 | <p>While the <code>update</code> method is optional, the design pattern consistently used in synthetic providers shipping with LLDB |
| 1032 | is to use the <code>__init__</code> to store the SBValue instance as a part of <code>self</code>, and then call <code>update</code> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 1033 | to perform the actual initialization. This pattern should make for a transparent transition to a future version of LLDB that persists synthetic children. For example:</p> |
| 1034 | <code> |
| 1035 | <font color=blue>def</font> __init__(self, valobj, dict):<br/> |
| 1036 | self.valobj = valobj;<br/> |
| 1037 | self.update() |
| 1038 | </code> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 1039 | <p>Once a synthetic children provider is written, one must load it into LLDB before it can be used. |
| 1040 | Currently, one can use the LLDB <code>script</code> command to type Python code interactively, |
| 1041 | or use the <code>script import <i>module</i></code> command to load Python code from a Python module |
| 1042 | (ordinary rules apply to importing modules this way). A third option is to type the code for |
| 1043 | the provider class interactively while adding it.</p> |
| 1044 | |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 1045 | <p>For example, let's pretend we have a class <code>Foo</code> for which a synthetic children provider class |
| 1046 | <code>Foo_Provider</code> is available, in a Python module named <code>Foo_Tools</code>. The following interaction |
| 1047 | sets <code>Foo_Provider</code> as a synthetic children provider in LLDB:</p> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 1048 | |
| 1049 | <table class="stats" width="620" cellspacing="0"> |
| 1050 | <td class="content"> |
| 1051 | <b>(lldb)</b> script import Foo_Tools<br/> |
| 1052 | <b>(lldb)</b> type synthetic add Foo --python-class Foo_Tools.Foo_Provider |
| 1053 | </td> |
| 1054 | <table> |
| 1055 | <code> <b>(lldb)</b> frame variable a_foo<br/> |
| 1056 | (Foo) a_foo = {<br/> |
| 1057 | x = 1<br/> |
| 1058 | y = "Hello world"<br/> |
| 1059 | } <br/> |
| 1060 | </code> </p> |
| 1061 | |
| 1062 | <p>Currently, in LLDB <a href="http://llvm.org/svn/llvm-project/lldb/trunk/">top of tree</a>, synthetic children providers are enabled for |
| 1063 | <code>std::vector<T></code>, <code>std::list<T></code> and <code>std::map<K,V></code>.</p> |
| 1064 | |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 1065 | <p>Synthetic children extend summary strings by enabling a new special variable: <code>${svar</code>.<br/> |
| 1066 | This symbol tells LLDB to refer expression paths to the |
| 1067 | synthetic children instead of the real ones. For instance,</p> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 1068 | |
| 1069 | <table class="stats" width="620" cellspacing="0"> |
| 1070 | <td class="content"> |
| 1071 | <b>(lldb)</b> type summary add --expand -x "std::vector<" --summary-string "${svar%#} items" |
| 1072 | </td> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 1073 | </table> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 1074 | <code> <b>(lldb)</b> frame variable numbers<br/> |
| 1075 | (std::vector<int>) numbers = 4 items {<br/> |
| 1076 | (int) [0] = 1<br/> |
| 1077 | (int) [1] = 12<br/> |
| 1078 | (int) [2] = 123<br/> |
| 1079 | (int) [3] = 1234<br/> |
| 1080 | }<br/> |
| 1081 | </code> </p> |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 1082 | <p>In some cases, if LLDB is unable to use the real object to get a child specified in an expression path, it will automatically refer to the |
| 1083 | synthetic children. While in summaries it is best to always use <code>${svar</code> to make your intentions clearer, interactive debugging |
| 1084 | can benefit from this behavior, as in: |
| 1085 | <code> <b>(lldb)</b> frame variable numbers[0] numbers[1]<br/> |
| 1086 | (int) numbers[0] = 1<br/> |
| 1087 | (int) numbers[1] = 12<br/> |
| 1088 | </code> </p> |
| 1089 | Unlike many other visualization features, however, the access to synthetic children only works when using <code>frame variable</code>, and is |
| 1090 | not supported in <code>expression</code>:<br/> |
| 1091 | <code> <b>(lldb)</b> expression numbers[0]<br/> |
| 1092 | Error [IRForTarget]: Call to a function '_ZNSt33vector<int, std::allocator<int> >ixEm' that is not present in the target<br/> |
| 1093 | error: Couldn't convert the expression to DWARF<br/> |
| 1094 | </code> </p> |
| 1095 | The reason for this is that classes might have an overloaded <code><font color="blue">operator</font> []</code>, or other special provisions |
| 1096 | and the <code>expression</code> command ignores synthetic children when evaluating its arguments. |
Enrico Granata | 68506fb | 2011-08-22 16:10:25 +0000 | [diff] [blame] | 1097 | </div> |
| 1098 | </div> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 1099 | |
| 1100 | <div class="post"> |
| 1101 | <h1 class="postheader">Filters</h1> |
| 1102 | <div class="postcontent"> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 1103 | <p>Filters are a solution to the display of complex classes. |
| 1104 | At times, classes have many member variables but not all of these are actually |
| 1105 | necessary for the user to see.</p> |
| 1106 | <p>A filter will solve this issue by only letting the user see those member |
| 1107 | variables he cares about. Of course, the equivalent of a filter can be implemented easily |
| 1108 | using synthetic children, but a filter lets you get the job done without having to write |
| 1109 | Python code.</p> |
| 1110 | <p>For instance, if your class <code>Foobar</code> has member variables named <code>A</code> thru <code>Z</code>, but you only need to see |
| 1111 | the ones named <code>B</code>, <code>H</code> and <code>Q</code>, you can define a filter: |
| 1112 | <table class="stats" width="620" cellspacing="0"> |
| 1113 | <td class="content"> |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 1114 | <b>(lldb)</b> type filter add Foobar --child B --child H --child Q |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 1115 | </td> |
Enrico Granata | 097e555 | 2011-08-24 04:53:31 +0000 | [diff] [blame] | 1116 | </table> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 1117 | <code> <b>(lldb)</b> frame variable a_foobar<br/> |
| 1118 | (Foobar) a_foobar = {<br/> |
| 1119 | (int) B = 1<br/> |
| 1120 | (char) H = 'H'<br/> |
| 1121 | (std::string) Q = "Hello world"<br/> |
| 1122 | }<br/> |
| 1123 | </code> </p> |
Enrico Granata | 097e555 | 2011-08-24 04:53:31 +0000 | [diff] [blame] | 1124 | </div> |
| 1125 | </div> |
| 1126 | |
| 1127 | <div class="post"> |
| 1128 | <h1 class="postheader">Objective-C dynamic type discovery</h1> |
| 1129 | <div class="postcontent"> |
| 1130 | <p>When doing Objective-C development, you may notice that some of your variables |
Enrico Granata | 9e4102f | 2011-09-07 19:20:42 +0000 | [diff] [blame] | 1131 | come out as of type <code>id</code> (for instance, items extracted from <code>NSArray</code>). |
| 1132 | While this does not influence the ability of the runtime to send messages to them, it could make it impossible for LLDB |
| 1133 | to determine the actual formatters for that object, given its type-based algorithm.</p> |
Enrico Granata | 097e555 | 2011-08-24 04:53:31 +0000 | [diff] [blame] | 1134 | <p>The debugger, however, can dynamically discover the type of an Objective-C |
| 1135 | variable, much like the runtime itself does when invoking a selector. In order |
| 1136 | to let LLDB do that, however, a special option to <code>frame variable</code> is |
| 1137 | required: <code>--dynamic-type</code>.</p> |
| 1138 | <p><code>--dynamic-type</code> can have one of three values: |
| 1139 | <ul> |
| 1140 | <li><code>no-dynamic-values</code>: the default, prevents dynamic type discovery</li> |
| 1141 | <li><code>no-run-target</code>: enables dynamic type discovery as long as running |
| 1142 | code on the target is not required</li> |
| 1143 | <li><code>run-target</code>: enables code execution on the target in order to perform |
| 1144 | dynamic type discovery</li> |
| 1145 | </ul> |
| 1146 | </p> |
| 1147 | <p> |
| 1148 | If you specify a value of either <code>no-run-target</code> or <code>run-target</code>, |
| 1149 | LLDB will detect the dynamic type of your variables and show the appropriate formatters |
| 1150 | for them. As an example: |
| 1151 | </p> |
| 1152 | <p><table class="stats" width="620" cellspacing="0"> |
| 1153 | <td class="content"> |
| 1154 | <b>(lldb)</b> frame variable ns_string --dynamic-type no-run-target --show-types |
| 1155 | </td> |
| 1156 | </table> |
| 1157 | <code>(id, dynamic type: __NSCFString) ns_string = 0x00000001001183d0 @"An NSString saying hello world"<br/> |
| 1158 | </code> |
| 1159 | <p> |
| 1160 | Because LLDB uses a detection algorithm that does not need to invoke any functions |
| 1161 | on the target process, <code>no-run-target</code> is enough for this to work. |
| 1162 | As a final sidenote on this, LLDB is currently able to provide a summary string for <code>NSString</code> |
| 1163 | that shows the content of the string, without requiring you to run code on the target |
| 1164 | process. <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/synthetic/CFString.py"> |
| 1165 | CFString.py</a> contains the code for such a Python summary provider (the code is well commented, |
| 1166 | but you may find it hard to follow if it is your first time dealing with LLDB formatting features) |
| 1167 | and <a href="http://llvm.org/svn/llvm-project/lldb/trunk/test/functionalities/data-formatter/data-formatter-objc/"> |
| 1168 | this test case</a> contains an usage example. |
| 1169 | </p> |
Enrico Granata | ef1923d | 2011-08-23 21:26:09 +0000 | [diff] [blame] | 1170 | </div> |
| 1171 | </div> |
| 1172 | |
Enrico Granata | 7e65503 | 2011-08-24 01:32:46 +0000 | [diff] [blame] | 1173 | <div class="post"> |
| 1174 | <h1 class="postheader">Categories</h1> |
| 1175 | <div class="postcontent"> |
| 1176 | <p>Categories are a way to group related formatters. For instance, LLDB itself groups |
| 1177 | the formatters for the C++ STL objects in a category named <code>gnu-libstdc++</code>. |
| 1178 | Basically, categories act like containers in which to store formatters for a same library |
| 1179 | or OS release.</p> |
| 1180 | <p>By default, three categories are created in LLDB: <code>system</code>, <code>gnu-libstdc++</code> and <code>default</code>. |
| 1181 | Every formatter that is not created inside a category, is by default a part of the <code>default</code> category. |
| 1182 | If you want to use a custom category for your formatters, all the <code>type ... add</code> (except for <code>type format add</code>), |
| 1183 | provide a <code>--category</code> (<code>-w</code>) option, that names the category to add the formatter to. |
| 1184 | To delete the formatter, you then have to specify the correct category.</p> |
| 1185 | <p>Categories can be in one of two states: enabled and disabled. A category is initially disabled, |
| 1186 | and can be enabled using the <code>type category enable</code> command. To disable an enabled category, |
| 1187 | the command to use is <code>type category disable</code>. The order in which categories are enabled or disabled |
| 1188 | is significant, in that LLDB uses that order when looking for formatters. Therefore, when you enable a category, it becomes |
Enrico Granata | 0c5c9a2 | 2011-09-08 00:50:01 +0000 | [diff] [blame] | 1189 | the first one to be searched. The default categories are enabled in such a way that the search order is: <code>default</code> |
| 1190 | then <code>gnu-libstdc++</code> then finally <code>system</code>. As said, <code>gnu-libstdc++</code> contains formatters for C++ STL |
| 1191 | data types. <code>system</code> contains formatters for <code>char*</code> and <code>char[]</code>, which reflect the behavior |
| 1192 | of previous versions of LLDB which had built-in formatters for these types. Because now these are formatters, you can even |
| 1193 | replace them with your own if so you wish.</p> |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 1194 | <p>There is no special command to create a category. When you place a formatter in a category, if that category does not |
| 1195 | exist, it is automatically created. For instance,</p> |
| 1196 | <p><table class="stats" width="620" cellspacing="0"> |
| 1197 | <td class="content"> |
| 1198 | <b>(lldb)</b> type summary add Foobar --summary-string "a foobar" --category newcategory |
| 1199 | </td> |
| 1200 | </table> |
| 1201 | automatically creates a (disabled) category named newcategory.</p> |
| 1202 | <p>Another way to create a new (empty) category, is to enable it, as in:</p> |
| 1203 | <p><table class="stats" width="620" cellspacing="0"> |
| 1204 | <td class="content"> |
| 1205 | <b>(lldb)</b> type category enable newcategory |
| 1206 | </td> |
| 1207 | </table> |
| 1208 | <p>However, in this case LLDB warns you that enabling an empty category has no effect. If you add formatters to the |
| 1209 | category after enabling it, they will be honored. But an empty category <i>per se</i> does not change the way any |
| 1210 | type is displayed. The reason the debugger warns you is that enabling an empty category might be a typo, and you |
| 1211 | effectively wanted to enable a similarly-named but not-empty category.</p> |
Enrico Granata | 7e65503 | 2011-08-24 01:32:46 +0000 | [diff] [blame] | 1212 | </div> |
| 1213 | </div> |
| 1214 | |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 1215 | <div class="post"> |
Enrico Granata | 68506fb | 2011-08-22 16:10:25 +0000 | [diff] [blame] | 1216 | <h1 class="postheader">Finding formatters 101</h1> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 1217 | <div class="postcontent"> |
| 1218 | <p>While the rules for finding an appropriate format for a |
| 1219 | type are relatively simple (just go through typedef |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 1220 | hierarchies), searching other formatters goes through |
Enrico Granata | 7e65503 | 2011-08-24 01:32:46 +0000 | [diff] [blame] | 1221 | a rather intricate set of rules. Namely, what happens is that LLDB |
| 1222 | starts looking in each enabled category, according to the order in which |
| 1223 | they were enabled (latest enabled first). In each category, LLDB does |
| 1224 | the following:</p> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 1225 | <ul> |
Enrico Granata | 68506fb | 2011-08-22 16:10:25 +0000 | [diff] [blame] | 1226 | <li>If there is a formatter for the type of the variable, |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 1227 | use it</li> |
Enrico Granata | 68506fb | 2011-08-22 16:10:25 +0000 | [diff] [blame] | 1228 | <li>If this object is a pointer, and there is a formatter |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 1229 | for the pointee type that does not skip pointers, use |
| 1230 | it</li> |
| 1231 | <li>If this object is a reference, and there is a |
Enrico Granata | 0c5c9a2 | 2011-09-08 00:50:01 +0000 | [diff] [blame] | 1232 | formatter for the referred type that does not skip |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 1233 | references, use it</li> |
| 1234 | <li>If this object is an Objective-C class with a parent |
| 1235 | class, look at the parent class (and parent of parent, |
Enrico Granata | 68506fb | 2011-08-22 16:10:25 +0000 | [diff] [blame] | 1236 | ...). This phase can be based upon the actual type of |
| 1237 | the object as inferred by the value of its <code>isa</code> |
| 1238 | pointer, or upon the debugging information inferred by the |
| 1239 | debugger. The user can use the dynamic typing settings to |
| 1240 | elect one or the other behavior.</li> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 1241 | <li>If this object is a C++ class with base classes, |
| 1242 | look at base classes (and bases of bases, ...)</li> |
| 1243 | <li>If this object is a C++ class with virtual base |
| 1244 | classes, look at the virtual base classes (and bases |
| 1245 | of bases, ...)</li> |
| 1246 | <li>If this object's type is a typedef, go through |
Enrico Granata | 86e7c3e | 2011-07-12 22:56:10 +0000 | [diff] [blame] | 1247 | typedef hierarchy (LLDB might not be able to do this if |
| 1248 | the compiler has not emitted enough information. If the |
| 1249 | required information to traverse typedef hierarchies is |
| 1250 | missing, type cascading will not work. The |
| 1251 | <a href="http://clang.llvm.org/">clang compiler</a>, |
| 1252 | part of the LLVM project, emits the correct debugging |
| 1253 | information for LLDB to cascade)</li> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 1254 | <li>If everything has failed, repeat the above search, |
| 1255 | looking for regular expressions instead of exact |
| 1256 | matches</li> |
| 1257 | </ul> |
Enrico Granata | 7e65503 | 2011-08-24 01:32:46 +0000 | [diff] [blame] | 1258 | <p>If any of those attempts returned a valid formatter to be used, |
| 1259 | that one is used, and the search is terminated (without going to look |
| 1260 | in other categories). If nothing was found in the current category, the next |
| 1261 | enabled category is scanned according to the same algorithm. If there are no |
| 1262 | more enabled categories, the search has failed.</p> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 1263 | </div> |
| 1264 | </div> |
| 1265 | <div class="post"> |
| 1266 | <h1 class="postheader">TODOs</h1> |
| 1267 | <div class="postcontent"> |
| 1268 | <ul> |
| 1269 | <li>There's no way to do multiple dereferencing, and you |
| 1270 | need to be careful what the dereferencing operation is |
| 1271 | binding to in complicated scenarios</li> |
Enrico Granata | 68506fb | 2011-08-22 16:10:25 +0000 | [diff] [blame] | 1272 | <li>Synthetic children providers cannot have a permanent state</li> |
Enrico Granata | 3db17ae | 2011-08-24 17:12:47 +0000 | [diff] [blame] | 1273 | <li>Smarter algorithm to detect possible typos in category names</li> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 1274 | <li><code>type format add</code> does not support the <code>-x</code> |
| 1275 | option</li> |
Enrico Granata | ff78238 | 2011-07-08 02:51:01 +0000 | [diff] [blame] | 1276 | </ul> |
| 1277 | </div> |
| 1278 | </div> |
| 1279 | </div> |
| 1280 | </div> |
| 1281 | </div> |
| 1282 | </body> |
| 1283 | </html> |