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