Installing GDB on OS X Mavericks

  By | |
170 Comments

If you prefer watching videos to reading articles, Cody Henrichsen has created a video walkthrough of this procedure.

With its new OS release, Apple has discontinued the use of GDB in OS X. Since 2005 Apple has steadily been moving away from the GNU toolchain in favor of LLVM. This means that Xcode now uses LLDB instead.

LLDB looks to be a very nice replacement for GDB, and I hope to use it in the future, but currently Xcode is the only graphical front-end that supports its use; pretty much every other debugging GUI uses GDB under the hood, including Eclipse. So, if you want to debug C/C++ code in Eclipse CDT on the Mac, you must install GDB.1

Here is the procedure that worked for me.2 Others have reported issues with this, so please do let me know in the comments if it doesn't work for you.

Known Issues

GDB will not be able to breakpoint inside any template function, though it should be able to step into it. This problem may be resolved if you use the MacPorts installation procedure (below) but it may only work if you also compile with Apple's GCC.

It was also reported in the comments that it cannot breakpoint into a shared library function. I have not confirmed this issue myself.

On OS X Yosemite, the MacPorts version will require some extra hoops to jump through. See below.

Installing GDB

You can install via MacPorts or Homebrew. MacPorts has Apple's official GDB distribution, which is modified for OS X. This is probably the best option (thanks to CC's comment for this tip). However, on my machine this only seems to work if the program is compiled using Apple's GCC, which is no longer supported by Apple. All things being equal, I vastly prefer to avoid MacPorts altogether. So I installed with Homebrew, despite recommending MacPorts. If you have no preference either way, go with MacPorts.

Update for Yosemite users: I haven't upgraded to Yosemite yet, but some folks have reported problems in the comments below (and for some, it worked fine). It seems that Apple's GDB (the MacPorts install) is currently broken on Yosemite. If you know what you're doing, you can apply the Portfile patch from this ticket. It seems like a bit of a pain, though, so you might switch to plain vanilla GDB, which can be installed with either MacPorts or Homebrew.

Install with MacPorts

  1. Install Xcode and MacPorts, if not already installed.
  2. Now install the Apple GCC and GDB from MacPorts:
  3. For the remainder of the tutorial, use /opt/local/bin/gdb-apple as the GDB executable
  4. Remember if you want breakpoints in template functions to work, you'll need to change your compiler to g++-apple-4.2 instead of g++! This can be done in your Makefiles or in your IDE settings.

Install with Homebrew

  1. Install Xcode and Homebrew, if not already installed.
  2. Now install GDB from Homebrew:
  3. For the remainder of the tutorial, use /usr/local/bin/gdb as the GDB executable

If that worked, then lucky you! Getting it compiled is where many people seem to have trouble. Now you just need to sign it to give it permission to control OS X processes.

Certifying GDB

Open up the Keychain Access application (/Applications/Utilities/Keychain Access.app). Navigate via the menu to Keychain Access > Certificate Assistant > Create Certificate...

create-cert-menu

Enter a name for the certificate. For this how-to, I'll call it "gdb-cert". Set the fields exactly as shown below.

create-cert-1

The maximum validity period is 999 days. I don't really want to deal with this again, so I'm going to max it out.

create-cert-2

Keep clicking the "Continue" button until you are asked for a location. Set it to "System".3

create-cert-3

Success!

create-cert-4

Now make sure the cert is always trusted. Right-click the new certificate and select Get Info. Under the Trust section, set Code Signing to Always Trust.

cert-get-info

cert-always-trust

Now that we have a certificate, we need to use it to sign GDB. First, we'll restart the taskgated process to make sure it picks up the new certificate. Quit Keychain Access (you must quit Keychain Access!) and return to the Terminal for these final commands.

Find the taskgated process.

The first number in the above output is the PID. Use this to kill the process (it will immediately restart itself).

Now you can finally code sign GDB.

Now you should be all set! The OS X Keychain may ask for your password the first time you attempt to debug a program, but it should work!

Getting it to Work with Eclipse

There's one more step for Eclipse users. You need to specify where Eclipse can find the new GDB. Specify the path to GDB in Preferences > C/C++ > Debug > GDB:

eclipse-gdb-pref

If you already have some debug configurations, you may need to edit them individually to point to the correct place (under Run > Debug Configurations...):

eclipse-gdb-debug

  1. The CDT developers are planning to support LLDB, but they will have to write a whole new interface, and I think most of them only work on Eclipse in their spare time, so it will likely be at least some months before LLDB support is there.
  2. The procedure is derived from this StackOverflow post and this GDB Wiki page.
  3. If you are unable to save it to the System keychain, then save it to the login keychain. You can later export the cert, and then import it into the System keychain. I didn't have to do this, so comment if you have any problem.