1# How To Add Breakpad To Your Linux Application 2 3This document is an overview of using the Breakpad client libraries on Linux. 4 5## Building the Breakpad libraries 6 7Breakpad provides an Autotools build system that will build both the Linux 8client libraries and the processor libraries. Running `./configure && make` in 9the Breakpad source directory will produce 10**src/client/linux/libbreakpad\_client.a**, which contains all the code 11necessary to produce minidumps from an application. 12 13## Integrating Breakpad into your Application 14 15First, configure your build process to link **libbreakpad\_client.a** into your 16binary, 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 23Now 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 26static bool dumpCallback(const google_breakpad::MinidumpDescriptor& descriptor, 27void* context, bool succeeded) { 28 printf("Dump path: %s\n", descriptor.path()); 29 return succeeded; 30} 31 32void crash() { volatile int* a = (int*)(NULL); *a = 1; } 33 34int 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 42Compiling and running this example should produce a minidump file in /tmp, and 43it should print the minidump filename before exiting. You can read more about 44the 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. 49Your application is in an unsafe state. It may not be safe to allocate memory or 50call 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 52the callback, the Breakpad source contains [some simple reimplementations of libc functions][2], to avoid calling directly into 53libc, 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 60In a real application, you would want to handle the minidump in some way, likely 61by sending it to a server for analysis. The Breakpad source tree contains [some 62HTTP 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 69To produce useful stack traces, Breakpad requires you to convert the debugging 70symbols in your binaries to [text-format symbol files][6]. First, ensure that you've compiled your binaries with `-g` to 71include debugging symbols. Next, compile the `dump_syms` tool by running 72`configure && make` in the Breakpad source directory. Next, run `dump_syms` on 73your binaries to produce the text-format symbols. For example, if your main 74binary 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 82In order to use these symbols with the `minidump_stackwalk` tool, you will need 83to place them in a specific directory structure. The first line of the symbol 84file contains the information you need to produce this directory structure, for 85example (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 93You 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 99Breakpad includes a tool called `minidump_stackwalk` which can take a minidump 100plus its corresponding text-format symbols and produce a symbolized stacktrace. 101It should be in the **google-breakpad/src/processor** directory if you compiled 102the Breakpad source using the directions above. Simply pass it the minidump and 103the symbol path as commandline parameters: 104 105``` 106$ google-breakpad/src/processor/minidump_stackwalk minidump.dmp ./symbols 107``` 108 109It produces verbose output on stderr, and the stacktrace on stdout, so you may 110want to redirect stderr. 111