Using gdb debugger on macOS is no longer straightforward since Xcode stopped using it and replaced it with lldb. Starting from macOS Sierra, there are several steps to follow to make it work.

Install gdb

The easiest way to install gdb is by using Homebrew: "the missing package manager for macOS". If you don't have it installed, open your Terminal prompt and write this command:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Once you have Homebrew, you can install gdb. If you're using High Sierra (macOS  10.13), be aware that gdb 8.1 and 8.2 are not compatible. Instead, use gdb 8.0.1.

To install the latest version of gdb, run this command:

brew install gdb

You can install a specific version in this way:

brew install gdb@8.0.1

In case you already have a newer version of gdb, brew allows you switch version with the following command:

brew switch gdb 8.0.1

By running this command, you can find out your gdb version:

gdb --version

Take note of the version: you'll need it later. In my case, it is 8.0.1.

Generate a certificate

Installing gdb is not enough. If you try debugging a file, you'll get an error since the Darwin kernel doesn't allow gdb to control another process without having special rights. For security reasons, this is the default behaviour.

To give gdb those permissions, you need to generate a certificate.

  1. Launch Keychain Access application: Applications > Utilities > Keychain Access.
  2. From the Keychains list on the left, right-click on the System item and select Unlock Keychain "System".
  3. Go to Keychain Access > Certificate Assistant > Create a Certificate.
  4. Choose a name (e.g. gdb-cert).
  5. Set Identity Type to Self Signed Root.
  6. Set Certificate Type to Code Signing.
  7. Check the Let me override defaults check box.

At this point, you can go on with the installation process until you get the Specify a Location For The Certificate dialogue box. Here you need to set Keychain to System. Finally, you can click on the Create button.

After these steps, you can see the new certificate under System keychains. From the contextual menu of the newly created certificate (right-click on it) select the Get info option. In the dialogue box expand the Trust item and set Code signing to Always Trust.

Then, from the Keychains list on the left, right-click on the System item and select Lock Keychain "System".

Finally, reboot your system.

Sign the certificate for gdb

It's time to sign the certificate. Open your Terminal prompt and run:

codesign -s gdb-cert gdbPath

where gdb-cert is the name of your certificate and gdbPath is the full path to your gdb binary file. If you have installed gdb as explained before (using Homebrew), the path should be: /usr/local/Cellar/gdb/version/bin/gdb (replace version with the actual version of your gdb installation, e.g. 8.0.1).

Create a gdb command file

If you are on macOS Sierra (10.12) or later, you need to do this extra step.

In the home directory, create a new file called .gdbinit and write the following command in it:

set startup-with-shell off

From the Terminal, you can do that by running this:

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

Now you can use gdb for debugging files on your Mac. If you use Eclipse, follow the next step.

Set Eclipse for using gdb

If you want to configure gdb for a specific project in Eclipse, you need to set some options:

  1. Go to Run > Debug Configurations...
  2. Select a launch configuration from the list on the left (e.g. C/C++ Application)
  3. Open the Debugger tab from the menu on the right
  4. Set GDB debugger to the full path of your gdb binary file (the same used for signing the certificate)
  5. Set GDB command file to the full path of your .gdbinit file: ~/.gdbinit (or the extended form /Users/yourname/.gdbinit, where yourname is your username)
  6. Click on the Apply button.
Eclipse window for debug configurations

In case you want to define a default configuration for gdb to be used in any Eclipse project, these are the steps to follow:

  1. Go to Eclipse > Preferences
  2. From the left menu select C/C++ > Debug > GDB
  3. Set GDB debugger to the full path of your gdb binary file (the same used for signing the certificate)
  4. Set GDB command file to the full path of your .gdbinit file: ~/.gdbinit (or the extended form /Users/yourname/.gdbinit, where yourname is your username)
  5. Click on the Apply button.

Now, you can debug files from inside Eclipse using gdb.

Conclusion

In this tutorial, I've shown you how to install gdb and use it to debug a C/C++ application on macOS.

Special thanks to those people who helped me improve this article by commenting with suggestions and tips.

Resources

Last Update: 16 October 2018