DEV Community

Jason
Jason

Posted on

Install Gdb Mac Setup gdb on macOS in 2020

gdb on macOS

Beginning with Mavericks (macOS 10.9) Xcode stopped supporting the gdb debugger. Below are steps to walk you through solving this not-so-straightforward problem.

Table of Contents

Install gdb

Open the Terminal app, Applications > Utilities > Terminal. This guide uses the Terminal throughout, so it's best to leave it open until you have finished all of the steps.

If you don't already have gdb on your system, then you'll need to install it. I'm going to show you how to install gdb by using Homebrew.

Start by verifying whether you already have gdb installed on your system. Type the following in Terminal:



gdb --version


Enter fullscreen mode Exit fullscreen mode

If you have gdb on your system already, you can skip to the Generate a certificate step. If you received an error, then you'll need to install gdb using Homebrew.

Verify whether or not you have Homebrew by typing:



brew --version


Enter fullscreen mode Exit fullscreen mode

If Homebrew isn't already installed on your system, you'll need to install it. Using Terminal, type (or copy and paste) the following command:



/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"


Enter fullscreen mode Exit fullscreen mode

Once Homebrew is installed, you can install gdb. The current version of gdb as of this writing is 9.2, which is confirmed working on Catalina as of Sept. 2020.

In order to install gdb type the command:



brew install gdb


Enter fullscreen mode Exit fullscreen mode

You can confirm whether gdb is installed properly by running:



gdb --version


Enter fullscreen mode Exit fullscreen mode

If everything went well then you're ready to move on to the next step!

Generate a certificate

If it was as simple as installing gdb, I wouldn't have made this guide! If you attempt to debug a file now, you will get errors and unexpected behavior because the Darwin kernel does not allow gdb to control another process without having special rights. Fortunately the rest of this guide walks you through all of the steps you'll need in order to use gdb effectively on your Mac.

In order to give gdb the permissions it needs, you'll need to generate a self-signed certificate.

Here are the steps:

  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. From the toolbar, 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 checkbox.
  8. 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.
  9. 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.
  10. Then, from the Keychains list on the left, right-click on the System item and select Lock Keychain "System".
  11. Finally, reboot your system.

Sign certificate for gdb

Now you'll need to sign the certificate. Create a file called gdb-entitlement.xml. This allows macOS to trust gdb operations for debugging. Type the following into the xml file you just created, and save it:



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


Enter fullscreen mode Exit fullscreen mode

Now back in the Terminal app, navigate to the directory where you saved the xml file.
*note. <gdbPath> in the following command is your path to gdb. It will be something like
/usr/local/Cellar/gdb/version/bin/gdb
or
/usr/local/bin/gdb.
You can find out for sure by typing the following in the terminal:



which gdb


Enter fullscreen mode Exit fullscreen mode

Replace <gdbPath> with your path to gdb.



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


Enter fullscreen mode Exit fullscreen mode

where gdb-cert is the name of the certificate you created earlier, and gdbPath is the full path to your gdb binary file.

Create a gdb command file

For this step, do one of the following.
Either:

  • In the home directory, create a new file called .gdbinit. Write the following command into it and save: ```bash

set startup-with-shell off

or 
* Type the following into the Terminal:
```bash


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


Enter fullscreen mode Exit fullscreen mode

Generating builds

We're almost there! If you tried debugging with gdb now, you would likely receive a "No symbol table is loaded" error. In order to solve this, you'll need to compile programs with the -ggdb option, as in the following example:



gcc hello_world.c -o hello_world -ggdb.


Enter fullscreen mode Exit fullscreen mode

At this point you should be able to successfully debug your programs on Mac using gdb. Do a test by running (for example):



gdb hello_world


Enter fullscreen mode Exit fullscreen mode

and then from the gdb prompt, try creating a breakpoint:



(gdb)break main


Enter fullscreen mode Exit fullscreen mode

You should see something like the following:



Breakpoint 1 at 0x100000de5: file hello_word.c, line 15.


Enter fullscreen mode Exit fullscreen mode

I hope you're seeing the results you expected! Leave a comment and let me know how it goes!

Reference list:

Top comments (18)

Collapse
 
shellcromancer profile image
Daniel Stinon-Diess • Edited

Or you can use lldb instead! I found myself much happier after switching for debugging and program analysis tasks. Saved time from fighting the system and this is updated regularly with the macOS tool chains.

Collapse
 
dnsmichi profile image
Michael Friedrich

If your application forks child processes, gdb supports following the forks. lldb unfortunately does not, and you have to workaround this with debug code to delay the child startup and re-attach to the PID. More here: stackoverflow.com/questions/147463...

Collapse
 
jasonelwood profile image
Jason

Agreed! Unfortunately I'm taking a class that requires gdb.

Collapse
 
desparza22 profile image
desparza22

After typing break (line number), hitting enter and then typing run (or run [args]) I get "Starting program: /Users/diegoesparza/CS_Ventures/LearnC/factorial [args]
[New Thread 0x2303 of process 795]" followed by a blank line which does not respond to anything I type. Does anyone else get this? I have searched around and tried different ways of installing gdb but I get the same thing

Collapse
 
eric_c_fd089c02bd67a0d41f profile image
Eric C

When I run the following command below, I receive an error of 'cannot read entitlement data'. What can I do to resolve this?


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

Enter fullscreen mode Exit fullscreen mode
Collapse
 
nezda profile image
Luke Nezda

Maybe you didn't make gdb-entitlement.xml file described in the directions?

Collapse
 
ethanj0hn profile image
Ethan John

I followed this and I no longer get the gdb is codesigned error; however, everytime I run gdb it goes into a new thread and nothing happens unless I press ctrl z :(

Collapse
 
jeancasteres profile image
Jean Casteres

Hello Jason, Thank you for this post it helped me a lot setting up gdb on MacOS Monterey. The project I am working on must use gdb and CodeBlocks dev environment. From a terminal I can run gdb OK, but from CodeBlocks it sometimes crashes the environment. Do you have some experience in such a setup or could you point me in the correct direction ? Thank you.

Collapse
 
isaactait profile image
Isaac Tait

Thank you for this, I found it very helpful.

Collapse
 
praisedone profile image
praisedOne • Edited

I have completed the gdb path linking part too but it shows an error for code signed. Then it says zsh: parse error near '\n' . Can someone help me here. what should I do from here?

Collapse
 
dianamendbayar profile image
diana-mendbayar

Git rid of <> from this line:
codesign --entitlements gdb-entitlement.xml -fs gdb-cert

Collapse
 
firemanchief52 profile image
Stefano

I made every thing following the instructions above .. but at "Sign the certificate for gdb" I receive the follow error:
"error: The specified item could not be found in the keychain." But the certificate is in KeyChain.
Please can someone help me to sort it out.

Collapse
 
bryan_butler_428900dd5c9b profile image
Bryan Butler

I am using an old 2010 - 2012 Mac Pro and working with Code Lite for a C++ class. My OS is Mojave. I was not able to generate the certificate using the method above. However, I followed the following steps to generate the certificate:

opensource.apple.com/source/lldb/l...

Then your steps Signing the Certificate and then Create a gdb Command File made it all work. Thanks.

Collapse
 
brianharvey profile image
Brian Harvey

When trying to create the certificate I get "Unknown error=-2,147,414,007" MacOS 10.13.4. gdb 10.1. Thanks.

Collapse
 
hao_wang_769af06568f811ae profile image
Hao Wang

Checkout the first ref in the article (section 'Troubleshooting the certificate generation')

Collapse
 
furkanbezci profile image
furkanbezci

gdb-entitlement.xml: cannot read entitlement data