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