315 lines · plain
1Symbols on macOS2================3 4On macOS, debug symbols are often in stand alone bundles called **dSYM** files.5These are bundles that contain DWARF debug information and other resources6related to builds and debug info.7 8The DebugSymbols.framework framework helps locate dSYM files when given a UUID.9It can locate the symbols using a variety of methods:10 11- Spotlight12- Explicit search paths13- Implicit search paths14- File mapped UUID paths15- Running one or more shell scripts16 17DebugSymbols.framework also has global defaults that can be modified to allow18all of the debug tools (lldb, gdb, sample, CoreSymbolication.framework) to19easily find important debug symbols. The domain for the DebugSymbols.framework20defaults is **com.apple.DebugSymbols**, and the defaults can be read, written21or modified using the **defaults** shell command:22 23::24 25 % defaults read com.apple.DebugSymbols26 % defaults write com.apple.DebugSymbols KEY ...27 % defaults delete com.apple.DebugSymbols KEY28 29The following is a list of the defaults key value setting pairs that can30be used to enhance symbol location:31 32**DBGFileMappedPaths**33 34This default can be specified as a single string, or an array of35strings. Each string represents a directory that contains file mapped36UUID values that point to dSYM files. See the "File Mapped UUID37Directories" section below for more details. Whenever38DebugSymbols.framework is asked to lookup a dSYM file, it will first39look in any file mapped UUID directories for a quick match.40 41::42 43 % defaults write com.apple.DebugSymbols DBGFileMappedPaths -string /path/to/uuidmap144 % defaults write com.apple.DebugSymbols DBGFileMappedPaths -array /path/to/uuidmap145 /path/to/uuidmap246 47**DBGShellCommands**48 49This default can be specified as a single string, or an array of50strings. Specifies a shell script that will get run in order to find the51dSYM. The shell script will be run given a single UUID value as the52shell command arguments and the shell command is expected to return a53property list. See the property list format defined below.54 55::56 57 % defaults write com.apple.DebugSymbols DBGShellCommands -string /path/to/script158 % defaults write com.apple.DebugSymbols DBGShellCommands -array /path/to/script159 /path/to/script260 61**DBGSpotlightPaths**62 63Specifies the directories to limit spotlight searches to as a string or64array of strings. When any other defaults are supplied to65**com.apple.DebugSymbols**, spotlight searches will be disabled unless66this default is set to an empty array:67 68::69 70 # Specify an empty array to keep Spotlight searches enabled in all locations71 % defaults write com.apple.DebugSymbols DBGSpotlightPaths -array72 73 # Specify an array of paths to limit spotlight searches to certain directories74 % defaults write com.apple.DebugSymbols DBGSpotlightPaths -array /path/dir1 /path/dir275 76Shell Script Property List Format77---------------------------------78 79Shell scripts that are specified with the **DBGShellCommands** defaults key80will be run in the order in which they are specified until a match is found.81The shell script will be invoked with a single UUID string value like82"23516BE4-29BE-350C-91C9-F36E7999F0F1". The shell script must respond with a83property list being written to STDOUT. The property list returned must contain84UUID string values as the root key values, with a dictionary for each UUID. The85dictionaries can contain one or more of the following keys:86 87+-----------------------------------+-----------------------------------+88| Key | Description |89+-----------------------------------+-----------------------------------+90| **DBGArchitecture** | A textual architecture or target |91| | triple like "x86_64", "i386", or |92| | "x86_64-apple-macosx". |93+-----------------------------------+-----------------------------------+94| **DBGBuildSourcePath** | A path prefix that was used when |95| | building the dSYM file. The debug |96| | information will contain paths |97| | with this prefix. |98+-----------------------------------+-----------------------------------+99| **DBGSourcePath** | A path prefix for where the |100| | sources exist after the build has |101| | completed. Often when building |102| | projects, build machines will |103| | host the sources in a temporary |104| | directory while building, then |105| | move the sources to another |106| | location for archiving. If the |107| | paths in the debug info don't |108| | match where the sources are |109| | currently hosted, then specifying |110| | this path along with the |111| | **DBGBuildSourcePath** will help |112| | the developer tools always show |113| | you sources when debugging or |114| | symbolicating. |115+-----------------------------------+-----------------------------------+116| **DBGDSYMPath** | A path to the dSYM mach-o file |117| | inside the dSYM bundle. |118+-----------------------------------+-----------------------------------+119| **DBGSymbolRichExecutable** | A path to the symbol rich |120| | executable. Binaries are often |121| | stripped after being built and |122| | packaged into a release. If your |123| | build systems saves an unstripped |124| | executable a path to this |125| | executable can be provided. |126+-----------------------------------+-----------------------------------+127| **DBGError** | If a binary can not be located |128| | for the supplied UUID, a user |129| | readable error can be returned. |130+-----------------------------------+-----------------------------------+131 132Below is a sample shell script output for a binary that contains two133architectures:134 135::136 137 <?xml version="1.0" encoding="UTF-8"?>138 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">139 <plist version="1.0">140 <dict>141 <key>23516BE4-29BE-350C-91C9-F36E7999F0F1</key>142 <dict>143 <key>DBGArchitecture</key>144 <string>i386</string>145 <key>DBGBuildSourcePath</key>146 <string>/path/to/build/sources</string>147 <key>DBGSourcePath</key>148 <string>/path/to/actual/sources</string>149 <key>DBGDSYMPath</key>150 <string>/path/to/foo.dSYM/Contents/Resources/DWARF/foo</string>151 <key>DBGSymbolRichExecutable</key>152 <string>/path/to/unstripped/executable</string>153 </dict>154 <key>A40597AA-5529-3337-8C09-D8A014EB1578</key>155 <dict>156 <key>DBGArchitecture</key>157 <string>x86_64</string>158 <key>DBGBuildSourcePath</key>159 <string>/path/to/build/sources</string>160 <key>DBGSourcePath</key>161 <string>/path/to/actual/sources</string>162 <key>DBGDSYMPath</key>163 <string>/path/to/foo.dSYM/Contents/Resources/DWARF/foo</string>164 <key>DBGSymbolRichExecutable</key>165 <string>/path/to/unstripped/executable</string>166 </dict>167 </dict>168 </plist>169 170There is no timeout imposed on a shell script when is it asked to locate a dSYM171file, so be careful to not make a shell script that has high latency or takes a172long time to download unless this is really what you want. This can slow down173debug sessions in LLDB and GDB, symbolication with CoreSymbolication or Report174Crash, with no visible feedback to the user. You can quickly return a plist175with a single **DBGError** key that indicates a timeout has been reached. You176might also want to exec new processes to do the downloads so that if you return177an error that indicates a timeout, your download can still proceed after your178shell script has exited so subsequent debug sessions can use the cached files.179It is also important to track when a current download is in progress in case180you get multiple requests for the same UUID so that you don't end up181downloading the same file simultaneously. Also you will want to verify the182download was successful and then and only then place the file into the cache183for tools that will cache files locally.184 185Embedding UUID property lists inside the dSYM bundles186-----------------------------------------------------187 188Since dSYM files are bundles, you can also place UUID info plists files inside189your dSYM bundles in the **Contents/Resources** directory. One of the main190reasons to create the UUID plists inside the dSYM bundles is that it will help191LLDB and other developer tools show you source. LLDB currently knows how to192check for these plist files so it can automatically remap the source location193information in the debug info.194 195If we take the two UUID values from the returns plist above, we can split them196out and save then in the dSYM bundle:197 198::199 200 % ls /path/to/foo.dSYM/Contents/Resources201 23516BE4-29BE-350C-91C9-F36E7999F0F1.plist202 A40597AA-5529-3337-8C09-D8A014EB1578.plist203 204 % cat /path/to/foo.dSYM/Contents/Resources/23516BE4-29BE-350C-91C9-F36E7999F0F1.plist205 <?xml version="1.0" encoding="UTF-8"?>206 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">207 <plist version="1.0">208 <dict>209 <key>DBGArchitecture</key>210 <string>i386</string>211 <key>DBGBuildSourcePath</key>212 <string>/path/to/build/sources</string>213 <key>DBGSourcePath</key>214 <string>/path/to/actual/sources</string>215 <key>DBGDSYMPath</key>216 <string>/path/to/foo.dSYM/Contents/Resources/DWARF/foo</string>217 <key>DBGSymbolRichExecutable</key>218 <string>/path/to/unstripped/executable</string>219 <key>DBGVersion</key>220 <string>3</string>221 <key>DBGSourcePathRemapping</key>222 <dict>223 <key>/path/to/build/time/src/location1</key>224 <string>/path/to/debug/time/src/location</string>225 <key>/path/to/build/time/src/location2</key>226 <string>/path/to/debug/time/src/location</string>227 </dict>228 <key>DBGSymbolRichExecutable</key>229 <string>/path/to/unstripped/executable</string>230 </dict>231 </plist>232 233Note that the output is very close to what is needed by shell script output, so234making the results of your shell script will be very easy to create by235combining two plists into a single one where you take the UUID and use it a236string key, and the value is the contents of the plist.237 238LLDB will read the following entries from the per-UUID plist file in the dSYM239bundle: **DBGSymbolRichExecutable**, **DBGBuildSourcePath** and240**DBGSourcePath**, and **DBGSourcePathRemapping** if **DBGVersion** is 3 or241higher. **DBGBuildSourcePath** and **DBGSourcePath** are for remapping a single242file path. For instance, the files may be in /BuildDir/SheetApp/SheetApp-37243when built, but they are in /SourceDir/SheetApp/SheetApp-37 at debug time,244those two paths could be listed in those keys. If there are multiple source245path remappings, the **DBGSourcePathRemapping** dictionary can be used, where246an arbitrary number of entries may be present. **DBGVersion** should be 3 or247**DBGSourcePathRemapping** will not be read. If both **DBGSourcePathRemapping**248AND **DBGBuildSourcePath**/**DBGSourcePath** are present in the plist, the249**DBGSourcePathRemapping** entries will be used for path remapping first. This250may allow for more specific remappings in the **DBGSourcePathRemapping**251dictionary and a less specific remapping in the252**DBGBuildSourcePath**/**DBGSourcePath** pair as a last resort.253 254File Mapped UUID Directories255----------------------------256 257File Mapped directories can be used for efficient dSYM file lookups for local258or remote dSYM files. The UUID is broken up by splitting the first 20 hex259digits into 4 character chunks, and a directory is created for each chunk, and260each subsequent directory is created inside the previous one. A symlink is then261created whose name is the last 12 hex digits in the deepest directory. The262symlinks value is a full path to the mach-o files inside the dSYM bundle which263contains the DWARF. Whenever DebugSymbols.framework is asked to lookup a dSYM264file, it will first look in any file mapped UUID directories for a quick match265if the defaults are appropriately set.266 267For example, if we take the sample UUID plist information from above, we can268create a File Mapped UUID directory cache in269**~/Library/SymbolCache/dsyms/uuids**. We can easily see how things are laid270out:271 272::273 274 % find ~/Library/SymbolCache/dsyms/uuids -type l275 ~/Library/SymbolCache/dsyms/uuids/2351/6BE4/29BE/350C/91C9/F36E7999F0F1276 ~/Library/SymbolCache/dsyms/uuids/A405/97AA/5529/3337/8C09/D8A014EB1578277 278The last entries in these file mapped directories are symlinks to the actual279dsym mach file in the dsym bundle:280 281::282 283 % ls -lAF ~/Library/SymbolCache/dsyms/uuids/2351/6BE4/29BE/350C/91C9/F36E7999F0F1284 ~/Library/SymbolCache/dsyms/uuids/2351/6BE4/29BE/350C/91C9/F36E7999F0F1@ -> ../../../../../../dsyms/foo.dSYM/Contents/Resources/DWARF/foo285 286Then you can also tell DebugSymbols to check this UUID file map cache using:287 288::289 290 % defaults write com.apple.DebugSymbols DBGFileMappedPaths ~/Library/SymbolCache/dsyms/uuids291 292dSYM Locating Shell Script Tips293-------------------------------294 295One possible implementation of a dSYM finding shell script is to have the296script download and cache files locally in a known location. Then create a UUID297map for each UUID value that was found in a local UUID File Map cache so the298next query for the dSYM file will be able to use the cached version. So the299shell script is used to initially download and cache the file, and subsequent300accesses will use the cache and avoid calling the shell script.301 302Then the defaults for DebugSymbols.framework will entail enabling your shell303script, enabling the file mapped path setting so that already downloaded dSYMS304fill quickly be found without needing to run the shell script every time, and305also leaving spotlight enabled so that other normal dSYM files are still found:306 307::308 309 % defaults write com.apple.DebugSymbols DBGShellCommands /path/to/shellscript310 % defaults write com.apple.DebugSymbols DBGFileMappedPaths ~/Library/SymbolCache/dsyms/uuids311 % defaults write com.apple.DebugSymbols DBGSpotlightPaths -array312 313Hopefully this helps explain how DebugSymbols.framework can help any company314implement a smart symbol finding and caching with minimal overhead.315