--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">\r
+<html xmlns="http://www.w3.org/1999/xhtml">\r
+<head>\r
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />\r
+<link href="style.css" rel="stylesheet" type="text/css" />\r
+<title>Debug Sybmols on Mac OS X</title>\r
+</head>\r
+\r
+<body>\r
+ <div class="www_title">\r
+ The <strong>LLDB</strong> Debugger\r
+ </div>\r
+ \r
+<div id="container">\r
+ <div id="content">\r
+ \r
+ <!--#include virtual="sidebar.incl"-->\r
+ \r
+ <div id="middle">\r
+ <div class="post">\r
+ <h1 class="postheader">Debug Symbols on MacOSX</h1>\r
+ <div class="postcontent">\r
+ <p>On MacOSX, debug symbols are often in stand alone bundles called <b>dSYM</b> files. \r
+ These are bundles that contain DWARF debug information and other resources related to\r
+ builds and debug info.</p>\r
+ <p>The DebugSymbols.framework framework helps locate dSYM files when given a UUID. It can\r
+ locate the symbols using a variety of methods:</p>\r
+ <ul>\r
+ <li>Spotlight</li>\r
+ <li>Explicit search paths</li>\r
+ <li>Implicit search paths</li>\r
+ <li>File mapped UUID paths</li>\r
+ <li>Running one or more shell scripts</li>\r
+ </ul>\r
+ <p>DebugSymbols.framework also has global defaults that can be modified to allow\r
+ all of the debug tools (lldb, gdb, sample, CoreSymbolication.framework) to easily\r
+ find important debug symbols. The domain for the DebugSymbols.framework defaults\r
+ is <b>com.apple.DebugSymbols</b>, and the defaults can be read, written or modified\r
+ using the <b>defaults</b> shell command:\r
+<code><pre><tt><b>% defaults read com.apple.DebugSymbols\r
+% defaults write com.apple.DebugSymbols KEY ...\r
+% defaults delete com.apple.DebugSymbols KEY</b>\r
+</tt></pre></code>\r
+ \r
+ <p>The following is a list of the defaults key value\r
+ setting pairs that can be used to enhance symbol location:</p>\r
+ <table class="stats" width="620" cellspacing="0">\r
+ <tr>\r
+ <td class="hed" width="20%">Defaults Key</td>\r
+ <td class="hed" width="70%">Description</td>\r
+ </tr>\r
+\r
+ <tr>\r
+ <td class="content">\r
+ <b>DBGFileMappedPaths</b>\r
+ </td>\r
+ <td class="content">\r
+ This default can be specified as a single string, or an array of strings.\r
+ Each string represents a directory that contains file mapped UUID values\r
+ that point to dSYM files. See the "File Mapped UUID Directories" section\r
+ below for more details. Whenever DebugSymbols.framework is asked to lookup \r
+ a dSYM file, it will first look in any file mapped UUID directories\r
+ for a quick match.\r
+ </td>\r
+ </tr>\r
+ <td class="content" colspan="2">\r
+<code><pre><tt><b>% defaults write com.apple.DebugSymbols DBGFileMappedPaths -string /path/to/uuidmap1</b>\r
+<b>% defaults write com.apple.DebugSymbols DBGFileMappedPaths -array /path/to/uuidmap1 \r
+ /path/to/uuidmap2</b>\r
+</tt></pre></code>\r
+ </tr>\r
+ <tr>\r
+ <td class="content">\r
+ <b>DBGShellCommands</b>\r
+ </td>\r
+ <td class="content">\r
+ This default can be specified as a single string, or an array of strings.\r
+ Specifies a shell script that will get run in order to find the dSYM.\r
+ The shell script will be run given a single UUID value as the shell\r
+ command arguments and the shell command is expected to return a property\r
+ list. See the property list format defined below.\r
+ </td>\r
+ </tr>\r
+ <td class="content" colspan="2">\r
+<code><pre><tt><b>% defaults write com.apple.DebugSymbols DBGShellCommands -string /path/to/script1</b>\r
+<b>% defaults write com.apple.DebugSymbols DBGShellCommands -array /path/to/script1\r
+ /path/to/script2</b>\r
+</tt></pre></code>\r
+ </td>\r
+ </tr>\r
+ <tr>\r
+ <td class="content">\r
+ <b>DBGSpotlightPaths</b>\r
+ </td>\r
+ <td class="content">\r
+ Specifies the directories to limit spotlight searches to as a string or array of strings. When any \r
+ other defaults are supplied to <b>com.apple.DebugSymbols</b>, spotlight\r
+ searches will be disabled unless this default is set to an empty array:\r
+ </td>\r
+ </tr>\r
+ <td class="content" colspan="2">\r
+<code><pre><tt><font color="green"># Specify an empty array to keep Spotlight searches enabled in all locations</font>\r
+<b>% defaults write com.apple.DebugSymbols DBGSpotlightPaths -array</b>\r
+\r
+<font color="green"># Specify an array of paths to limit spotlight searches to certain directories</font>\r
+<b>% defaults write com.apple.DebugSymbols DBGSpotlightPaths -array /path/dir1 /path/dir2</b>\r
+</tt></pre></code>\r
+ </td>\r
+ </tr>\r
+ </table>\r
+ </div>\r
+ <div class="postfooter"></div>\r
+ </div>\r
+ <div class="post">\r
+ <h1 class="postheader">Shell Script Property List Format</h1>\r
+ <div class="postcontent">\r
+<p>Shell scripts that are specified with the <b>DBGShellCommands</b> defaults key\r
+will be run in the order in which they are specified until a match is found.\r
+The shell script will be invoked with a single UUID string value like \r
+"23516BE4-29BE-350C-91C9-F36E7999F0F1". The shell script must respond with a \r
+property list being written to STDOUT. The property list must contain UUID\r
+string values as the root key values, with a dictionary for each UUID. The dictionaries\r
+can contain one or more of the following keys:\r
+\r
+ <table class="stats" width="620" cellspacing="0">\r
+ <tr>\r
+ <td class="hed" width="20%">Key</td>\r
+ <td class="hed" width="70%">Description</td>\r
+ </tr>\r
+ <tr>\r
+ <td class="content">\r
+ <b>DBGArchitecture</b>\r
+ </td>\r
+ <td class="content">A textual architecture or target triple like "x86_64", "i386", or "x86_64-apple-macosx".\r
+ </td>\r
+ </tr>\r
+ <tr>\r
+ <td class="content">\r
+ <b>DBGBuildSourcePath</b>\r
+ </td>\r
+ <td class="content">A path prefix that was used when building the dSYM file. The debug information will\r
+ contain paths with this prefix.\r
+ </td>\r
+ </tr>\r
+ <tr>\r
+ <td class="content">\r
+ <b>DBGSourcePath</b>\r
+ </td>\r
+ <td class="content">A path prefix for where the sources exist after the build has completed. Often when\r
+ building projects, build machines will host the sources in a temporary directory while building, then\r
+ move the sources to another location for archiving. If the paths in the debug info don't match where\r
+ the sources are currently hosted, then specifying this path along with the <b>DBGBuildSourcePath</b>\r
+ will help the developer tools always show you sources when debugging or symbolicating.\r
+ </td>\r
+ </tr>\r
+ <tr>\r
+ <td class="content">\r
+ <b>DBGDSYMPath</b>\r
+ </td>\r
+ <td class="content">A path to the dSYM mach-o file inside the dSYM bundle.\r
+ </td>\r
+ </tr>\r
+ <tr>\r
+ <td class="content">\r
+ <b>DBGSymbolRichExecutable</b>\r
+ </td>\r
+ <td class="content">A path to the symbol rich executable. Binaries are often stripped after\r
+ being built and packaged into a release. If your build systems saves an unstripped executable\r
+ a path to this executable can be provided.\r
+ </td>\r
+ </tr>\r
+ <tr>\r
+ <td class="content">\r
+ <b>DBGError</b>\r
+ </td>\r
+ <td class="content">If a binary can not be located for the supplied UUID, a user readable error\r
+ can be returned.\r
+ </td>\r
+ </tr>\r
+ </table>\r
+\r
+<p>Below is a sample shell script output for a binary that contains two architectures:\r
+<code><pre><tt>\r
+<?xml version="1.0" encoding="UTF-8"?>\r
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\r
+<plist version="1.0">\r
+<dict>\r
+ <key>23516BE4-29BE-350C-91C9-F36E7999F0F1</key>\r
+ <dict>\r
+ <key>DBGArchitecture</key>\r
+ <string>i386</string>\r
+ <key>DBGBuildSourcePath</key>\r
+ <string>/path/to/build/sources</string>\r
+ <key>DBGSourcePath</key>\r
+ <string>/path/to/actual/sources</string>\r
+ <key>DBGDSYMPath</key>\r
+ <string>/path/to/foo.dSYM/Contents/Resources/DWARF/foo</string>\r
+ <key>DBGSymbolRichExecutable</key>\r
+ <string>/path/to/unstripped/exectuable</string>\r
+ </dict>\r
+ <key>A40597AA-5529-3337-8C09-D8A014EB1578</key>\r
+ <dict>\r
+ <key>DBGArchitecture</key>\r
+ <string>x86_64</string>\r
+ <key>DBGBuildSourcePath</key>\r
+ <string>/path/to/build/sources</string>\r
+ <key>DBGSourcePath</key>\r
+ <string>/path/to/actual/sources</string>\r
+ <key>DBGDSYMPath</key>\r
+ <string>/path/to/foo.dSYM/Contents/Resources/DWARF/foo</string>\r
+ <key>DBGSymbolRichExecutable</key>\r
+ <string>/path/to/unstripped/exectuable</string>\r
+ </dict>\r
+</dict>\r
+</plist>\r
+</tt></pre></code>\r
+\r
+ </div>\r
+ <div class="postfooter"></div>\r
+ </div>\r
+ <div class="post">\r
+ <h1 class="postheader">Embedding UUID property lists inside the dSYM bundles</h1>\r
+ <div class="postcontent">\r
+<p>Since dSYM files are bundles, you can also place UUID info plists files inside \r
+your dSYM bundles in the <b>Contents/Resources</b> directory. One of the main \r
+reasons to create the UUID plists inside the dSYM bundles\r
+is that it will help LLDB and other developer tools show you source. LLDB currently\r
+knows how to check for these plist files so it can automatically remap the source\r
+location information in the debug info.\r
+\r
+<p>If we take the two UUID values from the returns plist above, we can split \r
+them out and save then in the dSYM bundle:\r
+\r
+<code><pre><tt><b>% ls /path/to/foo.dSYM/Contents/Resources</b>\r
+23516BE4-29BE-350C-91C9-F36E7999F0F1.plist\r
+A40597AA-5529-3337-8C09-D8A014EB1578.plist\r
+\r
+<b>% cat /path/to/foo.dSYM/Contents/Resources/23516BE4-29BE-350C-91C9-F36E7999F0F1.plist</b>\r
+<?xml version="1.0" encoding="UTF-8"?>\r
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">\r
+<plist version="1.0">\r
+<dict>\r
+ <key>DBGArchitecture</key>\r
+ <string>i386</string>\r
+ <key>DBGBuildSourcePath</key>\r
+ <string>/path/to/build/sources</string>\r
+ <key>DBGSourcePath</key>\r
+ <string>/path/to/actual/sources</string>\r
+ <key>DBGDSYMPath</key>\r
+ <string>/path/to/foo.dSYM/Contents/Resources/DWARF/foo</string>\r
+ <key>DBGSymbolRichExecutable</key>\r
+ <string>/path/to/unstripped/exectuable</string>\r
+</dict>\r
+</plist>\r
+</tt></pre></code>\r
+\r
+<p>Note that the output is very close to what is needed by shell script output, \r
+so making the results of your shell script will be very easy to create by \r
+combining two plists into a single one where you take the UUID and use it a\r
+ string key, and the value is the contents of the plist.\r
+\r
+\r
+ </div>\r
+ <div class="postfooter"></div>\r
+ </div>\r
+ <div class="post">\r
+ <h1 class="postheader">File Mapped UUID Directories</h1>\r
+ <div class="postcontent">\r
+<p>File Mapped directories can be used for efficient dSYM file lookups for\r
+local or remote dSYM files. The UUID is broken up by splitting the first \r
+20 hex digits into 4 character chunks, and a directory is created for each \r
+chunk, and each subsequent directory is created inside the previous one. \r
+A symlink is then created whose name is the last 12 hex digits in the deepest\r
+directory. The symlinks value is a full path to the mach-o files inside the\r
+dSYM bundle which contains the DWARF. Whenever DebugSymbols.framework is asked\r
+to lookup a dSYM file, it will first look in any file mapped UUID directories\r
+for a quick match if the defaults are appropriately set.\r
+\r
+<p>For example, if we take the sample UUID plist inforamtion from above, we\r
+can create a File Mapped UUID directory cache in <b>~/Library/SymbolCache/dsyms/uuids</b>.\r
+We can easily see how things are laid out:\r
+\r
+<code><pre><tt><b>% find ~/Library/SymbolCache/dsyms/uuids -type l</b>\r
+~/Library/SymbolCache/dsyms/uuids/2351/6BE4/29BE/350C/91C9/F36E7999F0F1\r
+~/Library/SymbolCache/dsyms/uuids/A405/97AA/5529/3337/8C09/D8A014EB1578\r
+</tt></pre></code>\r
+\r
+<p>The last entries in these file mapped directories are symlinks to the actual dsym mach file in the dsym bundle:\r
+\r
+<code><pre><tt><b>% ls -lAF ~/Library/SymbolCache/dsyms/uuids/2351/6BE4/29BE/350C/91C9/F36E7999F0F1</b>\r
+~/Library/SymbolCache/dsyms/uuids/2351/6BE4/29BE/350C/91C9/F36E7999F0F1@ -> ../../../../../../dsyms/foo.dSYM/Contents/Resources/DWARF/foo\r
+</tt></pre></code>\r
+<p>Then you can also tell DebugSymbols to check this UUID file map cache using:\r
+\r
+<code><pre><tt><b>% defaults write com.apple.DebugSymbols DBGFileMappedPaths ~/Library/SymbolCache/dsyms/uuids</b>\r
+</tt></pre></code>\r
+\r
+\r
+ </div>\r
+ <div class="postfooter"></div>\r
+ </div>\r
+ <div class="post">\r
+ <h1 class="postheader">dSYM Locating Shell Script Tips</h1>\r
+ <div class="postcontent">\r
+\r
+<p>One possible implementation of a dSYM finding shell script is to have the script\r
+download and cache files locally in a known location. Then create a UUID map\r
+for each UUID value that was found in a local UUID File Map cache so the next query for the dSYM \r
+file will be able to use the cached version. So the shell script is used to \r
+initially download and cache the file, and subsequent accesses will use the\r
+cache and avoid calling the shell script.\r
+\r
+<p>Then the defaults for DebugSymbols.framework will entail enabling your shell script, \r
+enabling the file mapped path setting so that already downloaded dSYMS fill quickly\r
+be found without needing to run the shell script every time, and also leaving spotlight enabled\r
+so that other normal dSYM files are still found:\r
+\r
+<code><pre><tt><b>% defaults write com.apple.DebugSymbols DBGShellCommands /path/to/shellscript\r
+% defaults write com.apple.DebugSymbols DBGFileMappedPaths ~/Library/SymbolCache/dsyms/uuids\r
+% defaults write com.apple.DebugSymbols DBGSpotlightPaths -array</b>\r
+</tt></pre></code>\r
+\r
+Hopefully this helps explain how DebugSymbols.framework can help any company \r
+implement a smart symbol finding and caching with minimal overhead.\r
+</p>\r
+ </div>\r
+ <div class="postfooter"></div>\r
+ </div>\r
+ </div>\r
+ </div>\r
+</div>\r
+</body>\r
+</html>
\ No newline at end of file
projects / platform / upstream / llvm.git / commitdiff