DBGSpotlightPaths is to limit spotlight searches to only those directories, but they must be valid locations that spotlight would normally index. If you want to see if spotlight indexes a directory that contains a dSYM file, then you can us “mdls”:
$ mdls a.out.dSYM
_kMDItemDisplayNameWithExtensions = “a.out.dSYM”
com_apple_xcode_dsym_paths = (
com_apple_xcode_dsym_uuids = (
if you see “com_apple_xcode_dsym_paths” and “com_apple_xcode_dsym_uuids”, then spotlight already indexes this directory and nothing should need to be done. This won’t work for locations that spotlight normally doesn’t index like “/tmp/", "~/Library/Caches/” and many more locations. This will just let you know if spotlight is indexing files already.
If you have a directory that contains dSYM files that you want to search, you have a few options:
1 - specify a directory that will be used for the current LLDB session only
2 - add dsym files manually as you need them
3 - specify a directory that will always be searched for all debug sessions
For solution #1 you can do this in LLDB with a setting:
(lldb) settings set target.debug-file-search-paths /symbols/dir/number1 [/symbols/dir/number2 …]
(lldb) target create …
Any dSYM files that aren’t found by spotlight, will fall back and look for matching dsym files in the directories you specify for the current LLDB session only.
For solution #2, you can add dSYM files manually:
(lldb) target create a.out
(lldb) target symbols add /path/to/libfoo.dSYM
LLDB will find the executable that matches /path/to/libfoo.dSYM and add it
For solution #3, you can modify the DebugSymbols.framework global defaults which will help LLDB and any other Xcode tools (sample, Instruments, Xcode, etc) to find your symbols:
$ defaults write com.apple.DebugSymbols DBGSearchPaths -string /single/path/to/search
$ defaults write com.apple.DebugSymbols DBGSearchPaths -array /path/to/search1 /path/to/search2
The main issue with this settings, is each time you have a program that loads DebugSymbols.framework (like LLDB), it will need to scan this entire directory and find all matching dSYM files. If you end up placing a lot of files in this directory, then it can become a performance cost. So this method is not preferred due to its possible costs that depends on how many dSYM files are in these directories.
A better solution that works well for solution #3 but has no cost associated with it is to store you dSYM files in a directory that isn’t indexed by spotlight, then have a script that ends up chopping up your UUID into 4 byte hex values as specified in File Mapped UUID Directories page. This allows direct access for looking up symbol files when needed and doesn’t cost you much besides a few stat() calls when you are looking for specific symbols.
More comments inlined below!
I am in need of configuring dSYM lookups on macOS for a directory under ~/Library/Caches which is not indexed by Spotlight and does not seem to be picked up when adding my directory to DBGSpotlightPaths.
Spotlight purposely doesn’t index in ~/Library/Caches at all and DBGSpotlightPaths setting for DebubSymbols.framework is used to only limit spotlight’s search to existing directories. The DBGSpotlightPaths setting is typically used when you might have multiple external drives and you want to limit spotlight searches to only a few root drives that contain symbols. It won’t cause a location that isn’t indexed by Spotlight to suddenly become indexed.
The Symbols on macOS page includes “Explicit search paths” as a method of dSYM lookups but mentions no way of configuring it. I happened to come across this very old GDB release notes page which mentions that DBGSearchPaths can be used to configure explicit search paths.
Yes this is correct as I detailed above, but it comes with unacceptable costs according to most people as each process has to scan these directories recursively, so you want to make sure to specify a directory with only a few files if you do end up using this method. If you specify an entire hard drive, each time you start a process that uses DebugSymbols.framework, it will recursively search the entire drive and all subdirectories for dSYM files which can obviously slow things down!
I can use DBGFileMappedPaths or DBGShellCommands but DBGSearchPaths seems to be working fine and looks like a much simpler approach if it is intended to be supported in the long term.
It has been support for over 10 years, so yes, this is supported and will continue to be, as long as you know the costs involved and are ok with that, you can use this method.