+

Debug Symbols on MacOSX

+

On MacOSX, debug symbols are often in stand alone bundles called dSYM files. + These are bundles that contain DWARF debug information and other resources related to + builds and debug info.

+

The DebugSymbols.framework framework helps locate dSYM files when given a UUID. It can + locate the symbols using a variety of methods:

+

Spotlight
Explicit search paths
Implicit search paths
File mapped UUID paths
Running one or more shell scripts

+

DebugSymbols.framework also has global defaults that can be modified to allow + all of the debug tools (lldb, gdb, sample, CoreSymbolication.framework) to easily + find important debug symbols. The domain for the DebugSymbols.framework defaults + is com.apple.DebugSymbols, and the defaults can be read, written or modified + using the defaults shell command: +

% defaults read com.apple.DebugSymbols
+% defaults write com.apple.DebugSymbols KEY ...
+% defaults delete com.apple.DebugSymbols KEY
+

+ +

The following is a list of the defaults key value + setting pairs that can be used to enhance symbol location:

+ + + + + + + + + + + + + + + + + + + + + + + +

Defaults Key	Description
+ DBGFileMappedPaths +	+ This default can be specified as a single string, or an array of strings. + Each string represents a directory that contains file mapped UUID values + that point to dSYM files. See the "File Mapped UUID Directories" section + below for more details. Whenever DebugSymbols.framework is asked to lookup + a dSYM file, it will first look in any file mapped UUID directories + for a quick match. +
+`% defaults write com.apple.DebugSymbols DBGFileMappedPaths -string /path/to/uuidmap1 +% defaults write com.apple.DebugSymbols DBGFileMappedPaths -array /path/to/uuidmap1 + /path/to/uuidmap2 +` +
+ DBGShellCommands +	+ This default can be specified as a single string, or an array of strings. + Specifies a shell script that will get run in order to find the dSYM. + The shell script will be run given a single UUID value as the shell + command arguments and the shell command is expected to return a property + list. See the property list format defined below. +
+`% defaults write com.apple.DebugSymbols DBGShellCommands -string /path/to/script1 +% defaults write com.apple.DebugSymbols DBGShellCommands -array /path/to/script1 + /path/to/script2 +` +
+ DBGSpotlightPaths +	+ Specifies the directories to limit spotlight searches to as a string or array of strings. When any + other defaults are supplied to com.apple.DebugSymbols, spotlight + searches will be disabled unless this default is set to an empty array: +
+`# Specify an empty array to keep Spotlight searches enabled in all locations +% defaults write com.apple.DebugSymbols DBGSpotlightPaths -array + +# Specify an array of paths to limit spotlight searches to certain directories +% defaults write com.apple.DebugSymbols DBGSpotlightPaths -array /path/dir1 /path/dir2 +` +

+

Shell Script Property List Format

+

Shell scripts that are specified with the DBGShellCommands defaults key +will be run in the order in which they are specified until a match is found. +The shell script will be invoked with a single UUID string value like +"23516BE4-29BE-350C-91C9-F36E7999F0F1". The shell script must respond with a +property list being written to STDOUT. The property list must contain UUID +string values as the root key values, with a dictionary for each UUID. The dictionaries +can contain one or more of the following keys: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Key Description
+ DBGArchitecture + A textual architecture or target triple like "x86_64", "i386", or "x86_64-apple-macosx". +
+ DBGBuildSourcePath + A path prefix that was used when building the dSYM file. The debug information will + contain paths with this prefix. +
+ DBGSourcePath + A path prefix for where the sources exist after the build has completed. Often when + building projects, build machines will host the sources in a temporary directory while building, then + move the sources to another location for archiving. If the paths in the debug info don't match where + the sources are currently hosted, then specifying this path along with the DBGBuildSourcePath + will help the developer tools always show you sources when debugging or symbolicating. +
+ DBGDSYMPath + A path to the dSYM mach-o file inside the dSYM bundle. +
+ DBGSymbolRichExecutable + A path to the symbol rich executable. Binaries are often stripped after + being built and packaged into a release. If your build systems saves an unstripped executable + a path to this executable can be provided. +
+ DBGError + If a binary can not be located for the supplied UUID, a user readable error + can be returned. +
+ +

Key	Description
+ DBGArchitecture +	A textual architecture or target triple like "x86_64", "i386", or "x86_64-apple-macosx". +
+ DBGBuildSourcePath +	A path prefix that was used when building the dSYM file. The debug information will + contain paths with this prefix. +
+ DBGSourcePath +	A path prefix for where the sources exist after the build has completed. Often when + building projects, build machines will host the sources in a temporary directory while building, then + move the sources to another location for archiving. If the paths in the debug info don't match where + the sources are currently hosted, then specifying this path along with the DBGBuildSourcePath + will help the developer tools always show you sources when debugging or symbolicating. +
+ DBGDSYMPath +	A path to the dSYM mach-o file inside the dSYM bundle. +
+ DBGSymbolRichExecutable +	A path to the symbol rich executable. Binaries are often stripped after + being built and packaged into a release. If your build systems saves an unstripped executable + a path to this executable can be provided. +
+ DBGError +	If a binary can not be located for the supplied UUID, a user readable error + can be returned. +

Below is a sample shell script output for a binary that contains two architectures: +


+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>23516BE4-29BE-350C-91C9-F36E7999F0F1</key>
+	<dict>
+		<key>DBGArchitecture</key>
+		<string>i386</string>
+		<key>DBGBuildSourcePath</key>
+		<string>/path/to/build/sources</string>
+		<key>DBGSourcePath</key>
+		<string>/path/to/actual/sources</string>
+		<key>DBGDSYMPath</key>
+		<string>/path/to/foo.dSYM/Contents/Resources/DWARF/foo</string>
+		<key>DBGSymbolRichExecutable</key>
+		<string>/path/to/unstripped/exectuable</string>
+	</dict>
+	<key>A40597AA-5529-3337-8C09-D8A014EB1578</key>
+	<dict>
+		<key>DBGArchitecture</key>
+		<string>x86_64</string>
+		<key>DBGBuildSourcePath</key>
+		<string>/path/to/build/sources</string>
+		<key>DBGSourcePath</key>
+		<string>/path/to/actual/sources</string>
+		<key>DBGDSYMPath</key>
+		<string>/path/to/foo.dSYM/Contents/Resources/DWARF/foo</string>
+		<key>DBGSymbolRichExecutable</key>
+		<string>/path/to/unstripped/exectuable</string>
+	</dict>
+</dict>
+</plist>
+

+ +

+

Embedding UUID property lists inside the dSYM bundles

+

Since dSYM files are bundles, you can also place UUID info plists files inside +your dSYM bundles in the Contents/Resources directory. One of the main +reasons to create the UUID plists inside the dSYM bundles +is that it will help LLDB and other developer tools show you source. LLDB currently +knows how to check for these plist files so it can automatically remap the source +location information in the debug info. + +

If we take the two UUID values from the returns plist above, we can split +them out and save then in the dSYM bundle: + +

% ls /path/to/foo.dSYM/Contents/Resources
+23516BE4-29BE-350C-91C9-F36E7999F0F1.plist
+A40597AA-5529-3337-8C09-D8A014EB1578.plist
+
+% cat /path/to/foo.dSYM/Contents/Resources/23516BE4-29BE-350C-91C9-F36E7999F0F1.plist
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+   <key>DBGArchitecture</key>
+   <string>i386</string>
+   <key>DBGBuildSourcePath</key>
+   <string>/path/to/build/sources</string>
+   <key>DBGSourcePath</key>
+   <string>/path/to/actual/sources</string>
+   <key>DBGDSYMPath</key>
+   <string>/path/to/foo.dSYM/Contents/Resources/DWARF/foo</string>
+   <key>DBGSymbolRichExecutable</key>
+   <string>/path/to/unstripped/exectuable</string>
+</dict>
+</plist>
+

+ +

Note that the output is very close to what is needed by shell script output, +so making the results of your shell script will be very easy to create by +combining two plists into a single one where you take the UUID and use it a + string key, and the value is the contents of the plist. + + +

+

File Mapped UUID Directories

+

File Mapped directories can be used for efficient dSYM file lookups for +local or remote dSYM files. The UUID is broken up by splitting the first +20 hex digits into 4 character chunks, and a directory is created for each +chunk, and each subsequent directory is created inside the previous one. +A symlink is then created whose name is the last 12 hex digits in the deepest +directory. The symlinks value is a full path to the mach-o files inside the +dSYM bundle which contains the DWARF. Whenever DebugSymbols.framework is asked +to lookup a dSYM file, it will first look in any file mapped UUID directories +for a quick match if the defaults are appropriately set. + +

For example, if we take the sample UUID plist inforamtion from above, we +can create a File Mapped UUID directory cache in ~/Library/SymbolCache/dsyms/uuids. +We can easily see how things are laid out: + +

% find ~/Library/SymbolCache/dsyms/uuids -type l
+~/Library/SymbolCache/dsyms/uuids/2351/6BE4/29BE/350C/91C9/F36E7999F0F1
+~/Library/SymbolCache/dsyms/uuids/A405/97AA/5529/3337/8C09/D8A014EB1578
+

+ +

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

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

+

Then you can also tell DebugSymbols to check this UUID file map cache using: + +

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

+ + +

+

dSYM Locating Shell Script Tips

+

+ +

One possible implementation of a dSYM finding shell script is to have the script +download and cache files locally in a known location. Then create a UUID map +for each UUID value that was found in a local UUID File Map cache so the next query for the dSYM +file will be able to use the cached version. So the shell script is used to +initially download and cache the file, and subsequent accesses will use the +cache and avoid calling the shell script. + +

Then the defaults for DebugSymbols.framework will entail enabling your shell script, +enabling the file mapped path setting so that already downloaded dSYMS fill quickly +be found without needing to run the shell script every time, and also leaving spotlight enabled +so that other normal dSYM files are still found: + +

% defaults write com.apple.DebugSymbols DBGShellCommands /path/to/shellscript
+% defaults write com.apple.DebugSymbols DBGFileMappedPaths ~/Library/SymbolCache/dsyms/uuids
+% defaults write com.apple.DebugSymbols DBGSpotlightPaths -array
+

+ +Hopefully this helps explain how DebugSymbols.framework can help any company +implement a smart symbol finding and caching with minimal overhead. +

+