michael@0: Google Breakpad for Android michael@0: =========================== michael@0: michael@0: This document explains how to use the Google Breakpad client library michael@0: on Android, and later generate valid stack traces from the minidumps michael@0: it generates. michael@0: michael@0: This release supports ARM and x86 based Android systems. MIPS is not michael@0: currently supported by Breakpad. michael@0: michael@0: I. Building the client library: michael@0: =============================== michael@0: michael@0: The Android client is built as a static library that you can michael@0: link into your own Android native code. There are two ways to michael@0: build it: michael@0: michael@0: I.1. Building with ndk-build: michael@0: ----------------------------- michael@0: michael@0: If you're using the ndk-build build system, you can follow michael@0: these simple steps: michael@0: michael@0: 1/ Include android/google_breakpad/Android.mk from your own michael@0: project's Android.mk michael@0: michael@0: This can be done either directly, or using ndk-build's michael@0: import-module feature. michael@0: michael@0: 2/ Link the library to one of your modules by using: michael@0: michael@0: LOCAL_STATIC_LIBRARIES += breakpad_client michael@0: michael@0: NOTE: The client library requires a C++ STL implementation, michael@0: which you can select with APP_STL in your Application.mk michael@0: michael@0: It has been tested succesfully with both STLport and GNU libstdc++ michael@0: michael@0: michael@0: II.1. Building with a standalone Android toolchain: michael@0: --------------------------------------------------- michael@0: michael@0: All you need to do is configure your build with the right 'host' michael@0: value, and disable the processor and tools, as in: michael@0: michael@0: $GOOGLE_BREAKPAD_PATH/configure --host=arm-linux-androideabi \ michael@0: --disable-processor \ michael@0: --disable-tools michael@0: make -j4 michael@0: michael@0: The library will be under src/client/linux/libbreakpad_client.a michael@0: michael@0: You can also use 'make check' to run the test suite on a connected michael@0: Android device. This requires the Android 'adb' tool to be in your michael@0: path. michael@0: michael@0: II. Using the client library in Android: michael@0: ======================================== michael@0: michael@0: The usage instructions are very similar to the Linux ones that are michael@0: found at http://code.google.com/p/google-breakpad/wiki/LinuxStarterGuide michael@0: michael@0: 1/ You need to include "client/linux/handler/exception_handler.h" from a C++ michael@0: source file. michael@0: michael@0: 2/ If you're not using ndk-build, you also need to: michael@0: michael@0: - add the following to your compiler include search paths: michael@0: $GOOGLE_BREAKPAD_PATH/src michael@0: $GOOGLE_BREAKPAD_PATH/src/common/android/include michael@0: michael@0: - add -llog to your linker flags michael@0: michael@0: Note that ndk-build does that for your automatically. michael@0: michael@0: 3/ Keep in mind that there is no /tmp directory on Android. michael@0: michael@0: If you use the library from a regular Android applications, specify a michael@0: path under your app-specific storage directory. An alternative is to michael@0: store them on the SDCard, but this requires a specific permission. michael@0: michael@0: For a concrete example, see the sample test application under michael@0: android/sample_app. See its README for more information. michael@0: michael@0: michael@0: III. Getting a stack trace on the host: michael@0: ======================================= michael@0: michael@0: This process is similar to other platforms, but here's a quick example: michael@0: michael@0: 1/ Retrieve the minidumps on your development machine. michael@0: michael@0: 2/ Dump the symbols for your native libraries with the 'dump_syms' tool. michael@0: This first requires building the host version of Google Breakpad, then michael@0: calling: michael@0: michael@0: dump_syms $PROJECT_PATH/obj/local/$ABI/libfoo.so > libfoo.so.sym michael@0: michael@0: 3/ Create the symbol directory hierarchy. michael@0: michael@0: The first line of the generated libfoo.so.sym will have a "MODULE" michael@0: entry that carries a hexadecimal version number, e.g.: michael@0: michael@0: MODULE Linux arm D51B4A5504974FA6ECC1869CAEE3603B0 test_google_breakpad michael@0: michael@0: Note: The second field could be either 'Linux' or 'Android'. michael@0: michael@0: Extract the version number, and a 'symbol' directory, for example: michael@0: michael@0: $PROJECT_PATH/symbols/libfoo.so/$VERSION/ michael@0: michael@0: Copy/Move your libfoo.sym file there. michael@0: michael@0: 4/ Invoke minidump_stackwalk to create the stack trace: michael@0: michael@0: minidump_stackwalk $MINIDUMP_FILE $PROJECT_PATH/symbols michael@0: michael@0: Note that various helper scripts can be found on the web to automate these michael@0: steps. michael@0: michael@0: IV. Verifying the Android build library: michael@0: ======================================== michael@0: michael@0: If you modify Google Breakpad and want to check that it still works correctly michael@0: on Android, please run the android/run-checks.sh script which will do all michael@0: necessary verifications for you. This includes: michael@0: michael@0: - Rebuilding the full host binaries. michael@0: - Rebuilding the full Android binaries with configure/make. michael@0: - Rebuilding the client library unit tests, and running them on a device. michael@0: - Rebuilding the client library with ndk-build. michael@0: - Building, installing and running a test crasher program on a device. michael@0: - Extracting the corresponding minidump, dumping the test program symbols michael@0: and generating a stack trace. michael@0: - Checking the generated stack trace for valid source locations. michael@0: michael@0: For more details, please run: michael@0: michael@0: android/run-checks.sh --help-all