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

Greg Clayton

2012-11-16 23:50:32 +0000

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>

<title>Debug Sybmols on Mac OS X</title>

</head>

<body>

The <strong>LLDB</strong> Debugger

</div>

<h1 class="postheader">Debug Symbols on MacOSX</h1>

22

23

<p>On MacOSX, debug symbols are often in stand alone bundles called <b>dSYM</b> files.

24

These are bundles that contain DWARF debug information and other resources related to

25

builds and debug info.</p>

26

<p>The DebugSymbols.framework framework helps locate dSYM files when given a UUID. It can

27

locate the symbols using a variety of methods:</p>

28

<ul>

29

<li>Spotlight</li>

30

<li>Explicit search paths</li>

31

<li>Implicit search paths</li>

32

<li>File mapped UUID paths</li>

33

<li>Running one or more shell scripts</li>

34

</ul>

35

<p>DebugSymbols.framework also has global defaults that can be modified to allow

36

all of the debug tools (lldb, gdb, sample, CoreSymbolication.framework) to easily

37

find important debug symbols. The domain for the DebugSymbols.framework defaults

38

is <b>com.apple.DebugSymbols</b>, and the defaults can be read, written or modified

39

using the <b>defaults</b> shell command:

40

<code><pre><tt><b>% defaults read com.apple.DebugSymbols

41

% defaults write com.apple.DebugSymbols KEY ...

42

% defaults delete com.apple.DebugSymbols KEY</b>

43

</tt></pre></code>

44

45

<p>The following is a list of the defaults key value

46

setting pairs that can be used to enhance symbol location:</p>

47

48

<tr>

49

<td class="hed" width="20%">Defaults Key</td>

50

<td class="hed" width="70%">Description</td>

</tr>

<tr>

<b>DBGFileMappedPaths</b>

56

</td>

57

58

This default can be specified as a single string, or an array of strings.

59

Each string represents a directory that contains file mapped UUID values

60

that point to dSYM files. See the "File Mapped UUID Directories" section

61

below for more details. Whenever DebugSymbols.framework is asked to lookup

62

a dSYM file, it will first look in any file mapped UUID directories

for a quick match.

</td>

</tr>

<code><pre><tt><b>% defaults write com.apple.DebugSymbols DBGFileMappedPaths -string /path/to/uuidmap1</b>

68

<b>% defaults write com.apple.DebugSymbols DBGFileMappedPaths -array /path/to/uuidmap1

69

/path/to/uuidmap2</b>

</tt></pre></code>

</tr>

<tr>

<b>DBGShellCommands</b>

75

</td>

76

77

This default can be specified as a single string, or an array of strings.

78

Specifies a shell script that will get run in order to find the dSYM.

79

The shell script will be run given a single UUID value as the shell

80

command arguments and the shell command is expected to return a property

81

list. See the property list format defined below.

</td>

</tr>

<code><pre><tt><b>% defaults write com.apple.DebugSymbols DBGShellCommands -string /path/to/script1</b>

86

<b>% defaults write com.apple.DebugSymbols DBGShellCommands -array /path/to/script1

/path/to/script2</b>

</tt></pre></code>

</td>

</tr>

<tr>

<b>DBGSpotlightPaths</b>

94

</td>

95

96

Specifies the directories to limit spotlight searches to as a string or array of strings. When any

97

other defaults are supplied to <b>com.apple.DebugSymbols</b>, spotlight

98

searches will be disabled unless this default is set to an empty array:

</td>

</tr>

<code><pre><tt><font color="green"># Specify an empty array to keep Spotlight searches enabled in all locations</font>

103

<b>% defaults write com.apple.DebugSymbols DBGSpotlightPaths -array</b>

104

105

<font color="green"># Specify an array of paths to limit spotlight searches to certain directories</font>

106

<b>% defaults write com.apple.DebugSymbols DBGSpotlightPaths -array /path/dir1 /path/dir2</b>

</tt></pre></code>

</td>

</tr>

</table>

</div>

</div>

<h1 class="postheader">Shell Script Property List Format</h1>

116

117

<p>Shell scripts that are specified with the <b>DBGShellCommands</b> defaults key

118

will be run in the order in which they are specified until a match is found.

119

The shell script will be invoked with a single UUID string value like

120

"23516BE4-29BE-350C-91C9-F36E7999F0F1". The shell script must respond with a

Greg Clayton

5ee8d64

2012-11-19 17:38:24 +0000

[diff] [blame]

121

property list being written to STDOUT.

122

The property list returned must contain UUID string values as the root key values, with

123

a dictionary for each UUID. The dictionaries can contain one or more of the following keys:

Greg Clayton

e8ec5ac

2012-11-16 23:50:32 +0000

[diff] [blame]

<tr>

<td class="hed" width="70%">Description</td>

</tr>

<tr>

<b>DBGArchitecture</b>

133

</td>

134

<td class="content">A textual architecture or target triple like "x86_64", "i386", or "x86_64-apple-macosx".

</td>

</tr>

<tr>

<b>DBGBuildSourcePath</b>

140

</td>

141

<td class="content">A path prefix that was used when building the dSYM file. The debug information will

142

contain paths with this prefix.

</td>

</tr>

<tr>

<b>DBGSourcePath</b>

</td>

<td class="content">A path prefix for where the sources exist after the build has completed. Often when

150

building projects, build machines will host the sources in a temporary directory while building, then

151

move the sources to another location for archiving. If the paths in the debug info don't match where

152

the sources are currently hosted, then specifying this path along with the <b>DBGBuildSourcePath</b>

153

will help the developer tools always show you sources when debugging or symbolicating.

</td>

</tr>

<tr>

<b>DBGDSYMPath</b>

</td>

<td class="content">A path to the dSYM mach-o file inside the dSYM bundle.

</td>

</tr>

<tr>

<b>DBGSymbolRichExecutable</b>

166

</td>

167

<td class="content">A path to the symbol rich executable. Binaries are often stripped after

168

being built and packaged into a release. If your build systems saves an unstripped executable

169

a path to this executable can be provided.

</td>

</tr>

<tr>

<b>DBGError</b>

</td>

<td class="content">If a binary can not be located for the supplied UUID, a user readable error

can be returned.

</td>

</tr>

</table>

<p>Below is a sample shell script output for a binary that contains two architectures:

183

184

<?xml version="1.0" encoding="UTF-8"?>

185

<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

<dict>

<dict>

<key>DBGArchitecture</key>

191

192

<key>DBGBuildSourcePath</key>

193

<string>/path/to/build/sources</string>

194

<key>DBGSourcePath</key>

195

<string>/path/to/actual/sources</string>

196

<key>DBGDSYMPath</key>

197

<string>/path/to/foo.dSYM/Contents/Resources/DWARF/foo</string>

198

<key>DBGSymbolRichExecutable</key>

199

<string>/path/to/unstripped/exectuable</string>

</dict>

<dict>

<key>DBGArchitecture</key>

204

205

<key>DBGBuildSourcePath</key>

206

<string>/path/to/build/sources</string>

207

<key>DBGSourcePath</key>

208

<string>/path/to/actual/sources</string>

209

<key>DBGDSYMPath</key>

210

<string>/path/to/foo.dSYM/Contents/Resources/DWARF/foo</string>

211

<key>DBGSymbolRichExecutable</key>

212

<string>/path/to/unstripped/exectuable</string>

</dict>

</dict>

</plist>

</tt></pre></code>

Greg Clayton

2012-11-19 17:38:24 +0000

[diff] [blame]

218

<p>There is no timeout imposed on a shell script when is it asked to locate a dSYM file, so be careful to not make a shell

219

script that has high latency or takes a long time to download unless this

220

is really what you want. This can slow down debug sessions in LLDB and GDB, symbolication

221

with CoreSymbolication or Report Crash, with no visible feedback to the user. You can

222

quickly return a plist with a single <b>DBGError</b> key that indicates a timeout

223

has been reached. You might also want to exec new processes to do the downloads so

224

that if you return an error that indicates a timeout, your download can still proceed

225

after your shell script has exited so subsequent debug sessions can use the cached files.

226

It is also important to track when a current download is in progress in case you get multiple requests for the same UUID so

227

that you don't end up downloading the same file simultaneously. Also you will want

228

to verify the download was successful and then and only then place the file into the

229

cache for tools that will cache files locally.

Greg Clayton

e8ec5ac

2012-11-16 23:50:32 +0000

[diff] [blame]

</div>

</div>

<h1 class="postheader">Embedding UUID property lists inside the dSYM bundles</h1>

235

236

<p>Since dSYM files are bundles, you can also place UUID info plists files inside

237

your dSYM bundles in the <b>Contents/Resources</b> directory. One of the main

238

reasons to create the UUID plists inside the dSYM bundles

239

is that it will help LLDB and other developer tools show you source. LLDB currently

240

knows how to check for these plist files so it can automatically remap the source

241

location information in the debug info.

242

243

<p>If we take the two UUID values from the returns plist above, we can split

244

them out and save then in the dSYM bundle:

245

246

<code><pre><tt><b>% ls /path/to/foo.dSYM/Contents/Resources</b>

247

23516BE4-29BE-350C-91C9-F36E7999F0F1.plist

248

A40597AA-5529-3337-8C09-D8A014EB1578.plist

249

250

<b>% cat /path/to/foo.dSYM/Contents/Resources/23516BE4-29BE-350C-91C9-F36E7999F0F1.plist</b>

251

<?xml version="1.0" encoding="UTF-8"?>

252

<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">

253

254

<dict>

255

<key>DBGArchitecture</key>

256

257

<key>DBGBuildSourcePath</key>

258

<string>/path/to/build/sources</string>

259

<key>DBGSourcePath</key>

260

<string>/path/to/actual/sources</string>

261

<key>DBGDSYMPath</key>

262

<string>/path/to/foo.dSYM/Contents/Resources/DWARF/foo</string>

263

<key>DBGSymbolRichExecutable</key>

264

<string>/path/to/unstripped/exectuable</string>

</dict>

</plist>

</tt></pre></code>

<p>Note that the output is very close to what is needed by shell script output,

270

so making the results of your shell script will be very easy to create by

271

combining two plists into a single one where you take the UUID and use it a

272

string key, and the value is the contents of the plist.

</div>

</div>

<h1 class="postheader">File Mapped UUID Directories</h1>

280

281

<p>File Mapped directories can be used for efficient dSYM file lookups for

282

local or remote dSYM files. The UUID is broken up by splitting the first

283

20 hex digits into 4 character chunks, and a directory is created for each

284

chunk, and each subsequent directory is created inside the previous one.

285

A symlink is then created whose name is the last 12 hex digits in the deepest

286

directory. The symlinks value is a full path to the mach-o files inside the

287

dSYM bundle which contains the DWARF. Whenever DebugSymbols.framework is asked

288

to lookup a dSYM file, it will first look in any file mapped UUID directories

289

for a quick match if the defaults are appropriately set.

290

291

<p>For example, if we take the sample UUID plist inforamtion from above, we

292

can create a File Mapped UUID directory cache in <b>~/Library/SymbolCache/dsyms/uuids</b>.

293

We can easily see how things are laid out:

294

295

<code><pre><tt><b>% find ~/Library/SymbolCache/dsyms/uuids -type l</b>

296

~/Library/SymbolCache/dsyms/uuids/2351/6BE4/29BE/350C/91C9/F36E7999F0F1

297

~/Library/SymbolCache/dsyms/uuids/A405/97AA/5529/3337/8C09/D8A014EB1578

298

</tt></pre></code>

299

300

<p>The last entries in these file mapped directories are symlinks to the actual dsym mach file in the dsym bundle:

301

302

<code><pre><tt><b>% ls -lAF ~/Library/SymbolCache/dsyms/uuids/2351/6BE4/29BE/350C/91C9/F36E7999F0F1</b>

303

~/Library/SymbolCache/dsyms/uuids/2351/6BE4/29BE/350C/91C9/F36E7999F0F1@ -> ../../../../../../dsyms/foo.dSYM/Contents/Resources/DWARF/foo

304

</tt></pre></code>

305

<p>Then you can also tell DebugSymbols to check this UUID file map cache using:

306

307

<code><pre><tt><b>% defaults write com.apple.DebugSymbols DBGFileMappedPaths ~/Library/SymbolCache/dsyms/uuids</b>

</tt></pre></code>

</div>

</div>

<h1 class="postheader">dSYM Locating Shell Script Tips</h1>

316

317

318

<p>One possible implementation of a dSYM finding shell script is to have the script

319

download and cache files locally in a known location. Then create a UUID map

320

for each UUID value that was found in a local UUID File Map cache so the next query for the dSYM

321

file will be able to use the cached version. So the shell script is used to

322

initially download and cache the file, and subsequent accesses will use the

323

cache and avoid calling the shell script.

324

325

<p>Then the defaults for DebugSymbols.framework will entail enabling your shell script,

326

enabling the file mapped path setting so that already downloaded dSYMS fill quickly

327

be found without needing to run the shell script every time, and also leaving spotlight enabled

328

so that other normal dSYM files are still found:

329

330

<code><pre><tt><b>% defaults write com.apple.DebugSymbols DBGShellCommands /path/to/shellscript

331

% defaults write com.apple.DebugSymbols DBGFileMappedPaths ~/Library/SymbolCache/dsyms/uuids

332

% defaults write com.apple.DebugSymbols DBGSpotlightPaths -array</b>

333

</tt></pre></code>

334

335

Hopefully this helps explain how DebugSymbols.framework can help any company

336

implement a smart symbol finding and caching with minimal overhead.

</p>

</div>

</div>

</div>

</div>

</div>

</body>

</html>