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