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 r11c 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 https://chromium.googlesource.com/breakpad/breakpad/+/master/docs/linux_starter_guide.md 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