From 0bed408b15fa3a2df0567171fa07c80618010523 Mon Sep 17 00:00:00 2001 From: "digit@chromium.org" Date: Mon, 9 Jul 2012 19:02:17 +0000 Subject: Add Android NDK module definition + sample application This patch adds a new directory named "android/" which contains the following: - A NDK build system module definition for the Google Breakpad client library. This can be used by developers using the ndk-build build system to more easily build and use the client library in their own programs. - A sample application demonstrating how to use the module, as well as test that the library works properly during a crash. - A shell script (run-checks.sh) that will check everything for you automatically, including: - Rebuilding the host Google Breakpad host package with configure/make - Rebuilding the Android client library with configure/make - Rebuilding the Android client library and test program with ndk-build - Running the crashing test program, extract minidump, dump symbols, generate a stack trace and check that it has correct source file locations. For more details, run android/run-checks.sh --help-all + Updates to the README.ANDROID documentation. Review URL: https://breakpad.appspot.com/407002 git-svn-id: http://google-breakpad.googlecode.com/svn/trunk@983 4c0a9323-5329-0410-9bdc-e9ce6186880e --- README.ANDROID | 134 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 134 insertions(+) create mode 100644 README.ANDROID (limited to 'README.ANDROID') diff --git a/README.ANDROID b/README.ANDROID new file mode 100644 index 00000000..816f57a9 --- /dev/null +++ b/README.ANDROID @@ -0,0 +1,134 @@ +Google Breakpad for Android +=========================== + +This document explains how to use the Google Breakpad client library +on Android, and later generate valid stack traces from the minidumps +it generates. + +Note that this release only supports ARM-based Android systems. +We're working on adding support for x86 and MIPS, but that might +require an udpated NDK release. + + +I. Building the client library: +=============================== + +The Android client is built as a static library that you can +link into your own Android native code. There are two ways to +build it: + +I.1. Building with ndk-build: +----------------------------- + +If you're using the ndk-build build system, you can follow +these simple steps: + + 1/ Include android/google_breakpad/Android.mk from your own + project's Android.mk + + This can be done either directly, or using ndk-build's + import-module feature. + + 2/ Link the library to one of your modules by using: + + LOCAL_STATIC_LIBRARIES += breakpad_client + +NOTE: The client library requires a C++ STL implementation, + which you can select with APP_STL in your Application.mk + + It has been tested succesfully with both STLport and GNU libstdc++ + + +II.1. Building with a standalone Android toolchain: +--------------------------------------------------- + +All you need to do is configure your build with the right 'host' +value, and disable the processor and tools, as in: + + $GOOGLE_BREAKPAD_PATH/configure --host=arm-linux-androideabi \ + --disable-processor \ + --disable-tools + make -j4 + +The library will be under src/client/linux/libbreakpad_client.a + + +II. Using the client library in Android: +======================================== + +The usage instructions are very similar to the Linux ones that are +found at http://code.google.com/p/google-breakpad/wiki/LinuxStarterGuide + +1/ You need to include "client/linux/handler/exception_handler.h" from a C++ + source file. + +2/ If you're not using ndk-build, you also need to: + + - add $GOOGLE_BREAKPAD_PATH to your compiler include path + - add -llog to your linker flags + + Note that ndk-build does that for your automatically. + +3/ Keep in mind that there is no /tmp directory on Android. + + If you use the library from a regular Android applications, specify a + path under your app-specific storage directory. An alternative is to + store them on the SDCard, but this requires a specific permission. + +For a concrete example, see the sample test application under +android/sample_app. See its README for more information. + + +III. Getting a stack trace on the host: +======================================= + +This process is similar to other platforms, but here's a quick example: + +1/ Retrieve the minidumps on your development machine. + +2/ Dump the symbols for your native libraries with the 'dump_syms' tool. + This first requires building the host version of Google Breakpad, then + calling: + + dump_syms $PROJECT_PATH/obj/local/$ABI/libfoo.so > libfoo.so.sym + +3/ Create the symbol directory hierarchy. + + The first line of the generated libfoo.so.sym will have a "MODULE" + entry that carries a hexadecimal version number, e.g.: + + MODULE Linux arm D51B4A5504974FA6ECC1869CAEE3603B0 test_google_breakpad + + Note: The second field could be either 'Linux' or 'Android'. + + Extract the version number, and a 'symbol' directory, for example: + + $PROJECT_PATH/symbols/libfoo.so/$VERSION/ + + Copy/Move your libfoo.sym file there. + +4/ Invoke minidump_stackwalk to create the stack trace: + + minidump_stackwalk $MINIDUMP_FILE $PROJECT_PATH/symbols + +Note that various helper scripts can be found on the web to automate these +steps. + +IV. Verifying the Android build library: +======================================== + +If you modify Google Breakpad and want to check that it still works correctly +on Android, please run the android/run-test-program.sh script which will do all +necessary verifications for you. This includes: + + - Rebuilding the full host package + - Rebuilding the client library with configure/make + - Rebuilding the client library with ndk-build + - Building, installing and running a test crasher program on a device + - Extracting the corresponding minidump, dumping the test program symbols + and generating a stack trace. + - Checking the stack trace for valid source locations. + +For more details, please run: + + android/run-test-program.sh --help-all -- cgit v1.2.1