gdb Debugger for macOS

This guide will walk you through the steps of installing the gdb debugger on a macOS machine and having it run properly. Also, this tutorial works for Big Sur 11.4 and it might not work for later versions.

We will be using brew to install gdb. If you haven’t installed it, check out here. And it is a good practice to have it up-to-date.

brew update

Install gdb

Check if gdb exists on your device.

gdb --version

Install gdb through brew

brew install gdb

Debugging with gdb

Once you are done, you can enter the gdb interface with your executables. For instance:

gdb a.out

The program doesn’t actually run at the moment, but you can see the terminal displays (gdb) at the begining of the command line instead of the original directory path. In the terminal , simply type run to execute the file.

(gdb) run

Unfortunately, things are not so easy for me. I get the error message

gdb unable to find mach task port

As you might guess, this is a macOS issue. We need to create a certificate for the debugger so that it can properly do its work.

Create a certificate for gdb

1. Find your Keychain Access.app

2. In the top left corner just beside the apple icon, you should find the Keychain Access in the tool bar. Select Keychain Access > Certificate Assistant > Create a Certificate

3. Fill out the field as shown below. Then create it.

Right now you should be able to see the certificate in the login keychain (in the sidebar on the left there are login, iCloud, System, and System roots).

4. Move the certificate from login to System using copy and paste (you can delete the original certificate in login). Somehow the drag-and-drop doesn't function here.

5. Once the certificate is in the System keychain, right-click on it, go to Get Info and expand Trust. Set the drop-down menu to Always Trust.

6. Reboot before you proceed.

Sign the certificate

The next step is to sign it. Save the following code as gdb-entitlement.xml. I don’t know where you save it matters. For me, I save it under /Users/username.

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

Then, locate gdb by typing

which gdb 

It is under /usr/local/bin/gdb in my device.

Enter the following command in the terminal with <gdbPath> replaced by your path of gdb.

codesign --entitlements gdb-entitlement.xml -fs gdb-cert <gdbPath>

Set up gdb init file

When you run gdb with your executable again, you may encounter another issue:

During startup program terminated with signal SIG113, Real-time event 113

You can fix this by set up an init file.

echo "set startup-with-shell off" >> ~/.gdbinit

And you should be good to go!

References:

Setup gdb on macOS in 2020

MAC上使用gdb(完美解決)