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

1 files changed, 134 insertions, 0 deletions

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