1# Introduction 2 3Breakpad is a library and tool suite that allows you to distribute an 4application to users with compiler-provided debugging information removed, 5record crashes in compact "minidump" files, send them back to your server, and 6produce C and C++ stack traces from these minidumps. Breakpad can also write 7minidumps on request for programs that have not crashed. 8 9Breakpad is currently used by Google Chrome, Firefox, Google Picasa, Camino, 10Google Earth, and other projects. 11 12 13 14Breakpad has three main components: 15 16* The **client** is a library that you include in your application. It can 17 write minidump files capturing the current threads' state and the identities 18 of the currently loaded executable and shared libraries. You can configure 19 the client to write a minidump when a crash occurs, or when explicitly 20 requested. 21 22* The **symbol dumper** is a program that reads the debugging information 23 produced by the compiler and produces a **symbol file**, in [Breakpad's own 24 format](symbol_files.md). 25 26* The **processor** is a program that reads a minidump file, finds the 27 appropriate symbol files for the versions of the executables and shared 28 libraries the minidump mentions, and produces a human-readable C/C++ stack 29 trace. 30 31# The minidump file format 32 33The minidump file format is similar to core files but was developed by Microsoft 34for its crash-uploading facility. A minidump file contains: 35 36* A list of the executable and shared libraries that were loaded in the 37 process at the time the dump was created. This list includes both file names 38 and identifiers for the particular versions of those files that were loaded. 39 40* A list of threads present in the process. For each thread, the minidump 41 includes the state of the processor registers, and the contents of the 42 threads' stack memory. These data are uninterpreted byte streams, as the 43 Breakpad client generally has no debugging information available to produce 44 function names or line numbers, or even identify stack frame boundaries. 45 46* Other information about the system on which the dump was collected: 47 processor and operating system versions, the reason for the dump, and so on. 48 49Breakpad uses Windows minidump files on all platforms, instead of the 50traditional core files, for several reasons: 51 52* Core files can be very large, making them impractical to send across a 53 network to the collector for processing. Minidumps are smaller, as they were 54 designed to be used this way. 55 56* The core file format is poorly documented. For example, the Linux Standards 57 Base does not describe how registers are stored in `PT_NOTE` segments. 58 59* It is harder to persuade a Windows machine to produce a core dump file than 60 it is to persuade other machines to write a minidump file. 61 62* It simplifies the Breakpad processor to support only one file format. 63 64# Overview/Life of a minidump 65 66A minidump is generated via calls into the Breakpad library. By default, 67initializing Breakpad installs an exception/signal handler that writes a 68minidump to disk at exception time. On Windows, this is done via 69`SetUnhandledExceptionFilter()`; on OS X, this is done by creating a thread that 70waits on the Mach exception port; and on Linux, this is done by installing a 71signal handler for various exceptions like `SIGILL, SIGSEGV` etc. 72 73Once the minidump is generated, each platform has a slightly different way of 74uploading the crash dump. On Windows & Linux, a separate library of functions is 75provided that can be called into to do the upload. On OS X, a separate process 76is spawned that prompts the user for permission, if configured to do so, and 77sends the file. 78 79# Terminology 80 81**In-process vs. out-of-process exception handling** - it's generally considered 82that writing the minidump from within the crashed process is unsafe - key 83process data structures could be corrupted, or the stack on which the exception 84handler runs could have been overwritten, etc. All 3 platforms support what's 85known as "out-of-process" exception handling. 86 87# Integration overview 88 89## Breakpad Code Overview 90 91All the client-side code is found by visiting the Google Project at 92https://chromium.googlesource.com/breakpad/breakpad. The following directory structure is 93present in the `src` directory: 94 95* `processor` Contains minidump-processing code that is used on the server 96 side and isn't of use on the client side 97* `client` Contains client minidump-generation libraries for all platforms 98* `tools` Contains source code & projects for building various tools on each 99 platform. 100 101(Among other directories) 102 103* [Windows Integration Guide](windows_client_integration.md) 104* [Mac Integration Guide](mac_breakpad_starter_guide.md) 105* [Linux Integration Guide](linux_starter_guide.md) 106 107## Build process specifics(symbol generation) 108 109This applies to all platforms. Inside `src/tools/{platform}/dump_syms` is a tool 110that can read debugging information for each platform (e.g. for OS X/Linux, 111DWARF and STABS, and for Windows, PDB files) and generate a Breakpad symbol 112file. This tool should be run on your binary before it's stripped(in the case of 113OS X/Linux) and the symbol files need to be stored somewhere that the minidump 114processor can find. There is another tool, `symupload`, that can be used to 115upload symbol files if you have written a server that can accept them. 116
