getting_started_with_breakpad.md

# 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.

![Workflow](breakpad.png)

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.