← Back to branch summary

~imalinovskiy/rdm/0.8

« back to all changes in this revision

Viewing changes to 3rdparty/gbreakpad/README.ANDROID

  • Committer: RDM Bot
  • Date: 2016-02-04 11:29:17 UTC
  • Revision ID: git-v1:92436de8ed24fe0a57651f4a61caba27995ad55b
Pull updates from https://github.com/uglide/RedisDesktopManager

Show diffs side-by-side

added added

removed removed

Lines of Context:
3rdparty/gbreakpad/README.ANDROID
 
1
Google Breakpad for Android
 
2
===========================
 
3
 
 
4
This document explains how to use the Google Breakpad client library
 
5
on Android, and later generate valid stack traces from the minidumps
 
6
it generates.
 
7
 
 
8
This release supports ARM, x86 and MIPS based Android systems.
 
9
This release requires NDK release r10c or higher.
 
10
 
 
11
I. Building the client library:
 
12
===============================
 
13
 
 
14
The Android client is built as a static library that you can
 
15
link into your own Android native code. There are two ways to
 
16
build it:
 
17
 
 
18
I.1. Building with ndk-build:
 
19
-----------------------------
 
20
 
 
21
If you're using the ndk-build build system, you can follow
 
22
these simple steps:
 
23
 
 
24
  1/ Include android/google_breakpad/Android.mk from your own
 
25
     project's Android.mk
 
26
 
 
27
     This can be done either directly, or using ndk-build's
 
28
     import-module feature.
 
29
 
 
30
  2/ Link the library to one of your modules by using:
 
31
 
 
32
     LOCAL_STATIC_LIBRARIES += breakpad_client
 
33
 
 
34
NOTE: The client library requires a C++ STL implementation,
 
35
      which you can select with APP_STL in your Application.mk
 
36
 
 
37
      It has been tested succesfully with both STLport and GNU libstdc++
 
38
 
 
39
 
 
40
I.2. Building with a standalone Android toolchain:
 
41
--------------------------------------------------
 
42
 
 
43
All you need to do is configure your build with the right 'host'
 
44
value, and disable the processor and tools, as in:
 
45
 
 
46
  $GOOGLE_BREAKPAD_PATH/configure --host=arm-linux-androideabi \
 
47
                                  --disable-processor \
 
48
                                  --disable-tools
 
49
  make -j4
 
50
 
 
51
The library will be under src/client/linux/libbreakpad_client.a
 
52
 
 
53
You can also use 'make check' to run the test suite on a connected
 
54
Android device. This requires the Android 'adb' tool to be in your
 
55
path.
 
56
 
 
57
II. Using the client library in Android:
 
58
========================================
 
59
 
 
60
The usage instructions are very similar to the Linux ones that are
 
61
found at http://code.google.com/p/google-breakpad/wiki/LinuxStarterGuide
 
62
 
 
63
1/ You need to include "client/linux/handler/exception_handler.h" from a C++
 
64
   source file.
 
65
 
 
66
2/ If you're not using ndk-build, you also need to:
 
67
 
 
68
   - add the following to your compiler include search paths:
 
69
       $GOOGLE_BREAKPAD_PATH/src
 
70
       $GOOGLE_BREAKPAD_PATH/src/common/android/include
 
71
 
 
72
   - add -llog to your linker flags
 
73
 
 
74
   Note that ndk-build does that for your automatically.
 
75
 
 
76
3/ Keep in mind that there is no /tmp directory on Android.
 
77
 
 
78
   If you use the library from a regular Android applications, specify a
 
79
   path under your app-specific storage directory. An alternative is to
 
80
   store them on the SDCard, but this requires a specific permission.
 
81
 
 
82
For a concrete example, see the sample test application under
 
83
android/sample_app. See its README for more information.
 
84
 
 
85
 
 
86
III. Getting a stack trace on the host:
 
87
=======================================
 
88
 
 
89
This process is similar to other platforms, but here's a quick example:
 
90
 
 
91
1/ Retrieve the minidumps on your development machine.
 
92
 
 
93
2/ Dump the symbols for your native libraries with the 'dump_syms' tool.
 
94
   This first requires building the host version of Google Breakpad, then
 
95
   calling:
 
96
 
 
97
      dump_syms $PROJECT_PATH/obj/local/$ABI/libfoo.so > libfoo.so.sym
 
98
 
 
99
3/ Create the symbol directory hierarchy.
 
100
 
 
101
   The first line of the generated libfoo.so.sym will have a "MODULE"
 
102
   entry that carries a hexadecimal version number, e.g.:
 
103
 
 
104
     MODULE Linux arm D51B4A5504974FA6ECC1869CAEE3603B0 test_google_breakpad
 
105
 
 
106
   Note: The second field could be either 'Linux' or 'Android'.
 
107
 
 
108
   Extract the version number, and a 'symbol' directory, for example:
 
109
 
 
110
      $PROJECT_PATH/symbols/libfoo.so/$VERSION/
 
111
 
 
112
   Copy/Move your libfoo.sym file there.
 
113
 
 
114
4/ Invoke minidump_stackwalk to create the stack trace:
 
115
 
 
116
     minidump_stackwalk $MINIDUMP_FILE $PROJECT_PATH/symbols
 
117
 
 
118
Note that various helper scripts can be found on the web to automate these
 
119
steps.
 
120
 
 
121
IV. Verifying the Android build library:
 
122
========================================
 
123
 
 
124
If you modify Google Breakpad and want to check that it still works correctly
 
125
on Android, please run the android/run-checks.sh script which will do all
 
126
necessary verifications for you. This includes:
 
127
 
 
128
  - Rebuilding the full host binaries.
 
129
  - Rebuilding the full Android binaries with configure/make.
 
130
  - Rebuilding the client library unit tests, and running them on a device.
 
131
  - Rebuilding the client library with ndk-build.
 
132
  - Building, installing and running a test crasher program on a device.
 
133
  - Extracting the corresponding minidump, dumping the test program symbols
 
134
    and generating a stack trace.
 
135
  - Checking the generated stack trace for valid source locations.
 
136
 
 
137
For more details, please run:
 
138
 
 
139
  android/run-checks.sh --help-all