1  Google Breakpad for Android
  2  ===========================
  3  
  4  This document explains how to use the Google Breakpad client library
  5  on Android, and later generate valid stack traces from the minidumps
  6  it generates.
  7  
  8  This release supports ARM, x86 and MIPS based Android systems.
  9  This release requires NDK release r11c or higher.
 10  
 11  I. Building the client library:
 12  ===============================
 13  
 14  The Android client is built as a static library that you can
 15  link into your own Android native code. There are two ways to
 16  build it:
 17  
 18  I.1. Building with ndk-build:
 19  -----------------------------
 20  
 21  If you're using the ndk-build build system, you can follow
 22  these 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  
 34  NOTE: 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  
 40  I.2. Building with a standalone Android toolchain:
 41  --------------------------------------------------
 42  
 43  All you need to do is configure your build with the right 'host'
 44  value, 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  
 51  The library will be under src/client/linux/libbreakpad_client.a
 52  
 53  You can also use 'make check' to run the test suite on a connected
 54  Android device. This requires the Android 'adb' tool to be in your
 55  path.
 56  
 57  II. Using the client library in Android:
 58  ========================================
 59  
 60  The usage instructions are very similar to the Linux ones that are
 61  found at https://chromium.googlesource.com/breakpad/breakpad/+/master/docs/linux_starter_guide.md
 62  
 63  1/ You need to include "client/linux/handler/exception_handler.h" from a C++
 64     source file.
 65  
 66  2/ 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  
 76  3/ 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  
 82  For a concrete example, see the sample test application under
 83  android/sample_app. See its README for more information.
 84  
 85  
 86  III. Getting a stack trace on the host:
 87  =======================================
 88  
 89  This process is similar to other platforms, but here's a quick example:
 90  
 91  1/ Retrieve the minidumps on your development machine.
 92  
 93  2/ 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  
 99  3/ 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  
114  4/ Invoke minidump_stackwalk to create the stack trace:
115  
116       minidump_stackwalk $MINIDUMP_FILE $PROJECT_PATH/symbols
117  
118  Note that various helper scripts can be found on the web to automate these
119  steps.
120  
121  IV. Verifying the Android build library:
122  ========================================
123  
124  If you modify Google Breakpad and want to check that it still works correctly
125  on Android, please run the android/run-checks.sh script which will do all
126  necessary 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  
137  For more details, please run:
138  
139    android/run-checks.sh --help-all