Debug with GDB on macOS 11
The big reason to do this is that LLDB has no ability to "follow-fork-mode child", in other words, a multi-process target that doesn't have a single-process mode (or, a bug that only manifests when in multi-process mode) is going to be difficult or impossible to debug, especially if you have to run the target over and over in order to make the bug manifest. If you have a repeatable bug, no big deal, break on the fork
from the parent process and attach to the child in a second lldb instance. Otherwise, read on.
Install GDB
Don't make the mistake of thinking you can just brew install gdb
. Currently this is version 10.2 and it's mostly broken, with at least two annoying bugs as of April 29th 2021, but the big one is https://sourceware.org/bugzilla/show_bug.cgi?id=24069
$ xcode-select install # install the XCode command-line tools
$ brew install --force --build-from-source domq/gdb/gdb # a patched version based on 10.1
It's now installed at /usr/local/bin/gdb
.
Create and Install a Self-Signed Code-Signing Certificate
- Start the Keychain Access application, found in
/Applications/Utilities
. - From the Keychains list on the left, right-click on the System item and select Unlock Keychain "System".
- Choose Keychain Access > Certificate Assistant > Create a Certificate... from the menu.
- Choose a name (e.g. gdb-cert), set Identity Type to Self Signed Root, set Certificate Type to Code Signing and select the Let me override defaults. Click several times on Continue until you get to the Specify a Location For The Certificate screen, then set Keychain to System.
- If for some reason you create the certificate in the System keychain directly, create it in the Login keychain, then export it. You can then import it into the System keychain.
- Finally, using the context menu for the certificate, select Get Info, open the Trust item, and set Code Signing to Always Trust.
- From the Keychains list on the left, right-click on the System item and select Lock Keychain "System".
- You must quit the Keychain Access application and restart the system, in order to use the certificate.
Create the entitlements plist file (for macOS 10.14 and newer)
We'll call it gdb-entitlement.xml
:
<?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>com.apple.security.cs.allow-jit</key>
<true/>
<key>com.apple.security.cs.allow-unsigned-executable-memory</key>
<true/>
<key>com.apple.security.cs.allow-dyld-environment-variables</key>
<true/>
<key>com.apple.security.cs.disable-library-validation</key>
<true/>
<key>com.apple.security.cs.disable-executable-page-protection</key>
<true/>
<key>com.apple.security.cs.debugger</key>
<true/>
<key>com.apple.security.get-task-allow</key>
<true/>
</dict>
</plist>
Codesign and entitle the GDB executable
$ codesign --entitlements gdb-entitlement.xml -fs gdb-cert $(which gdb)
This seems to work even though that's Homebrew's link to the actual file on disk:
% ls -la $(which gdb)
lrwxr-xr-x 1 mmyers admin 26 Apr 28 16:16 /usr/local/bin/gdb -> ../Cellar/gdb/10.2/bin/gdb
% codesign -vvv /usr/local/Cellar/gdb/10.2/bin/gdb
/usr/local/Cellar/gdb/10.2/bin/gdb: valid on disk
/usr/local/Cellar/gdb/10.2/bin/gdb: satisfies its Designated Requirement
Finally, Run GDB
$ gdb hello_world
(gdb) break main
(gdb) run
Troubleshooting
- GDB will not understand "fat" executables. You can "lipo -thin x86_64" them.
- If you tried debugging with gdb, but you get a "No symbol table is loaded" error, you might need to compile programs with the
-ggdb
option ingcc
. I didn't have this issue personally. - If after hitting
run
in gdb, you get "Starting program: /path/to/your/executable [args] [New Thread 0x2303 of process 795]" followed by a blank line which does not respond to anything, then you have hit GDB bug 24069. Check that you built the patched version from source.
@mike-myers-tob A note about the entitlements, the only really neeeded entitlement is
com.apple.security.cs.debugger
, which lets the system know that GDB is a debugger and can control other processes.It is a good idea to also add
com.apple.security.get-task-allow
, which lets the system know that other processes are allowed to debug the GDB binary (e.g. if you want to debug GDB using LLDB, or another GDB instance). The other entitlements are not needed at all in my experience.