1Google Breakpad for Android
2===========================
3
4This document explains how to use the Google Breakpad client library
5on Android, and later generate valid stack traces from the minidumps
6it generates.
7
8This release supports ARM, x86 and MIPS based Android systems.
9This release requires NDK release r10c or higher.
10
11I. Building the client library:
12===============================
13
14The Android client is built as a static library that you can
15link into your own Android native code. There are two ways to
16build it:
17
18I.1. Building with ndk-build:
19-----------------------------
20
21If you're using the ndk-build build system, you can follow
22these simple steps:
23
24  1/ Include android/google_breakpad/Android.mk from your own
25     project's Android.mk
26
27     This can be done either directly, or using ndk-build's
28     import-module feature.
29
30  2/ Link the library to one of your modules by using:
31
32     LOCAL_STATIC_LIBRARIES += breakpad_client
33
34NOTE: The client library requires a C++ STL implementation,
35      which you can select with APP_STL in your Application.mk
36
37      It has been tested succesfully with both STLport and GNU libstdc++
38
39
40I.2. Building with a standalone Android toolchain:
41--------------------------------------------------
42
43All you need to do is configure your build with the right 'host'
44value, and disable the processor and tools, as in:
45
46  $GOOGLE_BREAKPAD_PATH/configure --host=arm-linux-androideabi \
47                                  --disable-processor \
48                                  --disable-tools
49  make -j4
50
51The library will be under src/client/linux/libbreakpad_client.a
52
53You can also use 'make check' to run the test suite on a connected
54Android device. This requires the Android 'adb' tool to be in your
55path.
56
57II. Using the client library in Android:
58========================================
59
60The usage instructions are very similar to the Linux ones that are
61found at http://code.google.com/p/google-breakpad/wiki/LinuxStarterGuide
62
631/ You need to include "client/linux/handler/exception_handler.h" from a C++
64   source file.
65
662/ If you're not using ndk-build, you also need to:
67
68   - add the following to your compiler include search paths:
69       $GOOGLE_BREAKPAD_PATH/src
70       $GOOGLE_BREAKPAD_PATH/src/common/android/include
71
72   - add -llog to your linker flags
73
74   Note that ndk-build does that for your automatically.
75
763/ Keep in mind that there is no /tmp directory on Android.
77
78   If you use the library from a regular Android applications, specify a
79   path under your app-specific storage directory. An alternative is to
80   store them on the SDCard, but this requires a specific permission.
81
82For a concrete example, see the sample test application under
83android/sample_app. See its README for more information.
84
85
86III. Getting a stack trace on the host:
87=======================================
88
89This process is similar to other platforms, but here's a quick example:
90
911/ Retrieve the minidumps on your development machine.
92
932/ Dump the symbols for your native libraries with the 'dump_syms' tool.
94   This first requires building the host version of Google Breakpad, then
95   calling:
96
97      dump_syms $PROJECT_PATH/obj/local/$ABI/libfoo.so > libfoo.so.sym
98
993/ Create the symbol directory hierarchy.
100
101   The first line of the generated libfoo.so.sym will have a "MODULE"
102   entry that carries a hexadecimal version number, e.g.:
103
104     MODULE Linux arm D51B4A5504974FA6ECC1869CAEE3603B0 test_google_breakpad
105
106   Note: The second field could be either 'Linux' or 'Android'.
107
108   Extract the version number, and a 'symbol' directory, for example:
109
110      $PROJECT_PATH/symbols/libfoo.so/$VERSION/
111
112   Copy/Move your libfoo.sym file there.
113
1144/ Invoke minidump_stackwalk to create the stack trace:
115
116     minidump_stackwalk $MINIDUMP_FILE $PROJECT_PATH/symbols
117
118Note that various helper scripts can be found on the web to automate these
119steps.
120
121IV. Verifying the Android build library:
122========================================
123
124If you modify Google Breakpad and want to check that it still works correctly
125on Android, please run the android/run-checks.sh script which will do all
126necessary verifications for you. This includes:
127
128  - Rebuilding the full host binaries.
129  - Rebuilding the full Android binaries with configure/make.
130  - Rebuilding the client library unit tests, and running them on a device.
131  - Rebuilding the client library with ndk-build.
132  - Building, installing and running a test crasher program on a device.
133  - Extracting the corresponding minidump, dumping the test program symbols
134    and generating a stack trace.
135  - Checking the generated stack trace for valid source locations.
136
137For more details, please run:
138
139  android/run-checks.sh --help-all
140