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  ![Workflow](breakpad.png)
 13  
 14  Breakpad 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  
 33  The minidump file format is similar to core files but was developed by Microsoft
 34  for 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  
 49  Breakpad uses Windows minidump files on all platforms, instead of the
 50  traditional 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  
 66  A minidump is generated via calls into the Breakpad library. By default,
 67  initializing Breakpad installs an exception/signal handler that writes a
 68  minidump to disk at exception time. On Windows, this is done via
 69  `SetUnhandledExceptionFilter()`; on OS X, this is done by creating a thread that
 70  waits on the Mach exception port; and on Linux, this is done by installing a
 71  signal handler for various exceptions like `SIGILL, SIGSEGV` etc.
 72  
 73  Once the minidump is generated, each platform has a slightly different way of
 74  uploading the crash dump. On Windows & Linux, a separate library of functions is
 75  provided that can be called into to do the upload. On OS X, a separate process
 76  is spawned that prompts the user for permission, if configured to do so, and
 77  sends the file.
 78  
 79  # Terminology
 80  
 81  **In-process vs. out-of-process exception handling** - it's generally considered
 82  that writing the minidump from within the crashed process is unsafe - key
 83  process data structures could be corrupted, or the stack on which the exception
 84  handler runs could have been overwritten, etc. All 3 platforms support what's
 85  known as "out-of-process" exception handling.
 86  
 87  # Integration overview
 88  
 89  ## Breakpad Code Overview
 90  
 91  All the client-side code is found by visiting the Google Project at
 92  https://chromium.googlesource.com/breakpad/breakpad. The following directory structure is
 93  present 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  
109  This applies to all platforms. Inside `src/tools/{platform}/dump_syms` is a tool
110  that can read debugging information for each platform (e.g. for OS X/Linux,
111  DWARF and STABS, and for Windows, PDB files) and generate a Breakpad symbol
112  file. This tool should be run on your binary before it's stripped(in the case of
113  OS X/Linux) and the symbol files need to be stored somewhere that the minidump
114  processor can find. There is another tool, `symupload`, that can be used to
115  upload symbol files if you have written a server that can accept them.