Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(62)

Side by Side Diff: docs/linux_starter_guide.md

Issue 1823583002: Fix the Linux Starter Guide docs (Closed) Base URL: https://chromium.googlesource.com/breakpad/breakpad.git@master
Patch Set: Created 4 years, 9 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
« no previous file with comments | « no previous file | no next file » | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
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.
OLDNEW
« no previous file with comments | « no previous file | no next file » | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698