1  # How To Add Breakpad To Your Linux Application
  2  
  3  This document is an overview of using the Breakpad client libraries on Linux.
  4  
  5  ## Building the Breakpad libraries
  6  
  7  Breakpad provides an Autotools build system that will build both the Linux
  8  client libraries and the processor libraries. Running `./configure && make` in
  9  the Breakpad source directory will produce
 10  **src/client/linux/libbreakpad\_client.a**, which contains all the code
 11  necessary to produce minidumps from an application.
 12  
 13  ## Integrating Breakpad into your Application
 14  
 15  First, configure your build process to link **libbreakpad\_client.a** into your
 16  binary, and set your include paths to include the **src** directory in the
 17  **google-breakpad** source tree. Next, include the exception handler header:
 18  
 19  ```cpp
 20  #include "client/linux/handler/exception_handler.h"
 21  ```
 22  
 23  Now you can instantiate an `ExceptionHandler` object. Exception handling is active for the lifetime of the `ExceptionHandler` object, so you should instantiate it as early as possible in your application's startup process, and keep it alive for as close to shutdown as possible. To do anything useful, the `ExceptionHandler` constructor requires a path where it can write minidumps, as well as a callback function to receive information about minidumps that were written:
 24  
 25  ```cpp
 26  static bool dumpCallback(const google_breakpad::MinidumpDescriptor& descriptor,
 27  void* context, bool succeeded) {
 28    printf("Dump path: %s\n", descriptor.path());
 29    return succeeded;
 30  }
 31  
 32  void crash() { volatile int* a = (int*)(NULL); *a = 1; }
 33  
 34  int main(int argc, char* argv[]) {
 35    google_breakpad::MinidumpDescriptor descriptor("/tmp");
 36    google_breakpad::ExceptionHandler eh(descriptor, NULL, dumpCallback, NULL, true, -1);
 37    crash();
 38    return 0;
 39  }
 40  ```
 41  
 42  Compiling and running this example should produce a minidump file in /tmp, and
 43  it should print the minidump filename before exiting. You can read more about
 44  the other parameters to the `ExceptionHandler` constructor [in the exception_handler.h source file][1].
 45  
 46  [1]: https://chromium.googlesource.com/breakpad/breakpad/+/master/src/client/linux/handler/exception_handler.h
 47  
 48  **Note**: You should do as little work as possible in the callback function.
 49  Your application is in an unsafe state. It may not be safe to allocate memory or
 50  call functions from other shared libraries. The safest thing to do is `fork` and
 51  `exec` a new process to do any work you need to do. If you must do some work in
 52  the callback, the Breakpad source contains [some simple reimplementations of libc functions][2], to avoid calling directly into
 53  libc, as well as [a header file for making Linux system calls][3] (in **src/third\_party/lss**) to avoid calling into other shared libraries.
 54  
 55  [2]: https://chromium.googlesource.com/breakpad/breakpad/+/master/src/common/linux/linux_libc_support.h
 56  [3]: https://chromium.googlesource.com/linux-syscall-support/+/master
 57  
 58  ## Sending the minidump file
 59  
 60  In a real application, you would want to handle the minidump in some way, likely
 61  by sending it to a server for analysis. The Breakpad source tree contains [some
 62  HTTP upload source][4] that you might find useful, as well as [a minidump upload tool][5].
 63  
 64  [4]: https://chromium.googlesource.com/breakpad/breakpad/+/master/src/common/linux/http_upload.h
 65  [5]: https://chromium.googlesource.com/breakpad/breakpad/+/master/src/tools/linux/symupload/minidump_upload.cc
 66  
 67  ## Producing symbols for your application
 68  
 69  To produce useful stack traces, Breakpad requires you to convert the debugging
 70  symbols in your binaries to [text-format symbol files][6]. First, ensure that you've compiled your binaries with `-g` to
 71  include debugging symbols. Next, compile the `dump_syms` tool by running
 72  `configure && make` in the Breakpad source directory. Next, run `dump_syms` on
 73  your binaries to produce the text-format symbols. For example, if your main
 74  binary was named `test`:
 75  
 76  [6]: https://chromium.googlesource.com/breakpad/breakpad/+/master/docs/symbol_files.md
 77  
 78  ```
 79  $ google-breakpad/src/tools/linux/dump_syms/dump_syms ./test > test.sym
 80  ```
 81  
 82  In order to use these symbols with the `minidump_stackwalk` tool, you will need
 83  to place them in a specific directory structure. The first line of the symbol
 84  file contains the information you need to produce this directory structure, for
 85  example (your output will vary):
 86  
 87  ```
 88  $ head -n1 test.sym MODULE Linux x86_64 6EDC6ACDB282125843FD59DA9C81BD830 test
 89  $ mkdir -p ./symbols/test/6EDC6ACDB282125843FD59DA9C81BD830
 90  $ mv test.sym ./symbols/test/6EDC6ACDB282125843FD59DA9C81BD830
 91  ```
 92  
 93  You may also find the [symbolstore.py][7] script in the Mozilla repository useful, as it encapsulates these steps.
 94  
 95  [7]: https://dxr.mozilla.org/mozilla-central/source/toolkit/crashreporter/tools/symbolstore.py
 96  
 97  ## Processing the minidump to produce a stack trace
 98  
 99  Breakpad includes a tool called `minidump_stackwalk` which can take a minidump
100  plus its corresponding text-format symbols and produce a symbolized stacktrace.
101  It should be in the **google-breakpad/src/processor** directory if you compiled
102  the Breakpad source using the directions above. Simply pass it the minidump and
103  the symbol path as commandline parameters:
104  
105  ```
106  $ google-breakpad/src/processor/minidump_stackwalk minidump.dmp ./symbols
107  ```
108  
109  It produces verbose output on stderr, and the stacktrace on stdout, so you may
110  want to redirect stderr.