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