diff options
Diffstat (limited to 'externals/breakpad/docs/getting_started_with_breakpad.md')
| -rw-r--r-- | externals/breakpad/docs/getting_started_with_breakpad.md | 115 |
1 files changed, 0 insertions, 115 deletions
diff --git a/externals/breakpad/docs/getting_started_with_breakpad.md b/externals/breakpad/docs/getting_started_with_breakpad.md deleted file mode 100644 index b827d401f3..0000000000 --- a/externals/breakpad/docs/getting_started_with_breakpad.md +++ /dev/null @@ -1,115 +0,0 @@ -# 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. |