<?xml version="1.0" encoding="UTF-8"?>
<Chapter AppleRefChapterID="CH1">
<Name>GDB Release Notes for Mac OS X v10.5 WWDC Seed</Name>
<Intro>
<Para>For complete information about GDB, please refer to the <uBook LinkToAppleRefId="//apple_ref/doc/uid/TP40000996">Debugging with GDB</uBook>.</Para>
</Intro>
<ReleaseNotes>
<Section><Name>Changes Since Xcode 2.4.1 (gdb-563)</Name>
<List-Bullet>
<Item>
<Para>DWARF is the primary debug format</Para>
<Para>Beginning with Leopard, DWARF (and DWARF + dSYM) is the primary, supported debug file format. The older format, stabs, will continue to work but no further development will be done to improve or enhance stabs. If you cannot transition your project to DWARF because of a problem with the tools, please file a bug report.</Para>
</Item>
<Item>
<Para>Inlined function debugging support</Para>
<Para>When debugging with DWARF, gdb will now treat inlined functions much like normal functions. You can set symbolic breakpoints on the inlined functions, you can next over inlined functions, you can step in to an inlined function and get a backtrace. If you are stopped in an inline function you can also <codeVoice xml:space="preserve">finish</codeVoice> out of that function.</Para>
</Item>
<Item>
<Para>More accurate reporting of variables optimized away</Para>
<Para>When a variable has been optimized away by the compiler, instead of the old behavior (sometimes being told "variable optimized out" and sometimes being told gdb never heard of the variable), the debugger will always report "variable optimized away by the compiler" when the DWARF debugging format is used.</Para>
<Para>When you request to see a variable which gdb can't currently get the value for (but which was not entirely optimized away by the compiler), instead of being told "variable optimized out", gdb will now report "value temporarily unavailable, due to optimizations" when the DWARF debugging format is used.</Para>
<Para>If you get the "temporarily unavailable" message, you can use the command "<codeVoice xml:space="preserve">info address <var></codeVoice>" to see a list of address ranges where the value will be available. Then by monitoring <codeVoice xml:space="preserve">$pc</codeVoice> you can proceed to a location where you can examine the variable.</Para>
</Item>
<Item>
<Para>Hardware watchpoint support on x86</Para>
<Para>gdb can now use the hardware watchpoint support on 32-bit x86 programs. This will yield faster and more accurate watchpoint behavior for this architecture.</Para>
</Item>
<Item>
<Para><codeVoice xml:space="preserve">watch -location</codeVoice></Para>
<Para>The <codeVoice xml:space="preserve">watch</codeVoice> command has a new flag: <codeVoice xml:space="preserve">-location</codeVoice>. If you specify this flag (it has to be first in the command line, before the expression you are going to watch) then gdb will resolve the expression you've passed it to a memory location, and then just watch that. This is useful, for instance, if you want to watch a local variable which contains a pointer to memory, since watching the local variable will cease to work when the variable goes out of scope. It is also useful when you just want to watch what <codeVoice xml:space="preserve">foo->bar->baz</codeVoice> points to, and don't want to watch the "<codeVoice xml:space="preserve">foo</codeVoice>" or "<codeVoice xml:space="preserve">bar</codeVoice>" components in-between.</Para>
</Item>
<Item>
<Para>New <codeVoice xml:space="preserve">-arch</codeVoice> command line argument</Para>
<Para>By default, when gdb is running on a 64-bit capable CPU and has a universal file, it will examine/run the 64-bit side of that file. The gdb <codeVoice xml:space="preserve">-arch</codeVoice> option can now be used to specify which fork of a binary gdb will run. For instance, if you are on a G5 and have a Universal ppc/ppc64 binary, then:</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">$ gdb -arch ppc MyUniversalFile</CodeLine>
</CodeLines-Full>
</CodeListing>
<Para>will run the 32 bit (ppc) side of the Universal binary. The valid options are <codeVoice xml:space="preserve">ppc</codeVoice>, <codeVoice xml:space="preserve">ppc64</codeVoice>, <codeVoice xml:space="preserve">x86</codeVoice> and <codeVoice xml:space="preserve">x86_64</codeVoice>.</Para>
</Item>
<Item>
<Para>New <codeVoice xml:space="preserve">--waitfor</codeVoice> argument</Para>
<Para>To catch processes that must launch outside gdb early in their startup, gdb has added a <codeVoice xml:space="preserve">--waitfor</codeVoice> command line argument and argument to the <codeVoice xml:space="preserve">attach</codeVoice> gdb command. <codeVoice xml:space="preserve">--waitfor</codeVoice> is followed by the name of the process to wait for. When <codeVoice xml:space="preserve">--waitfor</codeVoice> is used, gdb will poll repeatedly looking for the process to start running. As soon as gdb notices that the process is running, it will attach to the process, pause it, and give you the gdb prompt.</Para>
</Item>
<Item>
<Para>Debugging KEXTs with DWARF</Para>
<Para>Debugging system kernel extensions with the DWARF debug format requires a few special steps. First, you must build your project with the "DWARF with dSYM" build style. Second, you must keep an unstripped copy of your <codeVoice xml:space="preserve">.kext</codeVoice> bundle in addition to the <codeVoice xml:space="preserve">dSYM</codeVoice> bundle. When you run <codeVoice xml:space="preserve">kextload(8)</codeVoice> to load your kext you will get a <codeVoice xml:space="preserve">.sym</codeVoice> file -- you will need this piece as well.</Para>
<Para>Put all three pieces -- the unstripped <codeVoice xml:space="preserve">.kext</codeVoice> bundle, the <codeVoice xml:space="preserve">dSYM</codeVoice> bundle and the <codeVoice xml:space="preserve">.sym</codeVoice> file in the same directory. Launch gdb as you normally would and load the kext by using the new <codeVoice xml:space="preserve">add-kext</codeVoice> gdb command instead of <codeVoice xml:space="preserve">add-symbol-file</codeVoice> as was done in the past.</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">(gdb) add-kext myextension.kext</CodeLine>
</CodeLines-Full>
</CodeListing>
<Para>There is one additional setting that may help adjust to this new workflow: <codeVoice xml:space="preserve">kext-symbol-file-path</codeVoice>. This setting specifies a directory to search for the <codeVoice xml:space="preserve">.sym</codeVoice> file. For instance you may have your <codeVoice xml:space="preserve">dSYM</codeVoice> and <codeVoice xml:space="preserve">.kext</codeVoice> bundles in a working directory and your <codeVoice xml:space="preserve">.sym</codeVoice> files are in <codeVoice xml:space="preserve">/tmp</codeVoice>. You can avoid unnecessary copying of either of these by setting</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">(gdb) set kext-symbol-file-path /tmp</CodeLine>
</CodeLines-Full>
</CodeListing>
</Item>
<Item>
<Para>Fix and Continue does not work with Objective-C</Para>
<Para>Fix and Continue does not work with Objective-C programs in this seed. This is a temporarily limitation; it will be fixed in a future release.</Para>
</Item>
<Item>
<Para>Support for core files</Para>
<Para>gdb can now inspect core files from a process that crashed. By default, core files are not generated on Mac OS X but you can enable their generation from the command line. In <codeVoice xml:space="preserve">csh</codeVoice>/<codeVoice xml:space="preserve">tcsh</codeVoice>, you would enable core file generation by <codeVoice xml:space="preserve">limit coredumpsize unlimited</codeVoice>. In <codeVoice xml:space="preserve">sh</codeVoice>/<codeVoice xml:space="preserve">bash</codeVoice>, it is <codeVoice xml:space="preserve">ulimit -c unlimited</codeVoice>. The core files will be saved in <pathName>/cores</pathName> and will be large - you can fill your system drive with core files if you're not careful. Here is an example of core file debugging:</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">$ ulimit -c unlimited</CodeLine>
<CodeLine xml:space="preserve">$ ./crasher</CodeLine>
<CodeLine xml:space="preserve">My pid is 7766</CodeLine>
<CodeLine xml:space="preserve">Bus error (core dumped)</CodeLine>
<CodeLine xml:space="preserve">$ gdb crasher /cores/core.7766</CodeLine>
<CodeLine xml:space="preserve">Core was generated by `./crasher'.</CodeLine>
<CodeLine xml:space="preserve">#0 0x00000000 in _mh_dylib_header ()</CodeLine>
<CodeLine xml:space="preserve">(gdb) bt</CodeLine>
<CodeLine xml:space="preserve">Reading in symbols for crasher.c...done.</CodeLine>
<CodeLine xml:space="preserve">#0 0x00000000 in _mh_dylib_header ()</CodeLine>
<CodeLine xml:space="preserve">#1 0x00001fa2 in main () at crasher.c:8</CodeLine>
</CodeLines-Full>
</CodeListing>
</Item>
<Item>
<Para>Locating dSYM files</Para>
<Para>In Xcode 2.4, the dSYM file for an executable had to be placed in the same directory as the executable for gdb to find it. There is a new framework for locating dSYM files, <pathName>DebugSymbols.framework</pathName>, that will be used by various developer tools to locate dSYM files automatically in other locations. By default, dSYM files will be searched by a Spotlight search and by implicit search paths. Defaults can be written to the <codeVoice xml:space="preserve">com.apple.DebugSymbols</codeVoice> to modify this behavior via the <pathName>defaults(1)</pathName> command line tool.. The full list of recognized settings is:</Para>
<List-Bullet>
<Item>
<Para><codeVoice xml:space="preserve">DBGShellCommands</codeVoice></Para>
<Para>Shell commands can be used to return the paths to the matching dSYM files for provided UUIDs. Shell commands can provide a level of abstraction from the method of storing the UUID to dSYM mapping information, and allow build systems to store the data in a wide variety of ways. No shell command will be run by default.</Para>
<Para>UUID values are specified to stdin of the shell command with one UUID value specified on a line with no leading or trailing white spaces. The command reads until the EOF and returns any matches to stdout.</Para>
<Para>The shell command will return UTF8 encoded XML as a property list. Each UUID will result in a key whose value is the UUID string, with a dictionary of key/value pairs containing the results. All dictionary key value pairs are optional. The list of currently supported keys are:</Para>
<List-Simple>
<Item>
<Para><codeVoice xml:space="preserve">DBGError</codeVoice></Para>
<Para>An error describing why a the search failed.</Para>
</Item>
<Item>
<Para><codeVoice xml:space="preserve">DBGDSYMPath</codeVoice></Para>
<Para>The path to the dSYM file.</Para>
</Item>
<Item>
<Para><codeVoice xml:space="preserve">DBGSymbolRichExecutable</codeVoice></Para>
<Para>The path to the unstripped executable (if any).</Para>
</Item>
<Item>
<Para><codeVoice xml:space="preserve">DBGSourcePath</codeVoice></Para>
<Para>The path to the sources for the executable.</Para>
</Item>
</List-Simple>
<Para>The number of supported keys may be expanded in the future to support more features. </Para>
<Para>The shell commands to be used can be specified by setting the "DBGShellCommands" key to be a string for a single shell command, or an array of strings for multiple shell commands:</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">$ defaults write com.apple.DebugSymbols DBGShellCommands -string /usr/bin/find-dsym</CodeLine>
<CodeLine xml:space="preserve">$ defaults write com.apple.DebugSymbols DBGShellCommands -array /usr/bin/find-dsym /Network/bin/find-dsym</CodeLine>
</CodeLines-Full>
</CodeListing>
<Para>To disable shell command searching we can write a boolean value set to false, or delete the key altogether:</Para>
<codelisting>
<codelines-full><codeline xml:space="preserve">defaults delete com.apple.DebugSymbols DBGShellCommands</codeline></codelines-full>
</codelisting>
</Item>
<Item>
<Para><codeVoice xml:space="preserve">DBGSpotlightPaths</codeVoice></Para>
<Para>The spotlight paths used to limit a spotlight search to certain directories can can be specified by setting the "DBGSpotlightPaths" key to be a string for a single path, or an array of strings for multiple paths:</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">$ defaults write com.apple.DebugSymbols DBGSpotlightPaths -string /single/path/to/search</CodeLine>
<CodeLine xml:space="preserve">$ defaults write com.apple.DebugSymbols DBGSpotlightPaths -array /path/to/search1 /path/to/search2</CodeLine>
</CodeLines-Full>
</CodeListing>
<Para>In order to allow spotlight searches along with other preferences, yet not limit the spotlight search to any directories, we create an empty array:</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">$ defaults write com.apple.DebugSymbols DBGSpotlightPaths -array</CodeLine>
</CodeLines-Full>
</CodeListing>
<Para>To disable spotlight searching we can write an write a boolean value set to false:</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">$ defaults write com.apple.DebugSymbols DBGSpotlightPaths -bool NO</CodeLine>
</CodeLines-Full>
</CodeListing>
</Item>
<Item>
<Para><codeVoice xml:space="preserve">DBGSearchPaths</codeVoice></Para>
<Para>The explicit search paths can can be specified by setting the "DBGSearchPaths" key to be a string for a single path, or an array of strings for multiple paths:</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">$ defaults write com.apple.DebugSymbols DBGSearchPaths -string /single/path/to/search</CodeLine>
<CodeLine xml:space="preserve">$ defaults write com.apple.DebugSymbols DBGSearchPaths -array /path/to/search1 /path/to/search2</CodeLine>
</CodeLines-Full>
</CodeListing>
<Para>To disable explicit directory searching, delete the default key:</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">$ defaults delete com.apple.DebugSymbols DBGSearchPaths</CodeLine>
</CodeLines-Full>
</CodeListing>
</Item>
<Item>
<Para><codeVoice xml:space="preserve">DBGFileMappedPaths</codeVoice></Para>
<Para>File mapped paths allow users to specify a directory that contains shallow or deep UUID symlinks that point to the dSYM files.</Para>
<Para>A UUID whose value is C6F7EDC5-74C0-4CA8-A21D-ACED1357D811 whose dSYM file resides at /symbols/foo.dSYM has a shallow file mapped symlink that would appear as:</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">$ ls -lAF C6F7EDC5-74C0-4CA8-A21D-ACED1357D811</CodeLine>
<CodeLine xml:space="preserve">C6F7EDC5-74C0-4CA8-A21D-ACED1357D811@ -> /symbols/foo.dSYM</CodeLine>
</CodeLines-Full>
</CodeListing>
<Para>The same UUID and file would have a deep symlink that would appear as:</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">$ ls -lAF C6F7/EDC5/74C0/4CA8/A21D/ACED1357D811</CodeLine>
<CodeLine xml:space="preserve">C6F7/EDC5/74C0/4CA8/A21D/ACED1357D811@ -> /symbols/foo.dSYM</CodeLine>
</CodeLines-Full>
</CodeListing>
<Para>The file system mapping paths can be specified by setting the "DBGFileMappedPaths" key to be a string for a single path, or an array of strings for multiple paths:</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">$ defaults write com.apple.DebugSymbols DBGFileMappedPaths -string /single/path/to/search</CodeLine>
<CodeLine xml:space="preserve">$ defaults write com.apple.DebugSymbols DBGFileMappedPaths -array /path/to/search1 /path/to/search2</CodeLine>
</CodeLines-Full>
</CodeListing>
<Para>To disable file mapped path searches, delete the default key:</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">$ defaults delete com.apple.DebugSymbols DBGFileMappedPaths</CodeLine>
</CodeLines-Full>
</CodeListing>
</Item>
</List-Bullet>
</Item>
<Item>
<Para>Disabling dSYM lookups altogether</Para>
<Para>You can instruct gdb to do none of the advanced dSYM lookup methods by setting <codeVoice xml:space="preserve">locate-dsym</codeVoice>.</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">(gdb) set locate-dsym 0</CodeLine>
</CodeLines-Full>
</CodeListing>
<Para>gdb will still look for dSYM files next to the executable being debugged.</Para>
<Para>This setting is particularly useful if you are writing code that may cause low level systems like Spotlight or DirectoryServices to be slow, hang or crash. The advanced dSYM lookup methods depend on these services and it is possible to hang your system requiring a reboot in some rare cases.</Para>
</Item>
<Item>
<Para>Live kernel debugging</Para>
<Para>The live kernel debugger permits examination of the running kernel's memory image. To use this facility,</Para>
<List-Number>
<Item>
<Para>The system must be started with the "<codeVoice xml:space="preserve">kmem=1</codeVoice>" kernel boot-arg. To do this, issue the command: <codeVoice xml:space="preserve">sudo nvram boot-args="kmem=1"</codeVoice> (along with any other kernel boot-args set previously) followed by a restart.</Para>
</Item>
<Item>
<Para>GDB must be started as the superuser:</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">$ sudo gdb <location of kernel image with debugging symbols></CodeLine>
</CodeLines-Full>
</CodeListing>
<Para>("<pathName>/Volumes/KernelDebugKit/mach_kernel</pathName>", if you have the kernel debug kit diskimage for your Mac OS X release mounted)</Para>
</Item>
<Item>
<Para>Issue the following commands at the GDB prompt:</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">(gdb) target darwin-kernel</CodeLine>
<CodeLine xml:space="preserve">(gdb) attach</CodeLine>
</CodeLines-Full>
</CodeListing>
</Item>
<Item>
<Para>GDB is now ready to examine the currently executing kernel's memory image. You can issue:</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">(gdb) source <location of kernel debugging macros></CodeLine>
</CodeLines-Full>
</CodeListing>
<Para>("<pathName>/Volumes/KernelDebugKit/kgmacros</pathName>", for instance) to load the xnu kernel debugging macros. You may now execute kernel debugging macros ("<codeVoice xml:space="preserve">help kgm</codeVoice>" for a list) and examine kernel variables and data structures.</Para>
</Item>
</List-Number>
<Para>Things to be aware of:</Para>
<List-Bullet>
<Item>
<Para>Your view of the kernel isn't necessarily coherent--this is a live kernel, and you may see some inconsistencies while examining memory locations that are being actively altered. Thread stacks and such can potentially mutate while you're in the process of examining them; in most debugging scenarios however, you're examining threads that are blocked in some fashion--stack frames are relatively stable in such cases.</Para>
</Item>
<Item>
<Para>The live kernel debugger does not support altering kernel memory, i.e. it is read-only. Most kernel debugging macros don't manipulate register state or alter memory, so they will function correctly, with the caveats regarding actively changing areas noted above.</Para>
</Item>
</List-Bullet>
</Item>
<Item>
<Para><codeVoice xml:space="preserve">info malloc-history</codeVoice></Para>
<Para>This is a new command in gdb. It is to be used with the "<codeVoice xml:space="preserve">MALLOC_STACK_LOGGING_NO_COMPACT</codeVoice>" malloc stack logging environment variable. If you run with this on, then in gdb, you can say:</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">(gdb) info malloc-history <SYMBOL/ADDRESS></CodeLine>
</CodeLines-Full>
</CodeListing>
<Para>and we will return the stacks of all the instances where data was malloc'ed at that address.</Para>
</Item>
<Item>
<Para><codeVoice xml:space="preserve">info gc-roots</codeVoice> / <codeVoice xml:space="preserve">info gc-references</codeVoice></Para>
<Para>This is a new command. It is only useful when you are debugging an Application that is running with the Objective-C Garbage Collection enabled. In that case,</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">(gdb) info gc-roots <ADDRESS/SYMBOL></CodeLine>
</CodeLines-Full>
</CodeListing>
<Para>will tell you all the unique shortest roots to a given symbol, and</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">(gdb) info gc-references <ADDRESS/SYMBOL></CodeLine>
</CodeLines-Full>
</CodeListing>
<Para>will tell you all the objects in the collector that reference the given symbol or address.</Para>
</Item>
<Item>
<Para>Limit Function Names Displayed During Disassembly</Para>
<Para>gdb now has a setting, <kConstantName>disassembly-name-length</kConstantName>, which limits the length of function names that are printed during disassembly. C++ in particular can have very long mangled function names which can make it difficult to read the disassembly. Use it like this:</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">
(gdb) set disassembly-name-length 5
(gdb) disass $pc
Dump of assembler code for function _ZN11TDescriptor12InitBaseFontEv:
0x94adf226 <_ZN11+0>: push %ebp
0x94adf227 <_ZN11+1>: mov %esp,%ebp
0x94adf229 <_ZN11+3>: push %edi
0x94adf22a <_ZN11+4>: push %esi
0x94adf22b <_ZN11+5>: sub $0x10,%esp
</CodeLine>
</CodeLines-Full>
</CodeListing>
</Item>
<Item>
<Para>Fix and Continue build settings</Para>
<Para>There are two new build settings in Xcode that should not be enabled if you are going to use the Fix and Continue feature:</Para>
<List-Simple>
<Item>
<Para>"Generate Position-Dependent Code" must be disabled (unchecked).</Para>
</Item>
<Item>
<Para>"Symbols Hidden by Default" must be disabled (unchecked).</Para>
</Item>
</List-Simple>
<Para>These settings can be set as you please for your Release configuration but if you'd like to use Fix and Continue while debugging you will need to disable them for your Debug configuration.</Para>
</Item>
<Item>
<Para>Debugging with libgmalloc and zsh</Para>
<Para>If you are using zsh as your shell and want to run your program with libgmalloc under gdb you must do</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">(gdb) set start-with-shell 0</CodeLine>
</CodeLines-Full>
</CodeListing>
</Item>
<Item>
<Para>CFM runtime support disabled by default</Para>
<Para>If you are debugging CFM applications on PowerPC systems you will need to enable this support before executing your program by setting</Para>
<CodeListing>
<CodeLines-Full>
<CodeLine xml:space="preserve">(gdb) set inferior-auto-start-cfm 1</CodeLine>
</CodeLines-Full>
</CodeListing>
<Para>Either on at the gdb command prompt or by adding this to your <pathName>$HOME/.gdbinit</pathName> file.</Para>
</Item>
</List-Bullet>
</Section>
<Section><Name>Changes since Xcode 2.2 Developer tools update (gdb-437)</Name><List-Bullet><Item><Para>Support for DWARF debug file format</Para><Para>GDB now supports the use of the DWARF debug file format. It can work with DWARF in one of two ways: The debug information is stored primarily in the .o object files with a little bit in the executable, and with all of the debug information collected into a dSYM file and no debug information in the executable.</Para><Para>For normal change-compile-debug, change-compile-debug workflow, leaving the debug information in the .o files is the intended usage. A dSYM file should be created when you are distributing your binary to another person who will need to debug it, or archiving the debug information of a release binary so you can debug crash reports/bugs that are reported to you later.</Para><Para>In the case of debug information in .o files, the .o files must remain in their original location for gdb to find them. They may be copied to another system, but the pathname must remain the same -- or soft symbolic links (cf ln(1)) must be put in place.</Para><Para>In the case of a dSYM file, <codeVoice xml:space="preserve">dsymutil(1)</codeVoice>, is run on the executable file before stripping to create the dSYM. After that has been done, the binary may be stripped and released - you will be able to use the dSYM file along with the stripped binary to debug it later. The dSYM file must be next to the binary you are debugging for GDB to find it. For instance if your application is<pathName> /path/to/my/Fun.app</pathName>, the dSYM file should be named <pathName>/path/to/my/Fun.app.dSYM</pathName> or GDB will not read in the dSYM file. There is currently no way to specify the location of a dSYM file to gdb -- again, soft links are one workaround if copying the file into place is not feasible.</Para></Item></List-Bullet></Section>
<Section><Name>Changes since August 2004 Devtools update (gdb-330.1)</Name><List-Number><Item><Para>Lazy symbol and on-demand symbol loading under Xcode</Para><Para>When gdb is used under Xcode, and the <codeVoice xml:space="preserve">Load symbols lazily</codeVoice> Debugging preference is checked, gdb will postpone symbol reading until the symbols are needed. This optimization will yield faster start-up times, particularly on larger applications.</Para><Para>For developers with command line proclivities, some caution is needed when using Xcode and lazy symbol loading. When the application, dylib, bundle, or framework hasn't had a breakpoint set in it, or you haven't stopped execution while the PC was contained in that app/dylib/bundle/framework, gdb won't know anything about the symbols in that file so breakpoints in that file can't be set as you normally would. For instance, you run your application under Xcode, then pause it and open the Console window. In the Console window you type "<codeVoice xml:space="preserve">break MyFile.c:85</codeVoice>". If the symbols for the executable file containing <codeVoice xml:space="preserve">MyFile.c</codeVoice> haven't been loaded yet, gdb won't know where to set this breakpoint. In the case of a ZeroLink application where every source file is in its own bundle, this can happen often.</Para><Para>Breakpoints set from the Xcode UI will be handled correctly because Xcode knows which executable file contains that source file and communicates this information to gdb. You can force the symbols to be read for a file by either disabling lazy symbol loading (Xcode's Debugging Preferences), or once the app is running, Pause execution, open the <bold>Debug > Tools > Shared Libraries</bold>, and raise the load level of the executable file you're working in to "<bold>ALL</bold>".</Para><Para>From the debugger Console window in Xcode, if you are setting a breakpoint with the break command and want to inform gdb which executable file contains that breakpoint (so the symbols for that file are read in), you can use the <codeVoice xml:space="preserve">-shlib</codeVoice> argument to the break command. e.g. for the Sketch sample application, built in ZeroLink mode, you would do this to tell gdb that it should read in the symbols for the SKTGraphic ZeroLink bundle:</Para><Para><codeVoice xml:space="preserve">break -shlib SKTGraphic.ob SKTGraphic.m:19</codeVoice></Para><Para>Lazy symbol loading is only in effect when using gdb under Xcode. None of these caveats are required when using gdb from the command line.</Para></Item><Item><Para>Cached symfiles are no longer enabled</Para><Para>The cached symfile feature has been superseded by the lazy and on-demaned symbol loading.</Para></Item><Item><Para>Support for 64-bit executables</Para><Para>GDB now has support for debugging 64-bit executables.</Para></Item><Item><Para>No longer necessary to set osabi when working with 64 bits</Para><Para>In previous gdb releases, it was necessary to use set <codeVoice xml:space="preserve">osabi Darwin64</codeVoice> to examine the full contents of registers in a 32-bit app on a processor with 64-bit registers. This is no longer necessary.</Para></Item><Item><Para>gdb's .app app bundle support works for more bundle layouts</Para><Para>gdb will now look at the <codeVoice xml:space="preserve">CFBundleExecutable</codeVoice> key in the application bundle's <codeVoice xml:space="preserve">Info.plist</codeVoice> and look for the executable under that name. So the shortcut gdb <pathName>/My/Workdir/MyProg.app</pathName> will work for more applications.</Para></Item><Item><Para>gdb can step through a longjmp call</Para><Para>If your application has a <codeVoice xml:space="preserve">setjmp()/longjmp()</codeVoice> call, stepping will work correctly through the longjmp.</Para></Item><Item><Para>Performance improvements for single stepping with data formatters</Para><Para>The stepping speed in Xcode when there are custom data formatters that require function calls has been improved. For instance, in an Objective-C application, if you have a number of <codeVoice xml:space="preserve">NSString</codeVoice> local variables in a function, gdb must call one function per object after stepping to see if the contents have changed. </Para></Item><Item><Para>Calling Dead Code Stripping-elided functions in Fix and Continue won't work</Para><Para>If you are developing with Dead Code Stripping, and you add a call to a function that has been stripped by DCS in the process of Fixing a source file at debug-time, that call will not work. You must do a re-link of your program, at which point the Dead Code Stripping feature will recognize the new call to the stripped function and keep the function in your executable.</Para></Item></List-Number></Section>
<Section><Name>Changes since June 2003 Developer Preview (gdb-282):</Name><List-Number><Item><Para>Performance improvements for ZeroLink debugging</Para><Para>Most of the performance problems when debugging large ZeroLink applications have been resolved. Start-up time remains a bit slower with ZeroLink applications versus traditionally linked applications, but after that gdb performs well.</Para></Item><Item><Para>Performance improvements for Carbon applications</Para><Para>gdb will require less memory to debug Carbon applications than was often required previously. This was done with a change to the compiler, so you will need to rebuild your application with gcc 3.3 to realize these benefits.</Para></Item><Item><Para>Fixes for Fix & Continue</Para><Para>A number of minor bugs were patched in the Fix & Continue feature, particularly with ZeroLink programs, multi-threaded programs which have many threads being created/destroyed, and cached symfiles. Several more illegal changes will correctly be reported as errors and the fix operation will be backed out.</Para></Item><Item><Para>Fixes for cached symfiles</Para><Para>A number of fixes for cached symfiles were made, including renaming the gdb commands for better consistency. The previous release notes have been updated to reflect the new command names (using the word "cached" instead of "precompiled"). The old ("precompiled") names are deprecated, but will continue to work until the next major release.</Para></Item></List-Number></Section>
<Section><Name>Changes since December 2002 Devtools update (gdb-250):</Name><List-Number><Item><Para>Support for cached symbol files</Para><Para>GDB is now able to generate and used cached versions of symbol files, to speed up symbol reading. Cached symbol files should behave exactly like normal symbol files, except that they are significantly faster for GDB to read into memory. By default, the GDB installer builds cached symbol files for all system libraries in <pathName>/usr/libexec/gdb/symfiles</pathName>; you can regenerate these files using the <pathName>/usr/libexec/gdb/cache-symfiles</pathName> command. In the event that you run into a problem that you think might be related to cached symbol files, you can remove the <pathName>/usr/libexec/gdb/symfiles</pathName> directory, and GDB should behave normally.</Para><List-Bullet><Item><Para><codeVoice xml:space="preserve">set use-cached-symfiles</codeVoice></Para><Para>Determines if GDB will use cached symbol files that it finds on the system. Defaults to on. Note that if you set this to off in your <codeVoice xml:space="preserve">.gdbinit</codeVoice>, it may not have the behavior you expect, since GDB parses the <codeVoice xml:space="preserve">.gdbinit</codeVoice> file after loading any executables specified on the command-line.</Para></Item><Item><Para><codeVoice xml:space="preserve">set cached-symfile-path</codeVoice></Para><Para>Specifies a colon-separated set of directories that will be searched for cached symbol files, if use-cached-symfiles is set.</Para></Item><Item><Para><codeVoice xml:space="preserve">sharedlibrary cache-symfile <filename> <destination></codeVoice></Para><Para>Generates a cached symbol file for filename into the file or directory specified by <codeVoice xml:space="preserve">destination</codeVoice>. If <codeVoice xml:space="preserve">destination</codeVoice> is a directory, GDB will store the cached symbol file using the basename of the library, with <codeVoice xml:space="preserve">.syms</codeVoice> appended.</Para></Item><Item><Para><codeVoice xml:space="preserve">sharedlibrary cache-symfiles <shlibnums> <destination></codeVoice></Para><Para>Stores cached symbol files for all of the shared libraries specified by <codeVoice xml:space="preserve">shlibnums</codeVoice>. The value of <codeVoice xml:space="preserve">destination</codeVoice> is treated the same way as in <codeVoice xml:space="preserve">sharedlibrary cache-symfile</codeVoice>.</Para></Item></List-Bullet></Item><Item><Para>Support for app wrappers</Para><Para>It is no longer necessary to point gdb at the binary in an application wrapper directory ("<codeVoice xml:space="preserve">app-name.app/Contents/MacOS/app-name</codeVoice>"). If you point gdb at the wrapper directory, it will look for the binary in the correct place.</Para></Item><Item><Para>64-bit support</Para><Para>GDB now contains basic support for debugging 64-bit programs, including several new opcode mnemonics, extended branch-prediction decoding, and 64-bit register support. To indicate to GDB that it should use 64-bit register accesses for a particular program, use the <codeVoice xml:space="preserve">set osabi Darwin64</codeVoice> command before running the executable.</Para></Item><Item><Para>C++ exception catching</Para><Para>We added support for the<codeVoice xml:space="preserve"> catch catch;</codeVoice> and <codeVoice xml:space="preserve">catch throw;</codeVoice> commands in gdb. If you set either one of these, gdb will stop on C++ exception catching and throwing, respectively. The gdb online docs are wrong, however, we don't support catching a particular exception by the <codeVoice xml:space="preserve">catch catch exception</codeVoice> syntax. Instead, you can set the gdb variable <codeVoice xml:space="preserve">exception-{throw,catch}-type-regexp</codeVoice> to any regular expression, and gdb will stop if the exception name matches the regexp. If you have many shared libraries, you will see catchpoints are set. That is to be expected - each shared library gets its own copy of the C++ runtime support, including the catch & throw routines. To stop catching exceptions, just delete the catchpoints.</Para></Item><Item><Para>print-object crashes will now unwind the stack automatically</Para><Para>The <codeVoice xml:space="preserve">print-object</codeVoice> command now sets <codeVoice xml:space="preserve">unwindonsignal</codeVoice> unconditionally when calling the description on the object. This means that if the <codeVoice xml:space="preserve">print-object</codeVoice> crashes, the stack will unwind back to where you called it, and provided your objects description method doesn't affect program state you can continue safely.</Para></Item><Item><Para>Support for scheduler locking</Para><Para>Mac OS X gdb now supports the <codeVoice xml:space="preserve">schedlock</codeVoice> on gdb flag. You can use this to halt all the other threads but the current thread when you continue. This is useful if you want to run introspection calls in the target program without running the other threads. Be careful not to cause deadlocks in this situation.</Para></Item><Item><Para>Altivec vector printing</Para><Para>A number of bugs (mostly in the debug output of gcc) have been fixed that affected printing Altivec vector variables. Since the bugs were mostly in the compiler, you will need to rebuild your code, but then you should have more success examining your altivec variables in gdb. Note that none of the bugs caused errors in the actual use of the vector variables, just the debug info was wrong.</Para></Item><Item><Para><codeVoice xml:space="preserve">sharedlibrary specify-symbol-file</codeVoice></Para><Para>GDB now allows the user to specify the symbol file that should be loaded for a specific shared library loaded by the application using the <codeVoice xml:space="preserve">sharedlibrary specify-symbol-file</codeVoice> command. GDB will relocate the symbol file to the correct address for that shared library entry, unlike the previous behavior of <codeVoice xml:space="preserve">add-symbol-file</codeVoice>.</Para></Item><Item><Para>New output format for <codeVoice xml:space="preserve">info sharedlibrary</codeVoice></Para><Para>The 'Source' field of the output of <codeVoice xml:space="preserve">info sharedlibrary</codeVoice> can now include up to two additional fields. The second, if present, is the name of the object file to which the shared library entry actually refers (typically only used in ZeroLink binaries). The third, if present, is the name of the cached symbol file read in for the shared library in question.</Para></Item><Item><Para>"self" vs. "this" in ObjC++</Para><Para>We now use the current function name to determine whether a function in an ObjC++ file is C++ -- and thus has member data hanging off "<codeVoice xml:space="preserve">this</codeVoice>", or ObjC -- and thus we should look up "<codeVoice xml:space="preserve">self</codeVoice>".</Para></Item><Item><Para><codeVoice xml:space="preserve">thread_abort_safely</codeVoice></Para><Para>We now call <codeVoice xml:space="preserve">thread_abort_safely</codeVoice> before running functions in the target program. This makes it safe to call functions like pthread_self() on a thread that is blocked in the kernel - previously the call would just hang. This does mean if a thread is waiting in a kernel call, calling a function in the target on that thread will cause the kernel call to return with an EINTR. This will not cause a problem if your code protects against spurious wake-ups, which it should do. It is just something to be aware of.</Para></Item><Item><Para><codeVoice xml:space="preserve">info threads</codeVoice> port numbers</Para><Para>We now map the port numbers for threads that gdb receives back to the port space of the target program, so the output of <codeVoice xml:space="preserve">info threads</codeVoice> will match the return of <codeVoice xml:space="preserve">thread_self()</codeVoice>. This still provides a convenient way to match up your threads with what gdb presents.</Para></Item><Item><Para><codeVoice xml:space="preserve">info mach-regions</codeVoice></Para><Para>This command now works correctly, rather than looping infinitely at high address ranges.</Para></Item></List-Number></Section>
<Section><Name>Changes since MacOS X 10.2 (gdb-228):</Name><List-Number><Item><Para>Support for break ... <codeVoice xml:space="preserve">if <expression></codeVoice></Para><Para>GDB now correctly supports the break ... <codeVoice xml:space="preserve">if <expression></codeVoice> for specifying breakpoint conditions at the same time as a breakpoint.</Para></Item><Item><Para>Improved backtracing</Para><Para>A number of fixes have been made to the backtrace mechanism, particularly for backtracing through signal handlers, corrupt stacks, and optimized code. If you find a situation where GDB fails to generate a correct backtrace, please file a complete bug report.</Para></Item><Item><Para>Improvements to <codeVoice xml:space="preserve">detach</codeVoice></Para><Para>It is now possible to detach from programs at any time, even if they were originally started from within GDB. Detaching from a program started from GDB will close that program's input stream.</Para></Item><Item><Para>Watchpoints on the contents of arrays</Para><Para>GDB now supports the use of watchpoints on entire arrays. Given the declaration "<codeVoice xml:space="preserve">int x[100];</codeVoice>", the command <codeVoice xml:space="preserve">watch x</codeVoice> will cause GDB to stop whenever any element of <codeVoice xml:space="preserve">x</codeVoice> changes.</Para></Item><Item><Para>Improved register display</Para><Para>The display of floating-point and Altivec registers has been cleaned up to be more legible. The new command <codeVoice xml:space="preserve">info float</codeVoice> and <codeVoice xml:space="preserve">info vector</codeVoice>. allow display of the floating-point and Altivec registers independently of the other registers.</Para></Item><Item><Para>More reliable variable lookup</Para><Para>GDB is now configured with <codeVoice xml:space="preserve">set read-type-psyms 1</codeVoice> enabled by default. For more information, see "What to do if GDB is not finding types it should," below.</Para></Item><Item><Para>More reliable C++ stepping and breakpoints</Para><Para>A number of bugs were fixed with C++ stepping and breakpoint handling. Stepping into and breaking on methods defined in header files should now be much more reliable (although there are still some issues stepping into inlined C++ functions in header files). If you find any bugs with either C++ stepping or breakpoint handling, please file a complete bug report.</Para></Item><Item><Para>Altivec variable display</Para><Para>GDB now correctly displays the values of Altivec variables on the stack/heap. It no longer prints an extra f field for each variable, and correctly displays each of the separate vector subtypes of each variable. As several aspects of the Altivec improvements were the result of compiler changes, you will need to re-compile Altivec code in order to get the improved debugging support.</Para></Item><Item><Para>Improved C++ type detection</Para><Para>The <codeVoice xml:space="preserve">set print object</codeVoice> command can be used to have GDB automatically detect the type of C++ objects based on their virtual table information. This was present in previous versions of GDB, but should be substantially more reliable in the current release. This feature should not be enabled when running under Xcode, as Xcode already gets the same information via a different mechanism.</Para></Item><Item><Para>Shared library processing</Para><Para>GDB now models each executable as a single object file that can optionally load a number of associated images. GDB uses the properties of <codeVoice xml:space="preserve">exec-file</codeVoice> (or dyld, if the program is running) to determine which shared libraries to load, and the value of <codeVoice xml:space="preserve">symbol-file</codeVoice> to determine where to find <codeVoice xml:space="preserve">symbol-file</codeVoice> for the main executable. The result is that the <codeVoice xml:space="preserve">symbol-file</codeVoice> now behaves as one would expect. A number of bugs in shared library handling (mainly to do with slid executables) have also been fixed.</Para></Item><Item><Para>New commands <codeVoice xml:space="preserve">dump</codeVoice>, <codeVoice xml:space="preserve">append</codeVoice>, and <codeVoice xml:space="preserve">restore</codeVoice></Para><Para>These commands allow data to be copied from target memory to a bfd-format or binary file (<codeVoice xml:space="preserve">dump</codeVoice> and <codeVoice xml:space="preserve">append</codeVoice>), and back from a file into memory (<codeVoice xml:space="preserve">restore</codeVoice>).</Para></Item><Item><Para>Changes to command line processing</Para><Para>The new <codeVoice xml:space="preserve">--args</codeVoice> feature can be used to specify command-line arguments for the inferior from the command line of GDB.</Para></Item><Item><Para>Reloading a changed app should no longer cause crashes</Para><Para>If you launch gdb, load in and run an app, and quit the app, but NOT gdb, then in another terminal window rebuild the app, and finally re-run the app in the old gdb session, it has in the past been possible that gdb will crash (this was not true if you re-ran the app without rebuilding). We believe that all such crashes have are fixed in this release. If it should crash for some reason, the workaround is to quit and restart gdb each time you rebuild your app, as well as to file a full bug report using the normal channels.</Para></Item></List-Number></Section>
<Section><Name>Changes since MacOS X 10.1:</Name><List-Number><Item><Para>Hardware (page protection) watchpoint support</Para><Para>Hardware watchpoints are now supported, with a few limitations. They are implemented using the page-protection mechanism of Mach, not using the hardware watchpoint register. To insert a watchpoint, gdb write-protects the entire page containing the memory address, then traps for write faults to that page. Unfortunately, the Mach kernel does not generate a write fault when a system call tries to write to a protected page --- instead it returns error status to the calling application. So, for example, if you try to read() from a file into memory on any page that contains a watchpoint, read() will return with EADDR, rather than triggering the watchpoint. Also, watchpoints on stack addresses (local variables being the most likely example) can sometimes cause unexpected results.</Para><Para>To use watchpoints in Xcode, use the gdb console. For more information about watchpoints in gdb, please refer to the <URL url="http://developer.apple.com/documentation/DeveloperTools/gdb/gdb/gdb_6.html#SEC31">watchpoints section of the gdb manual</URL>.</Para></Item><Item><Para>"step" or "next" over code that is generating signals:</Para><Para>You should now be able to use gdb's "step" or "next" commands to step through code that is generating signals (for instance through a SIGALRM timer). Previous versions of gdb would occasionally report an error that the target stopped with TARGET_WAITKIND_SPURIOUS; we believe this to be fixed. If you encounter such an error; please file a complete bug report --- in the meantime you can work around the problem by using breakpoints and the "continue" command to move through this code.</Para></Item><Item><Para>Targets who have children who crash</Para><Para>Gdb now properly handles exceptions from children of the program being debugged. Previously, gdb would intercept any exception sent to a child of the program being debugged, and treat it as if it were an exception to the parent. Now it correctly forwards the exceptions to the child, where they are handled normally.</Para></Item><Item><Para>What to do if gdb is not finding types it should</Para><Para>There are two optimizations - one in the compiler, and one in gdb itself - that can cause gdb not to find types that actually are defined in your code. You will see this, for instance, if you try to call "ptype" on a pointer, and get "<unknown>" instead of the correct type. Of course, printing the pointer will also fail in this case.</Para><Para>There are two potential causes for this.</Para><Para>The first, and easiest to fix, is that gdb does not, by default, read in all the types when it reads in the symbols for your executable and libraries. This is because reading in types for all the libraries for a complex Mac OS X application can take 3 or 4 seconds, and so we try to defer reading them till the types are actually used. Usually, the process of getting to a point where you can print a type will cause gdb to bring in all the relevant type information, but this is not foolproof. To switch this default, add the line:</Para><Para><codeVoice xml:space="preserve">set read-type-psyms 1</codeVoice></Para><Para>to your <codeVoice xml:space="preserve">.gdbinit</codeVoice> file.</Para><Para>If that does not fix the problem, you may be running into a bug in gdb's ability to read the compressed type definitions that the "-g" option to gcc3 produces. gcc3 will only emit debug output for a type in any given compilation unit if the type is actually used in that compilation unit. This will make the compile and link go faster, so it is a good thing to do. But for relatively complex type definitions, particularly with C++, this can make the debug output harder to parse, and in some cases, gdb does not parse them correctly.</Para><Para>To get around this, you can turn off this compressed type definition by using the "-gfull" option to the compiler. In Xcode, you can just add this to the OTHER_CFLAGS entry field in the Target panel. In many cases, particularly with C++, this will fix the problem, and you will be able to print all the types in your code again.</Para></Item><Item><Para>Using gcc2-compiled code with gcc3-compiled libraries</Para><Para>Gdb assumes that it will never see a mix of gcc2 and gcc3 compiled C++ code in a single executable. So it determines which abi to use by setting it to gnu-v2, and then if it ever sees a v3 style mangled name, it switches it to v3. This breaks down in the case where you have some shared libraries compiled with gcc3, but the user code is compiled with gcc2. This is a perfectly okay thing to do if the libraries don't export any C++ symbols, but gdb will get the abi wrong, and you won't be able to print any C++ objects in the user code.</Para><Para>To help in this situation, we have added the 'set cp-abi' command. Useful values are "gnu-v2" and "gnu-v3". You can use this to set the appropriate value by hand if you notice the problem arising.</Para></Item><Item><Para>"run" commands in <codeVoice xml:space="preserve">.gdbinit</codeVoice> scripts</Para><Para>The "run" command issued in the startup .gdbinit script no longer works; instead, it causes gdb to hang. We will try to fix this. In the meantime, if you were using the "run" command in your .gdbinit to avoid having to type out a long argument string to pass to the program you are debugging, you can use the "set args" command instead, and just type "run" once gdb has started up.</Para></Item><Item><Para>Improved C++ support, particularly for gcc3-compiled code</Para><Para>A number of improvements have been made for debugging C++ code, particularly C++ code compiled with gcc3. Notable improvements include more reliable support for calling virtual functions of classes, as well as better template support. If you have had problems debugging C++ code in the past because of limitations, you will want to check out the new support --- please report any bugs you may find.</Para></Item><Item><Para>Debugging CFM Applications</Para><Para>Gdb does not support reading the symbolic information for CFM based applications. However, you can do assembly level debugging, and if you build your project with Traceback Tables Inlined (set in Project Preferences->Code Generation->PPC Processor in CodeWarrior) you will be able to see function names in backtraces. The only trick to this is that the system does not launch CFM Apps from the command line, it uses a helper app to do this. So to debug MyApp, you do:</Para><CodeListing><CodeLines><CodeLine xml:space="preserve">$ gdb /System/LibraryFrameworks/Carbon.framework/Versions/A/Support/LaunchCFMApp </CodeLine><CodeLine xml:space="preserve">GNU gdb 5.1-20020125 (Apple version gdb-211) (Wed Mar 27 01:41:44 GMT 2002)</CodeLine><CodeLine xml:space="preserve">Copyright 2000 Free Software Foundation, Inc.</CodeLine><CodeLine xml:space="preserve">GDB is free software, covered by the GNU General Public License, and you are</CodeLine><CodeLine xml:space="preserve">welcome to change it and/or distribute copies of it under certain conditions.</CodeLine><CodeLine xml:space="preserve">Type "show copying" to see the conditions.</CodeLine><CodeLine xml:space="preserve">There is absolutely no warranty for GDB. Type "show warranty" for details.</CodeLine><CodeLine xml:space="preserve">This GDB was configured as "powerpc-apple-macos10".</CodeLine><CodeLine xml:space="preserve">Reading symbols for shared libraries ... done.</CodeLine><CodeLine xml:space="preserve"></CodeLine><CodeLine xml:space="preserve">(gdb) run /Users/Myself/Build/MyApp</CodeLine></CodeLines></CodeListing></Item><Item><Para>Finding the Mach-O executable in an App package:</Para><Para>When you want to run an executable that you have built in an App package in gdb, you need to point gdb at the actual executable, and not the App package directory. For instance, if your application package is in <pathName>/Users/Myself/Build/MyApp.app</pathName>, then you would run gdb as:</Para><Para><codeVoice xml:space="preserve">$ gdb /Users/Myself/Build/MyApp.app/Contents/MacOS/MyApp</codeVoice></Para></Item><Item><Para>Running a project with its own Framework under command-line gdb:</Para><Para>When you debug a Project which uses its own framework(s) under gdb, you need to tell the dynamic loader where to find your framework files. To do this, set the environment variable <codeVoice xml:space="preserve">DYLD_FRAMEWORK_PATH</codeVoice> to point to the directory that contains your framework. You can do this inside gdb by saying:</Para><Para><codeVoice xml:space="preserve">(gdb) set env DYLD_FRAMEWORK_PATH /Users/Myself/Build</codeVoice></Para><Para>before you run the executable.</Para><Note><Name>Note</Name><Para>You do NOT have to set this environment variable when debugging your app with Xcode, as it does this for you automatically.</Para></Note></Item><Item><Para>Setting breakpoints when you have LOTS of code in Frameworks:</Para><Para>If your application is factored into many Frameworks, then setting breakpoints can be painful, since you have to wait till the Framework containing the code is actually loaded before gdb can successfully set the breakpoint. Gdb has the "future-break" command for just this situation. So you say:</Para><Para><codeVoice xml:space="preserve">(gdb) future-break someCode.c:123</codeVoice></Para><Para>and gdb will try to insert this breakpoint each time a new framework is loaded. You will see error messages telling you the breakpoint was not inserted each time a Framework is loaded, until gdb manages to set the breakpoint. Don't worry about these, they are just gdb trying to keep you up to date on its efforts.</Para></Item><Item><Para>Controlling symbol loading from Frameworks:</Para><Para>Mac OS X applications load many frameworks, either directly or implicitly. This can lead to long startup times as gdb processes the symbols in these frameworks. In gdb-200, we added a new set of commands that allow you to control the level of symbol loading from shared libraries. Look at the help for "set sharedlibrary load-rules" for details on how to use this facility.</Para></Item><Item><Para>Vector variables in registers in gcc2</Para><Para>If a vector variable is stored in a register, gcc writes debug information telling gdb which register the variable is stored in. Unfortunately, the mapping changed between gcc2 & gcc3. Since there isn't anything in the debug output to distinguish code compiled by gcc3 from code compiled by gcc2, there is no way for gdb to know the right map. gdb supports the gcc3 map. If you happen to know your vector code is compiled by gcc2, then the register assignment will be off by 1. To get it right, you will need to look at the register one less than the given one (so if "info address v_var" says vr3, it is actually in vr2...). OTOH, if you are compiling your AltiVec code with gcc2, you should seriously consider switching to gcc3 anyway, since it does a much better job of optimising AltiVec code.</Para></Item><Item><Para>Disassembler bug with stwcx. and the like...</Para><Para>The gdb disassembler has a bug with all the PowerPC store instructions, like stwcx., where the first argument is either 0, if the value is zero, or the name of the register from which to read the offset if non-zero. GDB will errantly report the "0" case as "r0". So for instance, you will see:</Para><Para><codeVoice xml:space="preserve">stxcw. r5,r0,r2</codeVoice></Para><Para>which should actually be:</Para><Para><codeVoice xml:space="preserve">stxcw. r5,0,r2</codeVoice></Para></Item></List-Number></Section>
</ReleaseNotes>
</Chapter>