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

4 files changed, 162 insertions, 0 deletions

diff --git a/android/sample_app/README b/android/sample_app/README
new file mode 100644
index 00000000..aa19dbb4
--- /dev/null
+++ b/android/sample_app/README
@@ -0,0 +1,32 @@
+This is a sample Android executable that can be used to test the
+Google Breakpad client library on Android.
+
+Its purpose is simply to crash and generate a minidump under /data/local/tmp.
+
+Build instructions:
+
+   cd android/sample_app
+   $NDK/ndk-build
+
+  Where $NDK points to a valid Android NDK installation.
+
+Usage instructions:
+
+   After buildind the test program, send it to a device, then run it as
+   the shell UID:
+
+     adb push libs/armeabi/test_google_breakpad /data/local/tmp
+     adb shell /data/local/tmp/test_google_breakpad
+
+   This will simply crash after dumping the name of the generated minidump
+   file.
+
+   See jni/test_breakpad.cpp for details.
+
+   Use 'armeabi-v7a' instead of 'armeabi' above to test the ARMv7-A version
+   of the binary.
+
+Note:
+   If you plan to use the library in a regular Android application, store
+   the minidump files either to your app-specific directory, or to the SDCard
+   (the latter requiring a specific permission).
diff --git a/android/sample_app/jni/Android.mk b/android/sample_app/jni/Android.mk
new file mode 100644
index 00000000..61487b52
--- /dev/null
+++ b/android/sample_app/jni/Android.mk
@@ -0,0 +1,44 @@
+# Copyright (c) 2012, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#     * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+#     * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+LOCAL_PATH := $(call my-dir)
+
+include $(CLEAR_VARS)
+LOCAL_MODULE := test_google_breakpad
+LOCAL_SRC_FILES := test_breakpad.cpp
+LOCAL_STATIC_LIBRARIES += breakpad_client
+include $(BUILD_EXECUTABLE)
+
+# If NDK_MODULE_PATH is defined, import the module, otherwise do a direct
+# includes. This allows us to build in all scenarios easily.
+ifneq ($(NDK_MODULE_PATH),)
+  $(call import-module,google_breakpad)
+else
+  include $(LOCAL_PATH)/../../google_breakpad/Android.mk
+endif
diff --git a/android/sample_app/jni/Application.mk b/android/sample_app/jni/Application.mk
new file mode 100644
index 00000000..50dcd0d5
--- /dev/null
+++ b/android/sample_app/jni/Application.mk
@@ -0,0 +1,31 @@
+# Copyright (c) 2012, Google Inc.
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+#     * Redistributions of source code must retain the above copyright
+# notice, this list of conditions and the following disclaimer.
+#     * Redistributions in binary form must reproduce the above
+# copyright notice, this list of conditions and the following disclaimer
+# in the documentation and/or other materials provided with the
+# distribution.
+#     * Neither the name of Google Inc. nor the names of its
+# contributors may be used to endorse or promote products derived from
+# this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+APP_STL := stlport_static
+APP_ABI := armeabi armeabi-v7a
diff --git a/android/sample_app/jni/test_breakpad.cpp b/android/sample_app/jni/test_breakpad.cpp
new file mode 100644
index 00000000..6c18edfb
--- /dev/null
+++ b/android/sample_app/jni/test_breakpad.cpp
@@ -0,0 +1,55 @@
+// Copyright (c) 2012, Google Inc.
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are
+// met:
+//
+//     * Redistributions of source code must retain the above copyright
+// notice, this list of conditions and the following disclaimer.
+//     * Redistributions in binary form must reproduce the above
+// copyright notice, this list of conditions and the following disclaimer
+// in the documentation and/or other materials provided with the
+// distribution.
+//     * Neither the name of Google Inc. nor the names of its
+// contributors may be used to endorse or promote products derived from
+// this software without specific prior written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+#include <stdio.h>
+
+#include "client/linux/handler/exception_handler.h"
+
+namespace {
+
+bool DumpCallback(const char* dump_path,
+                  const char* minidump_id,
+                  void* context,
+                  bool succeeded) {
+  printf("Dump path: %s/%s.dmp\n", dump_path, minidump_id);
+  return succeeded;
+}
+
+void Crash() {
+  volatile int* a = reinterpret_cast<volatile int*>(NULL);
+  *a = 1;
+}
+
+}  // namespace
+
+int main(int argc, char* argv[]) {
+  google_breakpad::ExceptionHandler eh(".", NULL, DumpCallback, NULL, true);
+  Crash();
+  return 0;
+}