generic-library/breakpad
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Fix the Linux Starter Guide docs

Browse Source 
The auto-conversion from googlecode wiki format apparently wasn't perfect.
This also fixes up some of the links to point to the new Breakpad repo.

R=vapier@chromium.org
BUG=

Review URL: https://codereview.chromium.org/1823583002 .
This commit is contained in:
Ted Mielczarek 2016-03-22 14:03:09 -04:00
parent ebba1800e4
commit 85b27e4a69
1 changed files with 52 additions and 39 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
docs/linux_starter_guide.md
View File

@ -14,76 +14,85 @@ necessary to produce minidumps from an application.
First, configure your build process to link **libbreakpad\_client.a** into your First, configure your build process to link **libbreakpad\_client.a** into your
binary, and set your include paths to include the **src** directory in the binary, and set your include paths to include the **src** directory in the
**google-breakpad** source tree. Next, include the exception handler header: ``` **google-breakpad** source tree. Next, include the exception handler header:
# include "client/linux/handler/exception_handler.h"
```cpp
#include "client/linux/handler/exception_handler.h"
``` ```
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: 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:
```
```cpp
static bool dumpCallback(const google_breakpad::MinidumpDescriptor& descriptor, static bool dumpCallback(const google_breakpad::MinidumpDescriptor& descriptor,
void* context, bool succeeded) { printf("Dump path: %s\n", descriptor.path()); void* context, bool succeeded) {
return succeeded; } printf("Dump path: %s\n", descriptor.path());
return succeeded;
}
void crash() { volatile int* a = (int*)(NULL); *a = 1; } void crash() { volatile int* a = (int*)(NULL); *a = 1; }
int main(int argc, char* argv[]) { google_breakpad::MinidumpDescriptor int main(int argc, char* argv[]) {
descriptor("/tmp"); google_breakpad::ExceptionHandler eh(descriptor, NULL, google_breakpad::MinidumpDescriptor descriptor("/tmp");
dumpCallback, NULL, true, -1); crash(); return 0; } ``` google_breakpad::ExceptionHandler eh(descriptor, NULL, dumpCallback, NULL, true, -1);
crash();
return 0;
}
```
Compiling and running this example should produce a minidump file in /tmp, and Compiling and running this example should produce a minidump file in /tmp, and
it should print the minidump filename before exiting. You can read more about it should print the minidump filename before exiting. You can read more about
the other parameters to the `ExceptionHandler` constructor <a the other parameters to the `ExceptionHandler` constructor [in the exception_handler.h source file][1].
href='http://code.google.com/p/google-breakpad/source/browse/trunk/src/client/linux/handler/exception_handler.h'>in
the exception_handler.h source file</a>. [1]: https://chromium.googlesource.com/breakpad/breakpad/+/master/src/client/linux/handler/exception_handler.h
**Note**: You should do as little work as possible in the callback function. **Note**: You should do as little work as possible in the callback function.
Your application is in an unsafe state. It may not be safe to allocate memory or Your application is in an unsafe state. It may not be safe to allocate memory or
call functions from other shared libraries. The safest thing to do is `fork` and call functions from other shared libraries. The safest thing to do is `fork` and
`exec` a new process to do any work you need to do. If you must do some work in `exec` a new process to do any work you need to do. If you must do some work in
the callback, the Breakpad source contains <a the callback, the Breakpad source contains [some simple reimplementations of libc functions][2], to avoid calling directly into
href='http://code.google.com/p/google-breakpad/source/browse/trunk/src/common/linux/linux_libc_support.h'>some 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.
simple reimplementations of libc functions</a>, to avoid calling directly into
libc, as well as <a href='http://code.google.com/p/linux-syscall-support/'>a [2]: https://chromium.googlesource.com/breakpad/breakpad/+/master/src/common/linux/linux_libc_support.h
header file for making Linux system calls</a> (in **src/third\_party/lss**) to [3]: https://chromium.googlesource.com/linux-syscall-support/+/master
avoid calling into other shared libraries.
## Sending the minidump file ## Sending the minidump file
In a real application, you would want to handle the minidump in some way, likely In a real application, you would want to handle the minidump in some way, likely
by sending it to a server for analysis. The Breakpad source tree contains <a by sending it to a server for analysis. The Breakpad source tree contains [some
href='http://code.google.com/p/google-breakpad/source/browse/#svn/trunk/src/common/linux'>some HTTP upload source][4] that you might find useful, as well as [a minidump upload tool][5].
HTTP upload source</a> that you might find useful, as well as <a
href='http://code.google.com/p/google-breakpad/source/browse/#svn/trunk/src/tools/linux/symupload'>a [4]: https://chromium.googlesource.com/breakpad/breakpad/+/master/src/common/linux/http_upload.h
minidump upload tool</a>. [5]: https://chromium.googlesource.com/breakpad/breakpad/+/master/src/tools/linux/symupload/minidump_upload.cc
## Producing symbols for your application ## Producing symbols for your application
To produce useful stack traces, Breakpad requires you to convert the debugging To produce useful stack traces, Breakpad requires you to convert the debugging
symbols in your binaries to <a symbols in your binaries to [text-format symbol files][6]. First, ensure that you've compiled your binaries with `-g` to
href='http://code.google.com/p/google-breakpad/wiki/SymbolFiles'>text-format
symbol files</a>. First, ensure that you've compiled your binaries with `-g` to
include debugging symbols. Next, compile the `dump_syms` tool by running include debugging symbols. Next, compile the `dump_syms` tool by running
`configure && make` in the Breakpad source directory. Next, run `dump_syms` on `configure && make` in the Breakpad source directory. Next, run `dump_syms` on
your binaries to produce the text-format symbols. For example, if your main your binaries to produce the text-format symbols. For example, if your main
binary was named `test`: `$ google-breakpad/src/tools/linux/dump_syms/dump_syms binary was named `test`:
./test > test.sym
` [6]: https://chromium.googlesource.com/breakpad/breakpad/+/master/docs/symbol_files.md
```
$ google-breakpad/src/tools/linux/dump_syms/dump_syms ./test > test.sym
```
In order to use these symbols with the `minidump_stackwalk` tool, you will need In order to use these symbols with the `minidump_stackwalk` tool, you will need
to place them in a specific directory structure. The first line of the symbol to place them in a specific directory structure. The first line of the symbol
file contains the information you need to produce this directory structure, for file contains the information you need to produce this directory structure, for
example (your output will vary): `$ head -n1 test.sym MODULE Linux x86_64 example (your output will vary):
6EDC6ACDB282125843FD59DA9C81BD830 test $ mkdir -p
./symbols/test/6EDC6ACDB282125843FD59DA9C81BD830 $ mv test.sym
./symbols/test/6EDC6ACDB282125843FD59DA9C81BD830
`
You may also find the <a ```
href='http://mxr.mozilla.org/mozilla-central/source/toolkit/crashreporter/tools/symbolstore.py'>symbolstore.py</a> $ head -n1 test.sym MODULE Linux x86_64 6EDC6ACDB282125843FD59DA9C81BD830 test
script in the Mozilla repository useful, as it encapsulates these steps. $ mkdir -p ./symbols/test/6EDC6ACDB282125843FD59DA9C81BD830
$ mv test.sym ./symbols/test/6EDC6ACDB282125843FD59DA9C81BD830
```
You may also find the [symbolstore.py][7] script in the Mozilla repository useful, as it encapsulates these steps.
[7]: https://dxr.mozilla.org/mozilla-central/source/toolkit/crashreporter/tools/symbolstore.py
## Processing the minidump to produce a stack trace ## Processing the minidump to produce a stack trace
@ -92,6 +101,10 @@ plus its corresponding text-format symbols and produce a symbolized stacktrace.
It should be in the **google-breakpad/src/processor** directory if you compiled It should be in the **google-breakpad/src/processor** directory if you compiled
the Breakpad source using the directions above. Simply pass it the minidump and the Breakpad source using the directions above. Simply pass it the minidump and
the symbol path as commandline parameters: the symbol path as commandline parameters:
`google-breakpad/src/processor/minidump_stackwalk minidump.dmp ./symbols
` It produces verbose output on stderr, and the stacktrace on stdout, so you may ```
$ google-breakpad/src/processor/minidump_stackwalk minidump.dmp ./symbols
```
It produces verbose output on stderr, and the stacktrace on stdout, so you may
want to redirect stderr. want to redirect stderr.