OLD | NEW |
(Empty) | |
| 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 # include "client/linux/handler/exception_handler.h" |
| 20 |
| 21 ``` |
| 22 |
| 23 Now you can instantiate an `ExceptionHandler` object. Exception handling is acti
ve 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 `ExceptionHand
ler` constructor requires a path where it can write minidumps, as well as a call
back function to receive information about minidumps that were written: |
| 24 ``` |
| 25 |
| 26 static bool dumpCallback(const google_breakpad::MinidumpDescriptor& descriptor, |
| 27 void* context, bool succeeded) { printf("Dump path: %s\n", descriptor.path()); |
| 28 return succeeded; } |
| 29 |
| 30 void crash() { volatile int* a = (int*)(NULL); *a = 1; } |
| 31 |
| 32 int main(int argc, char* argv[]) { google_breakpad::MinidumpDescriptor |
| 33 descriptor("/tmp"); google_breakpad::ExceptionHandler eh(descriptor, NULL, |
| 34 dumpCallback, NULL, true, -1); crash(); return 0; } ``` |
| 35 |
| 36 Compiling and running this example should produce a minidump file in /tmp, and |
| 37 it should print the minidump filename before exiting. You can read more about |
| 38 the other parameters to the `ExceptionHandler` constructor <a |
| 39 href='http://code.google.com/p/google-breakpad/source/browse/trunk/src/client/li
nux/handler/exception_handler.h'>in |
| 40 the exception_handler.h source file</a>. |
| 41 |
| 42 **Note**: You should do as little work as possible in the callback function. |
| 43 Your application is in an unsafe state. It may not be safe to allocate memory or |
| 44 call functions from other shared libraries. The safest thing to do is `fork` and |
| 45 `exec` a new process to do any work you need to do. If you must do some work in |
| 46 the callback, the Breakpad source contains <a |
| 47 href='http://code.google.com/p/google-breakpad/source/browse/trunk/src/common/li
nux/linux_libc_support.h'>some |
| 48 simple reimplementations of libc functions</a>, to avoid calling directly into |
| 49 libc, as well as <a href='http://code.google.com/p/linux-syscall-support/'>a |
| 50 header file for making Linux system calls</a> (in **src/third\_party/lss**) to |
| 51 avoid calling into other shared libraries. |
| 52 |
| 53 ## Sending the minidump file |
| 54 |
| 55 In a real application, you would want to handle the minidump in some way, likely |
| 56 by sending it to a server for analysis. The Breakpad source tree contains <a |
| 57 href='http://code.google.com/p/google-breakpad/source/browse/#svn/trunk/src/comm
on/linux'>some |
| 58 HTTP upload source</a> that you might find useful, as well as <a |
| 59 href='http://code.google.com/p/google-breakpad/source/browse/#svn/trunk/src/tool
s/linux/symupload'>a |
| 60 minidump upload tool</a>. |
| 61 |
| 62 ## Producing symbols for your application |
| 63 |
| 64 To produce useful stack traces, Breakpad requires you to convert the debugging |
| 65 symbols in your binaries to <a |
| 66 href='http://code.google.com/p/google-breakpad/wiki/SymbolFiles'>text-format |
| 67 symbol files</a>. First, ensure that you've compiled your binaries with `-g` to |
| 68 include debugging symbols. Next, compile the `dump_syms` tool by running |
| 69 `configure && make` in the Breakpad source directory. Next, run `dump_syms` on |
| 70 your binaries to produce the text-format symbols. For example, if your main |
| 71 binary was named `test`: `$ google-breakpad/src/tools/linux/dump_syms/dump_syms |
| 72 ./test > test.sym |
| 73 ` |
| 74 |
| 75 In order to use these symbols with the `minidump_stackwalk` tool, you will need |
| 76 to place them in a specific directory structure. The first line of the symbol |
| 77 file contains the information you need to produce this directory structure, for |
| 78 example (your output will vary): `$ head -n1 test.sym MODULE Linux x86_64 |
| 79 6EDC6ACDB282125843FD59DA9C81BD830 test $ mkdir -p |
| 80 ./symbols/test/6EDC6ACDB282125843FD59DA9C81BD830 $ mv test.sym |
| 81 ./symbols/test/6EDC6ACDB282125843FD59DA9C81BD830 |
| 82 ` |
| 83 |
| 84 You may also find the <a |
| 85 href='http://mxr.mozilla.org/mozilla-central/source/toolkit/crashreporter/tools/
symbolstore.py'>symbolstore.py</a> |
| 86 script in the Mozilla repository useful, as it encapsulates these steps. |
| 87 |
| 88 ## Processing the minidump to produce a stack trace |
| 89 |
| 90 Breakpad includes a tool called `minidump_stackwalk` which can take a minidump |
| 91 plus its corresponding text-format symbols and produce a symbolized stacktrace. |
| 92 It should be in the **google-breakpad/src/processor** directory if you compiled |
| 93 the Breakpad source using the directions above. Simply pass it the minidump and |
| 94 the symbol path as commandline parameters: |
| 95 `google-breakpad/src/processor/minidump_stackwalk minidump.dmp ./symbols |
| 96 ` It produces verbose output on stderr, and the stacktrace on stdout, so you may |
| 97 want to redirect stderr. |
OLD | NEW |