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 write com.apple.DebugSymbols DBGFileMappedPaths -string /path/to/uuidmap1
% defaults write com.apple.DebugSymbols DBGFileMappedPaths -array /path/to/uuidmap1 
    /path/to/uuidmap2

% defaults write com.apple.DebugSymbols DBGShellCommands -string /path/to/script1
% defaults write com.apple.DebugSymbols DBGShellCommands -array /path/to/script1
    /path/to/script2

# 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 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 returned 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:

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>

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 script that has high latency or takes a long time to download unless this is really what you want. This can slow down debug sessions in LLDB and GDB, symbolication with CoreSymbolication or Report Crash, with no visible feedback to the user. You can quickly return a plist with a single DBGError key that indicates a timeout has been reached. You might also want to exec new processes to do the downloads so that if you return an error that indicates a timeout, your download can still proceed after your shell script has exited so subsequent debug sessions can use the cached files. It is also important to track when a current download is in progress in case you get multiple requests for the same UUID so that you don't end up downloading the same file simultaneously. Also you will want to verify the download was successful and then and only then place the file into the cache for tools that will cache files locally.

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 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

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