| # Introduction | |
| Breakpad is a library and tool suite that allows you to distribute an | |
| application to users with compiler-provided debugging information removed, | |
| record crashes in compact "minidump" files, send them back to your server, and | |
| produce C and C++ stack traces from these minidumps. Breakpad can also write | |
| minidumps on request for programs that have not crashed. | |
| Breakpad is currently used by Google Chrome, Firefox, Google Picasa, Camino, | |
| Google Earth, and other projects. | |
|  | |
| Breakpad has three main components: | |
| * The **client** is a library that you include in your application. It can | |
| write minidump files capturing the current threads' state and the identities | |
| of the currently loaded executable and shared libraries. You can configure | |
| the client to write a minidump when a crash occurs, or when explicitly | |
| requested. | |
| * The **symbol dumper** is a program that reads the debugging information | |
| produced by the compiler and produces a **symbol file**, in [Breakpad's own | |
| format](symbol_files.md). | |
| * The **processor** is a program that reads a minidump file, finds the | |
| appropriate symbol files for the versions of the executables and shared | |
| libraries the minidump mentions, and produces a human-readable C/C++ stack | |
| trace. | |
| # The minidump file format | |
| The minidump file format is similar to core files but was developed by Microsoft | |
| for its crash-uploading facility. A minidump file contains: | |
| * A list of the executable and shared libraries that were loaded in the | |
| process at the time the dump was created. This list includes both file names | |
| and identifiers for the particular versions of those files that were loaded. | |
| * A list of threads present in the process. For each thread, the minidump | |
| includes the state of the processor registers, and the contents of the | |
| threads' stack memory. These data are uninterpreted byte streams, as the | |
| Breakpad client generally has no debugging information available to produce | |
| function names or line numbers, or even identify stack frame boundaries. | |
| * Other information about the system on which the dump was collected: | |
| processor and operating system versions, the reason for the dump, and so on. | |
| Breakpad uses Windows minidump files on all platforms, instead of the | |
| traditional core files, for several reasons: | |
| * Core files can be very large, making them impractical to send across a | |
| network to the collector for processing. Minidumps are smaller, as they were | |
| designed to be used this way. | |
| * The core file format is poorly documented. For example, the Linux Standards | |
| Base does not describe how registers are stored in `PT_NOTE` segments. | |
| * It is harder to persuade a Windows machine to produce a core dump file than | |
| it is to persuade other machines to write a minidump file. | |
| * It simplifies the Breakpad processor to support only one file format. | |
| # Overview/Life of a minidump | |
| A minidump is generated via calls into the Breakpad library. By default, | |
| initializing Breakpad installs an exception/signal handler that writes a | |
| minidump to disk at exception time. On Windows, this is done via | |
| `SetUnhandledExceptionFilter()`; on OS X, this is done by creating a thread that | |
| waits on the Mach exception port; and on Linux, this is done by installing a | |
| signal handler for various exceptions like `SIGILL, SIGSEGV` etc. | |
| Once the minidump is generated, each platform has a slightly different way of | |
| uploading the crash dump. On Windows & Linux, a separate library of functions is | |
| provided that can be called into to do the upload. On OS X, a separate process | |
| is spawned that prompts the user for permission, if configured to do so, and | |
| sends the file. | |
| # Terminology | |
| **In-process vs. out-of-process exception handling** - it's generally considered | |
| that writing the minidump from within the crashed process is unsafe - key | |
| process data structures could be corrupted, or the stack on which the exception | |
| handler runs could have been overwritten, etc. All 3 platforms support what's | |
| known as "out-of-process" exception handling. | |
| # Integration overview | |
| ## Breakpad Code Overview | |
| All the client-side code is found by visiting the Google Project at | |
| https://chromium.googlesource.com/breakpad/breakpad. The following directory structure is | |
| present in the `src` directory: | |
| * `processor` Contains minidump-processing code that is used on the server | |
| side and isn't of use on the client side | |
| * `client` Contains client minidump-generation libraries for all platforms | |
| * `tools` Contains source code & projects for building various tools on each | |
| platform. | |
| (Among other directories) | |
| * [Windows Integration Guide](windows_client_integration.md) | |
| * [Mac Integration Guide](mac_breakpad_starter_guide.md) | |
| * [Linux Integration Guide](linux_starter_guide.md) | |
| ## Build process specifics(symbol generation) | |
| This applies to all platforms. Inside `src/tools/{platform}/dump_syms` is a tool | |
| that can read debugging information for each platform (e.g. for OS X/Linux, | |
| DWARF and STABS, and for Windows, PDB files) and generate a Breakpad symbol | |
| file. This tool should be run on your binary before it's stripped(in the case of | |
| OS X/Linux) and the symbol files need to be stored somewhere that the minidump | |
| processor can find. There is another tool, `symupload`, that can be used to | |
| upload symbol files if you have written a server that can accept them. |