The Tor Browser / file comparison
comparison: toolkit/crashreporter/google-breakpad/README.ANDROID
toolkit/crashreporter/google-breakpad/README.ANDROID
- branch
- TOR_BUG_3246
- changeset 7
- 129ffea94266
equal
deleted
inserted
replaced
| -1:000000000000 | 0:073e3b017cd9 |
|---|---|
| 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 and x86 based Android systems. MIPS is not | |
| 9 currently supported by Breakpad. | |
| 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 II.1. 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 http://code.google.com/p/google-breakpad/wiki/LinuxStarterGuide | |
| 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 |
