1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/toolkit/crashreporter/google-breakpad/README.ANDROID Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,139 @@
1.4 +Google Breakpad for Android
1.5 +===========================
1.6 +
1.7 +This document explains how to use the Google Breakpad client library
1.8 +on Android, and later generate valid stack traces from the minidumps
1.9 +it generates.
1.10 +
1.11 +This release supports ARM and x86 based Android systems. MIPS is not
1.12 +currently supported by Breakpad.
1.13 +
1.14 +I. Building the client library:
1.15 +===============================
1.16 +
1.17 +The Android client is built as a static library that you can
1.18 +link into your own Android native code. There are two ways to
1.19 +build it:
1.20 +
1.21 +I.1. Building with ndk-build:
1.22 +-----------------------------
1.23 +
1.24 +If you're using the ndk-build build system, you can follow
1.25 +these simple steps:
1.26 +
1.27 + 1/ Include android/google_breakpad/Android.mk from your own
1.28 + project's Android.mk
1.29 +
1.30 + This can be done either directly, or using ndk-build's
1.31 + import-module feature.
1.32 +
1.33 + 2/ Link the library to one of your modules by using:
1.34 +
1.35 + LOCAL_STATIC_LIBRARIES += breakpad_client
1.36 +
1.37 +NOTE: The client library requires a C++ STL implementation,
1.38 + which you can select with APP_STL in your Application.mk
1.39 +
1.40 + It has been tested succesfully with both STLport and GNU libstdc++
1.41 +
1.42 +
1.43 +II.1. Building with a standalone Android toolchain:
1.44 +---------------------------------------------------
1.45 +
1.46 +All you need to do is configure your build with the right 'host'
1.47 +value, and disable the processor and tools, as in:
1.48 +
1.49 + $GOOGLE_BREAKPAD_PATH/configure --host=arm-linux-androideabi \
1.50 + --disable-processor \
1.51 + --disable-tools
1.52 + make -j4
1.53 +
1.54 +The library will be under src/client/linux/libbreakpad_client.a
1.55 +
1.56 +You can also use 'make check' to run the test suite on a connected
1.57 +Android device. This requires the Android 'adb' tool to be in your
1.58 +path.
1.59 +
1.60 +II. Using the client library in Android:
1.61 +========================================
1.62 +
1.63 +The usage instructions are very similar to the Linux ones that are
1.64 +found at http://code.google.com/p/google-breakpad/wiki/LinuxStarterGuide
1.65 +
1.66 +1/ You need to include "client/linux/handler/exception_handler.h" from a C++
1.67 + source file.
1.68 +
1.69 +2/ If you're not using ndk-build, you also need to:
1.70 +
1.71 + - add the following to your compiler include search paths:
1.72 + $GOOGLE_BREAKPAD_PATH/src
1.73 + $GOOGLE_BREAKPAD_PATH/src/common/android/include
1.74 +
1.75 + - add -llog to your linker flags
1.76 +
1.77 + Note that ndk-build does that for your automatically.
1.78 +
1.79 +3/ Keep in mind that there is no /tmp directory on Android.
1.80 +
1.81 + If you use the library from a regular Android applications, specify a
1.82 + path under your app-specific storage directory. An alternative is to
1.83 + store them on the SDCard, but this requires a specific permission.
1.84 +
1.85 +For a concrete example, see the sample test application under
1.86 +android/sample_app. See its README for more information.
1.87 +
1.88 +
1.89 +III. Getting a stack trace on the host:
1.90 +=======================================
1.91 +
1.92 +This process is similar to other platforms, but here's a quick example:
1.93 +
1.94 +1/ Retrieve the minidumps on your development machine.
1.95 +
1.96 +2/ Dump the symbols for your native libraries with the 'dump_syms' tool.
1.97 + This first requires building the host version of Google Breakpad, then
1.98 + calling:
1.99 +
1.100 + dump_syms $PROJECT_PATH/obj/local/$ABI/libfoo.so > libfoo.so.sym
1.101 +
1.102 +3/ Create the symbol directory hierarchy.
1.103 +
1.104 + The first line of the generated libfoo.so.sym will have a "MODULE"
1.105 + entry that carries a hexadecimal version number, e.g.:
1.106 +
1.107 + MODULE Linux arm D51B4A5504974FA6ECC1869CAEE3603B0 test_google_breakpad
1.108 +
1.109 + Note: The second field could be either 'Linux' or 'Android'.
1.110 +
1.111 + Extract the version number, and a 'symbol' directory, for example:
1.112 +
1.113 + $PROJECT_PATH/symbols/libfoo.so/$VERSION/
1.114 +
1.115 + Copy/Move your libfoo.sym file there.
1.116 +
1.117 +4/ Invoke minidump_stackwalk to create the stack trace:
1.118 +
1.119 + minidump_stackwalk $MINIDUMP_FILE $PROJECT_PATH/symbols
1.120 +
1.121 +Note that various helper scripts can be found on the web to automate these
1.122 +steps.
1.123 +
1.124 +IV. Verifying the Android build library:
1.125 +========================================
1.126 +
1.127 +If you modify Google Breakpad and want to check that it still works correctly
1.128 +on Android, please run the android/run-checks.sh script which will do all
1.129 +necessary verifications for you. This includes:
1.130 +
1.131 + - Rebuilding the full host binaries.
1.132 + - Rebuilding the full Android binaries with configure/make.
1.133 + - Rebuilding the client library unit tests, and running them on a device.
1.134 + - Rebuilding the client library with ndk-build.
1.135 + - Building, installing and running a test crasher program on a device.
1.136 + - Extracting the corresponding minidump, dumping the test program symbols
1.137 + and generating a stack trace.
1.138 + - Checking the generated stack trace for valid source locations.
1.139 +
1.140 +For more details, please run:
1.141 +
1.142 + android/run-checks.sh --help-all
