Gdb For Mac Os X

Creating a C++ application using the Standard Template Library and the CDT

Gdb Mac Os X Brew
Gdb For Mac Os X64
Gdb For Mac Os X 10.13
Gdb For Mac Os X 10.10
Gdb For Mac Os X 10.8
Download Gdb For Mac Os X

GDB Installation on Mac OS X. If you work on a Mac OS X 10.9 Mavericks or later, you will run into the problem of Eclipse refusing to interactively debug problems that otherwise build and run fine: An attempt to start a debugging session by selecting Run.
Using GDB on Mac OS X INSTALLATION: if not installed already, install brew; if you have brew already on your system, you might want to update the brew installation, typing: brew update. This will give you the latest installation recipes; install GDB: brew install gdb. This will install the latest GDB.

This document explains how to debug Mozilla-derived applications such as Firefox, Thunderbird, and SeaMonkey on macOS using Xcode. If you want to debug from the terminal see Debugging Mozilla with lldb. For specific information on a way to debug hangs, see Debugging a hang on OS X.

This article, which is a follow-up to 'C/C++ development with the Eclipse Platform,' is intended for C++ developers who want to learn C++ development using the Eclipse CDT. A simple C++ application is developed in the article. The application makes use of the C++ STL. Readers should be familiar with the STL, as well as with basic object-oriented programming principles such as inheritance and polymorphism. A familiarity with Eclipse will be helpful, but is not required.

Before we start

You need to install the following:

Eclipse
We're using the CDT, which is a plug-in to Eclipse, so of course you need Eclipse. The article uses Eclipse V3.2.
Java Runtime Environment
We're building a C++ application, but we're using Eclipse. Eclipse is a Java application itself, so it needs a Java Runtime Environment (JRE). The article uses Eclipse V3.2, which requires a JRE of V1.4 or higher. If you want to also use Eclipse for Java development, you'll need a Java Development Kit (JDK).
Eclipse C/C++ Development Toolkit (CDT)
This article is about the CDT, so you'll need it, of course. For instructions on installing the CDT on early versions of Eclipse, read a 'C/C++ Development with the Eclipse Platform' (developerWorks 2003) .
Cygwin
If you're using Microsoft Windows®, you will find Cygwin — which provides a Linux®-like environment on Windows — helpful.
GNU C/C++ Development Tools
The CDT uses the standard GNU C/C++ tools for compiling your code, building your project, and debugging the applications. These tools are GNU Compiler Collection (GCC) for C++ (g++), make, and the GNU Project Debugger (GDB). If you're a programmer using Linux or Mac OS X, there's a pretty good chance these tools are installed on your machine. The article contains instructions for setting up these tools for Windows.

The Eclipse CDT

The Eclipse CDT is an Eclipse plug-in that transforms Eclipse into a powerful C/C++ IDE. It was designed to bring many of the great features Eclipse enjoyed by Java developers to C/C++ developers, such as project management, integrated debugging, class wizards, automated builds, syntax coloring, and code completion. When Eclipse is used as a Java IDE, it leverages and integrates with the JDK. Similarly, the CDT leverages and integrates with standard C/C++ tools, such as g++, make, and GDB. This has lead to it becoming very popular on Linux, where those tools are readily available and used for most C++ development. The CDT can be set up on Windows to use the same tools. There is also an ongoing effort to get the CDT to work with Microsoft's C++ tools to make it even more attractive to Windows C++ developers.

Installing the CDT

We start by assuming you installed Eclipse and can run it. If not, consult Eclipse's Web site for getting up and running. Let's install the CDT. The CDT is an Eclipse plug-in, so it uses Eclipse's Software Updates feature. Select Help > Software Updates > Find and Install.

Gdb Mac Os X Brew

Figure 1. Eclipse Software Updates

Next, you'll want to choose Search for new features to install.

Figure 2. Search for new features

If you're using a newer version of Eclipse, the Callisto or Europa discovery sites should be included. (Editor's note: Since this was written in April 2007, the Europa release was still in the planning stages. However, installing Europa is expected to be similar to Callisto.) Simply select it and click Finish.

Figure 3. Callisto Discovery Site

Eclipse might ask you to choose from a list of mirror sites for the Callisto Discovery Site. Pick whatever one seems closest to you. You should see a list of plug-ins from the Callisto Discovery Site. You'll want to select C and C++ Development and click Next.

Figure 4. Available Callisto plug-ins

You'll be asked to accept the license for the CDT. Once you've done that, you can click Next. You'll see a summary of what's going to be downloaded and installed. Simply click Finish.

Figure 5. Download and installation summary

Eclipse's Update Manager will then download the CDT plug-in from the mirror site you selected earlier. The CDT is about 11 MB total, so this could take a few minutes, depending on your Internet connection speed. Once everything is downloaded, you'll be asked to confirm that you want to install the new features. Click Install All.

Figure 6. Confirm installation

After you finish installing CDT, you'll be asked to restart Eclipse. Go ahead and do that. Once Eclipse restarts, the CDT will be ready to go.

Windows configuration

If you're running Eclipse on Linux or Mac OS X, you're ready to start using the CDT to develop a C++ application. If you're on Windows, there might be a few more steps. As mentioned, CDT relies on the standard GNU C++ development tools: g++, make, and GDB. These are usually included on Linux or Mac OS X. They're usually not included with Windows. But don't worry. These tools can be easily installed on Windows. Perhaps the easiest way is to install Cygwin. Cygwin provides Linux-like environment on Windows (see Related topics). When installing Cygwin, you'll be asked to pick the packages you want to install. Make sure to go into the development section and select gcc: g++, make, and GDB. This will cause their prerequisites to be installed, too.

Once you're done installing Cygwin, you'll need to add g++, make, and GDB to your path. The easiest way to do this is to add Cygwin's bin directory to your path, since that's where g++, make, and GDB can be found. Once that's done, restart Eclipse.

Playing the lottery

At this point, we should be ready to start developing our application with CDT. Let's pause to figure out what we want to develop. The sample application is a simple command-line program for generating lottery numbers. Many states have lotteries, and the rules vary quite a bit. We'll allow the user to pick which state lottery he wants to generate numbers for. This will provide us a good way to use C++'s support for polymorphic behavior.

Creating the project

Eclipse uses the concepts of perspectives to allow for various plug-ins to customize their commands and views. Eclipse starts off by default in the Java perspective. CDT includes its own perspective, so we'll want to switch to that. To do that, select Window > Open Perspective > Other. You should see a list of perspectives available to you. Select the C/C++ perspective and click OK.

Figure 7. Select C/C++ perspective

Eclipse should now look something like Figure 8.

Figure 8. The C/C++ perspective

Eclipse organizes your code into projects, so we'll want to create a new project. Select File > New > Managed Make C++ Project.

Figure 9. New C++ project

Gdb For Mac Os X64

You might have noticed there were several different options for the project. We wanted a C++ project. We selected a 'Managed Make,' since that will allow Eclipse to create the make file for us. You could select a 'Standard Make' flavor and write your own make file. We should now be in the New Project wizard, where we'll name our project Lottery and click Finish.

This will create an empty project, which you should see in the C/C++ Projects window. Right-click on the project and select New > Source Folder. This will bring up the 'New Source Folder' wizard, where we'll name our folder src and click Finish.

Basic lottery

We're ready to start creating some code. We'll start by creating the executable of our application. Right-click on the source folder we just created and selected New > Source File, as shown in Figure 10.

Let's create an empty main method for now. This is just a placeholder; we'll add more to this after we've created the rest of our project.

Save your project, and Eclipse will make it for you automatically. You should see some output in the console indicating that it compiled successfully.

We're ready to create our first class. Right-click on the source folder we just created and select New > Class.

Figure 10. New class

This should bring up the New Class wizard. We'll give our class a namespace lotto, and we'll call our class Lottery.

Figure 11. Lottery class

Eclipse will now create stubs for your class. CDT does a lot of nice things for you. It generates the appropriate compiler directives in the header file. It encourages best practices by generating separate interface (Lottery.h) and implementation (Lottery.cpp) files. It encourages another best practice by making your class' destructor virtual. We can enter the source code for these classes as seen in Listings 1 and 2.

Listing 1. Lottery.h

Listing 2 shows the implementation file for the Lottery class.

Listing 2. Lottery.cpp

What's this code doing? Well, our Lottery class has two attributes. The ticketSize attribute is the number of numbers on the lottery ticket. The maxNum is the maximum number on the ticket. Later, we'll use the Florida state lottery as an example. There, you pick six numbers from 1 to 53, so ticketSize would be 6 and maxNum would be 53.

The generateNumbers method generates an array of numbers corresponding to the numbers on a lottery ticket. It uses the STL function rand() to generate numbers randomly. The allNums array is used to keep track of what numbers have been generated so far, so we can make sure we don't get a duplicate number on our ticket. Finally, the printTicket() creates a string representation of our ticket.

When you save the files, Eclipse builds your project automatically. Again, if you save the project, it should be compiled and you should see compilation messages in the console, as shown in Listing 3.

Listing 3. Compiler output in console

`MegaLottery` class

You might have noticed that we made the printTicket() method virtual when it was declared in the header file. That will allow us to subclass Lottery and override this method. We wanted to do that because some states have a lottery with a 'mega' number. This is a separately drawn number that any ticket must match in addition to the other numbers drawn. Let's create a MegaLottery class for these states that will subclass Lottery.

Once again, right-click on our source folder and select New > Class, as we did earlier. This time in the New Class wizard, we'll declare our new class in the same namespace, but call it MegaLottery.

Figure 12. `MegaLottery` class

To subclass Lottery, select the Add button next to the Base Classes section. This will bring up the Choose Base Class dialog. You can start typing the name of the class, and Eclipse will narrow the list of base class candidates quickly. You'll want to select Lottery and click OK.

Figure 13. Choose base classes

We can enter the code for MegaLottery, as shown in Listings 4 and 5.

Listing 4. MegaLottery.h

Listing 5 shows the implementation file for the MegaLottery class.

Listing 5. MegaLottery.cpp

Gdb For Mac Os X 10.13

The main difference between Lottery and MegaLottery is that MegaLottery has an extra attribute maxMegaNum. This is the max value that the mega number can take. It overrides the printTicket() method. It uses the base class to generate the first part of the ticket, then it generates the mega number and appends it to the string representation of the ticket.

We just need a way to create the various lotteries. We'll use a class Factory Pattern to do this. We'll do this by adding a LotteryFactory class. We want all Lotteries to come from the same factory, so we'll make LotteryFactory a singleton. The code for it is in Listings 6 and 7.

Listing 6. #ifndef LOTTERYFACTORY_H_

Listing 7 shows the implementation file for the LotteryFactory class.

Listing 7. LotteryFactory.cpp

The LotteryFactory has an enum of the different types of lotteries. We've only put in Florida and California in the example, but it shouldn't be hard to add as many as you want. The LotteryFactory's constructor seeds the rand() function used by our lottery classes. We just need to implement our executable's main method.

Listing 8. Main.cpp

Running the program

We're ready to run our program. Select Run > Run.

Figure 14. Choose base classes

Select C/C++ Local Application and click the New button.

Figure 15. New C/C++ run profile

This will bring up the Create run configuration interface for the Lottery project. You'll need to select its executable by clicking the Search Project button.

Figure 16. Search project for executable

You can select the binary that Eclipse created for you and click OK.

Figure 17. Search project for executable

Gdb For Mac Os X 10.10

Just click Run, and the program should run in your console. The code below shows some sample output.

Debugging the program

Our program should run fine, but let's take a look at debugging the application. First, create a breakpoint in our code. Pick a line and right-click next to it and select Toggle Breakpoint.

Figure 18. Create breakpoint

We need to create a debug configuration, much like we created a run configuration. Select Run > Debug.

Figure 19. Create debug configuration

This should bring up the Debug configuration. This is based on the Run configuration, and you shouldn't need to change anything. Just click Debug.

Gdb For Mac Os X 10.8

Figure 20. Debug configuration

Download Gdb For Mac Os X

Once the debugger starts, it will prompt you to switch to the Debugger perspective. Do so. Notice that in the configuration we set things to break automatically at the startup of our main method. Thus, the debugger should break immediately and you should see a screen something like Figure 21.

Figure 21. The debugger

Summary

We've built and debugged our lottery application. You can easily add more lottery schemes to it. Some of these could involve additional subclasses. CDT makes it easier than ever to create these classes and class hierarchies, and to run and debug the application to test it.

Downloadable resources

Debugging Chromium on macOS

Resources:
Contents
4 Debugging the renderer process
11 Debugging in Release Mode

The Mac OS X Debugging Magic Technote contains a wealth of information about various debugging options built in to macOS.
IMPORTANT: By default, Xcode has the 'Load Symbols Lazily' preference set. As a result, any symbols not in the main static library (99% of our code) won't be visible to set breakpoints. The result is that you set breakpoints in the editor window and they're ignored entirely when you run. The fix, however, is very simple! Uncheck the 'Load Symbols Lazily' checkbox in the 'Debugging' panel in preferences. Now all your breakpoints will work, at the expense of a little longer load time in gdb. Well worth it, if you ask me.

ALSO IMPORTANT: If you include fast_build=1 in your GYP_DEFINES, there is an excellent chance the symbols you'll need for debugging will be stripped! You may save yourself a lot of heartache if you remove this, rerun gyp_chromium and rebuild before proceeding.

Disabling ReportCrash

macOS helpfully tries to write a crash report every time a binary crashes – which happens for example when a test in unit_tests fails. Since Chromium's debug binaries are huge, this takes forever. If this happens, 'ReportCrash' will be the top cpu consuming process in Activity Monitor. You should disable ReportCrash while you work on Chromium. Run man ReportCrash to learn how to do this on your version of macOS. On 10.8, the command is
launchctl unload -w /System/Library/LaunchAgents/com.apple.ReportCrash.plist
sudo launchctl unload -w /System/Library/LaunchDaemons/com.apple.ReportCrash.Root.plist

Yes, you need to run this for both the normal user and the admin user.

Processing Apple Crash Reports

If you get a Google Chrome crash report caught by ReportCrash/OS X, it will not have symbols (every frame will be ChromeMain). To get a symbolized stack trace, use the internal crsym tool by simply pasting the contents of an entire Apple crash report.

Debugging the renderer process

Xcode's built in gdb wrapper doesn't allow you to debug more than one process at once and doesn't deal very well with debugging Chrome's subprocesses directly. There are two different ways around this:

(a) Run Chrome in a single process

(NOTE: this option is not recommended any more -- Chrome's single-process mode is neither supported nor tested.)

Edit the Executable settings for the Chromium app (make it the current executable, then choose Project > Edit Active Executable).
Switch to the Arguments tab and press the '+' button under the arguments list
Type '--single-process' in the list.

From now on Chromium will launch in single-process mode when invoked through this Xcode project, and the debugger will work fine. This obviously changes the apps behavior slightly, but for most purposes the differences aren't significant. If they are, though, you'll need to…

(b) or, Attach Xcode's debugger to a renderer process after launch

1. Launch the main executable from the Terminal (not through Xcode) and pass in the --renderer-startup-dialog flag on the command line. On macOS this causes the renderer to print a message with its PID and then call pause() immediately up on startup. This has the effect of pausing execution of the renderer until the process receives a signal (such as attaching the debugger).

e.g.
$ ~/dev/chrome//src/xcodebuild/Debug/Chromium.app/Contents/MacOS/Chromium --renderer-startup-dialog

[33215:2055:244180145280185:WARNING:/Users/Shared/bla/chrome/src/chrome/renderer/renderer_main.cc(48)] Renderer (33215) paused waiting for debugger to attach @ pid

So 33215 is the PID of the renderer process in question.

2. Open chrome.xcodeproj in Xcode and select Run -> Attach To Process -> Process ID ..

Debugging out-of-process tests:

Similar to debugging the renderer process, simply attaching gdb to a out-of-process test like browser_tests will not hit the test code. In order to debug a browser test, you need to run the test binary with '--single_process' (note the underscore in single_process). Because you can only run one browser test in the same process, you're probably going to need to add --gtest_filter as well. So your command will look like this:

/path/to/src/xcodebuild/Debug/browser_tests --single_process --gtest_filter=GoatTeleporterTest.DontTeleportSheep

UI Debugging

For UI Debugging, F-Script Anywhere is very useful. Read https://sites.google.com/a/chromium.org/dev/developers/f-script-anywhere for more information.

Building with Ninja, Debugging with Xcode

Temporarily disabling the Sandbox

Disabling the sandbox can sometimes be useful when debugging, this can be achieved by passing the --no-sandbox flag on the command line. This will, for example, allow writing out debugging information to a file from the Renderer Process.

e.g.
$ ~/dev/chrome//src/xcodebuild/Debug/Chromium.app/Contents/MacOS/Chromium --no-sandbox

Tips on Debugging the Renderer Sandbox

Launch chrome with the --enable-sandbox-logging flag. This will cause a message to be printed to /var/log/system.log every time an operation is denied by the Sandbox (you can use Console.app to watch logfiles). This is really useful for debugging and can often provide an explanation for very puzzling problems.

You can also get the Sandbox to send a SIGSTOP to a process when the sandbox denies functionality. This allows you to attach with a debugger and continue the execution from where it left off:

$ sandbox-exec -p '(version 1) (allow default) (deny file-write* (regex 'foo') (with send-signal SIGSTOP))' touch foo

Breakpoints Not Getting Hit in gdb

If a breakpoint you set isn't causing the debugger to stop, try one of these solutions:

Uncheck 'Load symbols lazily' In the Xcode->Preferences->Debugging dialog.
Manually insert a call to Debugger() in the code, this will forcefully break into the Debugger.

Debugging in Release Mode

Preserving symbols in Release builds

Profiling tools like Shark and 'sample' expect to find symbol names in the binary, but in Release builds most symbols are stripped out. You can preserve symbols by temporarily changing the build process, by adding mac_strip_release=0 to your GYP_DEFINES, rerunning gclient runhooks, and rebuilding (changing this define only relinks the main binary, it doesn't recompile everything).

(The above 'Debugging in Release Mode' trick with the .dSYM file might work for Shark/sample too; I haven't tried it yet. —snej)

Using DTrace

jgm's awesome introductory article:
http://www.mactech.com/articles/mactech/Vol.23/23.11/ExploringLeopardwithDTrace/index.html
Defining static probes on macOS:
http://www.macresearch.org/tuning-cocoa-applications-using-dtrace-custom-static-probes-and-instruments
http://www.brendangregg.com/dtrace.html#Examples
http://blogs.sun.com/bmc/resource/dtrace_tips.pdf
DTrace examples on macOS: /usr/share/examples/DTTk
To get truss on macOS, use dtruss. That requires root, so I often sudo dtruss -p and attach to a running nonroot program.

Testing other locales

To test Chrome in a different locale, change your system locale via the System Preferences. (Keep the preferences window open so that you can change the locale back without needing to navigate through menus in a language you may not know.)

Memory/Heap Inspection

There are several low-level command-line tools that can be used to inspect what's going on with memory inside a process.

'heap' summarizes what's currently in the malloc heap(s) of a process. (It only works with regular malloc, of course, but Mac Chrome still uses that.) It shows a number of useful things:

How much of the heap is used or free
The distribution of block sizes
A listing of every C++, Objective-C and CoreFoundation class found in the heap, with the number of instances, total size and average size.

It identifies C++ objects by their vtables, so it can't identify vtable-less classes, including a lot of the lower-level WebCore ones like StringImpl. To work around this I temporarily added the 'virtual' keyword to WebCore::RefCounted's destructor method, which forces every ref-counted object to include a vtable pointer identifying its class.
'malloc_history' identifies the stack backtrace that allocated every malloc block in the heap. It lists every unique backtrace together with its number of blocks and their total size. It requires that the process use malloc stack logging, which is enabled if the environment variable MallocStackLogging is set when it launches. The 'env' command is handy for this:

$ env MallocStackLogging=1 Chromium.app/Contents/MacOS/Chromium

Then in another shell you run

$ malloc_history pid -all_by_size

Watch out: the output is big. I ran malloc_history on a fairly bloated heap and got 60MB of text.
'leaks' finds malloc blocks that have no pointers to them and are probably leaked. It doesn't require MallocStackLogging, but it's more useful if it's on because it can then show the backtrace that allocated each leaked block. (So far I've seen only trivial leakage in Chrome.)
'vmmap' shows all the virtual-memory regions in the process's address space. This is less useful since it doesn't say anything about individual malloc blocks (except huge ones) but it can be useful for looking at things like static data size, mapped files, and how much memory is paged out. I recommend the '-resident' flag, which shows how much of each allocation is currently paged into RAM. See the man page for details.

Notes:

These are not going to be very useful on stripped binaries, and they're less useful in release builds.
All of these except vmmap take several minutes to run, apparently because of the number of symbols in Chrome. They spend most of their time pegging one CPU down inside system code that's reading symbol tables from the binary. Be patient.
There are GUI apps in /Developer that do a lot of the same things, such as Instruments, MallocDebug and Shark. I (snej) personally find the command-line tools easier to understand, but YMMV.

Working with minidumps

CrMallocErrorBreak

If you are looking at a crash report that ends in CrMallocErrorBreak, then either a malloc or free call has failed with the given stacktrace. Chromium overrides the empty function malloc_error_break in macOS's Libc with CrMallocErrorBreak. The system calls this function as a debugging aide that we've made fatal because it catches useful memory errors. Specifically, CrMallocErrorBreak will be called (resulting in a crash) under the following circumstances:

Attempting to free a pointer that was not allocated.
Attempting to free the same pointer more than once.
Freeing a pointer of size 0.
Freeing an unaligned pointer.
An internal checksum of the object being freed does not match. This usually indicates heap corruption!
Invalid checksums on the small or tiny free list. The system maintains a list of small allocations that it reuses to speed up things like allocations in a loop. A checksum mismatch usually indicates a use-after-free, double-free, or heap corruption.
Extra-large allocation failures. Normally all failures to allocate go through CrMallocErrorBreak but are not fatal because that is the job of Chromium's OOM killer. Extra-large allocations go through a different path and are sometimes killed here instead.

If you get a crash report that that ends in CrMallocErrorBreak, it is likely not an issue with this feature. It is instead surfacing a (sometimes serious) bug in your code or other code that is stomping on your code's memory. Using Chromium's memory tools (ASan, HeapCheck, and Valgrind) is a good start, if you can reproduce the problem.

Enabling high-DPI (aka 'HiDPI' or 'Retina') modes on standard-DPI hardware.

Under macOS 10.7 and above it's possible to fake 'HiDPI' modes on standard-DPI hardware. This can be useful in testing up-scaling codepaths or high-DPI resources.

Configure the OS to offer HiDPI modes:

EITHER follow Apple's instructions to enable high resolution modes:http://developer.apple.com/library/mac/#documentation/GraphicsAnimation/Conceptual/HighResolutionOSX/Testing/Testing.html.
OR run the command-line: sudo defaults write /Library/Preferences/com.apple.windowserver DisplayResolutionEnabled -bool YES

Open the System Preferences -> Displays panel, select Scaled mode and scroll to the bottom to see modes marked '(HiDPI)'.

Looking for gdb? It's been replaced with lldb. Use that it instead.

Taking CPU Samples

A quick and easy way to investigate slow or hung processes is to use the sample facility, which will generate a CPU sample trace. This can be done either in the Terminal with the sample(1) command or by using Activity Monitor:

Open Activity Monitor
Find the process you want to sample (for 'Helper' processes, you may want to consult the Chrome Task Manager)
Double-click on the row
Click the Sample button in the process's information window

After a few seconds, the sample will be completed. For official Google Chrome builds, the sample should be symbolized using crsym. If you do not have access to crsym, save the entire contents as a file and attach it to a bug report for later analysis.