85b27e4a69
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 .
110 lines
5.2 KiB
Markdown
110 lines
5.2 KiB
Markdown
# How To Add Breakpad To Your Linux Application
|
|
|
|
This document is an overview of using the Breakpad client libraries on Linux.
|
|
|
|
## Building the Breakpad libraries
|
|
|
|
Breakpad provides an Autotools build system that will build both the Linux
|
|
client libraries and the processor libraries. Running `./configure && make` in
|
|
the Breakpad source directory will produce
|
|
**src/client/linux/libbreakpad\_client.a**, which contains all the code
|
|
necessary to produce minidumps from an application.
|
|
|
|
## Integrating Breakpad into your Application
|
|
|
|
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
|
|
**google-breakpad** source tree. Next, include the exception handler header:
|
|
|
|
```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:
|
|
|
|
```cpp
|
|
static bool dumpCallback(const google_breakpad::MinidumpDescriptor& descriptor,
|
|
void* context, bool succeeded) {
|
|
printf("Dump path: %s\n", descriptor.path());
|
|
return succeeded;
|
|
}
|
|
|
|
void crash() { volatile int* a = (int*)(NULL); *a = 1; }
|
|
|
|
int main(int argc, char* argv[]) {
|
|
google_breakpad::MinidumpDescriptor descriptor("/tmp");
|
|
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
|
|
it should print the minidump filename before exiting. You can read more about
|
|
the other parameters to the `ExceptionHandler` constructor [in the exception_handler.h source file][1].
|
|
|
|
[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.
|
|
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
|
|
`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 [some simple reimplementations of libc functions][2], to avoid calling directly into
|
|
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.
|
|
|
|
[2]: https://chromium.googlesource.com/breakpad/breakpad/+/master/src/common/linux/linux_libc_support.h
|
|
[3]: https://chromium.googlesource.com/linux-syscall-support/+/master
|
|
|
|
## Sending the minidump file
|
|
|
|
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 [some
|
|
HTTP upload source][4] that you might find useful, as well as [a minidump upload tool][5].
|
|
|
|
[4]: https://chromium.googlesource.com/breakpad/breakpad/+/master/src/common/linux/http_upload.h
|
|
[5]: https://chromium.googlesource.com/breakpad/breakpad/+/master/src/tools/linux/symupload/minidump_upload.cc
|
|
|
|
## Producing symbols for your application
|
|
|
|
To produce useful stack traces, Breakpad requires you to convert the debugging
|
|
symbols in your binaries to [text-format symbol files][6]. First, ensure that you've compiled your binaries with `-g` to
|
|
include debugging symbols. Next, compile the `dump_syms` tool by running
|
|
`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
|
|
binary was named `test`:
|
|
|
|
[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
|
|
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
|
|
example (your output will vary):
|
|
|
|
```
|
|
$ head -n1 test.sym MODULE Linux x86_64 6EDC6ACDB282125843FD59DA9C81BD830 test
|
|
$ 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
|
|
|
|
Breakpad includes a tool called `minidump_stackwalk` which can take a minidump
|
|
plus its corresponding text-format symbols and produce a symbolized stacktrace.
|
|
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 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
|
|
want to redirect stderr.
|