Mercurial > sdl-ios-xcode

annotate README.android @ 5225:1fbe1c202501

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Renamed SDL_Key to SDL_Keycode to clarify terminology.
author Sam Lantinga <slouken@libsdl.org>
date Mon, 07 Feb 2011 10:40:21 -0800
parents 3811132c584f
children
rev   line source
4727
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
1 ================================================================================
4726
9076cdb027af Cleanups.
Paul Hunkin <paul@bieh.net>
parents: 4725
diff changeset
2 Simple DirectMedia Layer for Android
4727
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
3 ================================================================================
4725
4eb9d3c7fdd2 Added initial README.android
Paul Hunkin <paul@bieh.net>
parents:
diff changeset
4
4965
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
5 Requirements:
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
6
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
7 Android SDK
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
8 http://developer.android.com/sdk/index.html
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
9
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
10 Android NDK r4 or later
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
11 http://developer.android.com/sdk/ndk/index.html
4725
4eb9d3c7fdd2 Added initial README.android
Paul Hunkin <paul@bieh.net>
parents:
diff changeset
12
4967
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
13
4727
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
14 ================================================================================
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
15 How the port works
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
16 ================================================================================
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
17
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
18 - Android applications are Java-based, optionally with parts written in C
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
19 - As SDL apps are C-based, we use a small Java shim that uses JNI to talk to
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
20 the SDL library
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
21 - This means that your application C code must be placed inside an android
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
22 Java project, along with some C support code that communicates with Java
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
23 - This eventually produces a standard Android .apk package
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
24
4967
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
25 The Android Java code implements an "activity" and can be found in:
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
26 android-project/src/org/libsdl/app/SDLActivity.java
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
27
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
28 The Java code loads your game code, the SDL shared library, and
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
29 dispatches to native functions implemented in the SDL library:
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
30 src/SDL_android.cpp
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
31
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
32 Your project must include some glue code that starts your main() routine:
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
33 src/main/android/SDL_android_main.cpp
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
34
4727
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
35
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
36 ================================================================================
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
37 Building an app
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
38 ================================================================================
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
39
4725
4eb9d3c7fdd2 Added initial README.android
Paul Hunkin <paul@bieh.net>
parents:
diff changeset
40 Instructions:
4965
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
41 1. Copy the android-project directory wherever you want to keep your projects and rename it to the name of your project.
4964
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
42 2. Move this SDL directory into the <project>/jni directory
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
43 3. Place your application source files in the <project>/jni/src directory
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
44 4. Edit <project>/jni/src/Android.mk to include your source files
4727
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
45 5. Run 'ndk-build' (a script provided by the NDK). This compiles the C source
4964
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
46
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
47 If you want to use the Eclipse IDE, skip to the Eclipse section below.
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
48
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
49 6. Edit <project>/local.properties to point to the Android SDK directory
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
50 7. Run 'ant debug' in android/project. This compiles the .java and eventually
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
51 creates a .apk with the native code embedded
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
52 8. 'ant install' will push the apk to the device or emulator (if connected)
4725
4eb9d3c7fdd2 Added initial README.android
Paul Hunkin <paul@bieh.net>
parents:
diff changeset
53
4965
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
54 Here's an explanation of the files in the Android project, so you can customize them:
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
55
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
56 android-project/
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
57 AndroidManifest.xml - package manifest, do not modify
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
58 build.properties - empty
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
59 build.xml - build description file, used by ant
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
60 default.properties - holds the ABI for the application, currently android-4 which corresponds to the Android 1.6 system image
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
61 local.properties - holds the SDK path, you should change this to the path to your SDK
4967
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
62 jni/ - directory holding native code
4965
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
63 jni/Android.mk - Android makefile that includes all subdirectories
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
64 jni/SDL/ - directory holding the SDL library files
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
65 jni/SDL/Android.mk - Android makefile for creating the SDL shared library
4967
f74a3f94c408 Added some more information on how the port works
Sam Lantinga <slouken@libsdl.org>
parents: 4965
diff changeset
66 jni/src/ - directory holding your C/C++ source
4965
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
67 jni/src/Android.mk - Android makefile that you should customize to include your source code and any library references
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
68 res/ - directory holding resources for your application
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
69 res/drawable-* - directories holding icons for different phone hardware
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
70 res/layout/main.xml - place holder for the main screen layout, overridden by the SDL video output
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
71 res/values/strings.xml - strings used in your application, including the application name shown on the phone.
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
72 src/org/libsdl/app/SDLActivity.java - the Java class handling the initialization and binding to SDL. Be very careful changing this, as the SDL library relies on this implementation.
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
73
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
74
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
75 ================================================================================
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
76 Additional documentation
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
77 ================================================================================
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
78
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
79 The documentation in the NDK docs directory is very helpful in understanding the build process and how to work with native code on the Android platform.
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
80
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
81 The best place to start is with docs/OVERVIEW.TXT
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
82
4725
4eb9d3c7fdd2 Added initial README.android
Paul Hunkin <paul@bieh.net>
parents:
diff changeset
83
4964
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
84 ================================================================================
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
85 Using Eclipse
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
86 ================================================================================
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
87
4965
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
88 First make sure that you've installed Eclipse and the Android extensions as described here:
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
89 http://developer.android.com/sdk/eclipse-adt.html
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
90
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
91 Once you've copied the SDL android project and customized it, you can create an Eclipse project from it:
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
92 * File -> New -> Other
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
93 * Select the Android -> Android Project wizard and click Next
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
94 * Enter the name you'd like your project to have
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
95 * Select "Create project from existing source" and browse for your project directory
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
96 * Make sure the Build Target is set to Android 1.6
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
97 * Click Finish
4964
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
98
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
99
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
100 ================================================================================
4965
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
101 Loading files and resources
4964
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
102 ================================================================================
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
103
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
104 NEED CONTENT
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
105
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
106
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
107 ================================================================================
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
108 Troubleshooting
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
109 ================================================================================
6c645018741e Build the SDL library as a shared object on Android, so it will work correctly with SDL_image and SDL_ttf.
Sam Lantinga <slouken@libsdl.org>
parents: 4954
diff changeset
110
4965
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
111 You can create and run an emulator from the Eclipse IDE:
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
112 * Window -> Android SDK and AVD Manager
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
113
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
114 You can see if adb can see any devices with the following command:
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
115 adb devices
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
116
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
117 You can see the output of log messages on the default device with:
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
118 adb logcat
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
119
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
120 You can push files to the device with:
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
121 adb push local_file remote_path_and_file
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
122
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
123 You can push files to the SD Card at /sdcard, for example:
91d0085b7560 Added the Android project and lots of info to README.android
Sam Lantinga <slouken@libsdl.org>
parents: 4964
diff changeset
124 adb push moose.dat /sdcard/moose.dat
4727
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
125
4976
3811132c584f Added information about starting a command shell on the device
Sam Lantinga <slouken@libsdl.org>
parents: 4975
diff changeset
126 You can see the files on the SD card with a shell command:
3811132c584f Added information about starting a command shell on the device
Sam Lantinga <slouken@libsdl.org>
parents: 4975
diff changeset
127 adb shell ls /sdcard/
3811132c584f Added information about starting a command shell on the device
Sam Lantinga <slouken@libsdl.org>
parents: 4975
diff changeset
128
3811132c584f Added information about starting a command shell on the device
Sam Lantinga <slouken@libsdl.org>
parents: 4975
diff changeset
129 You can start a command shell on the default device with:
3811132c584f Added information about starting a command shell on the device
Sam Lantinga <slouken@libsdl.org>
parents: 4975
diff changeset
130 adb shell
3811132c584f Added information about starting a command shell on the device
Sam Lantinga <slouken@libsdl.org>
parents: 4975
diff changeset
131
4975
6fbc7044f343 Added information about doing a clean build
Sam Lantinga <slouken@libsdl.org>
parents: 4974
diff changeset
132 You can do a clean build with the following commands:
6fbc7044f343 Added information about doing a clean build
Sam Lantinga <slouken@libsdl.org>
parents: 4974
diff changeset
133 ndk-build clean
6fbc7044f343 Added information about doing a clean build
Sam Lantinga <slouken@libsdl.org>
parents: 4974
diff changeset
134 ndk-build
6fbc7044f343 Added information about doing a clean build
Sam Lantinga <slouken@libsdl.org>
parents: 4974
diff changeset
135
4973
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
136 You can see the complete command line that ndk-build is using by passing V=1 on the command line:
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
137 ndk-build V=1
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
138
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
139 If your application crashes in native code, you can use addr2line to convert the addresses in the stack trace to lines in your code.
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
140
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
141 For example, if your crash looks like this:
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
142 I/DEBUG ( 31): signal 11 (SIGSEGV), code 2 (SEGV_ACCERR), fault addr 400085d0
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
143 I/DEBUG ( 31): r0 00000000 r1 00001000 r2 00000003 r3 400085d4
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
144 I/DEBUG ( 31): r4 400085d0 r5 40008000 r6 afd41504 r7 436c6a7c
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
145 I/DEBUG ( 31): r8 436c6b30 r9 435c6fb0 10 435c6f9c fp 4168d82c
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
146 I/DEBUG ( 31): ip 8346aff0 sp 436c6a60 lr afd1c8ff pc afd1c902 cpsr 60000030
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
147 I/DEBUG ( 31): #00 pc 0001c902 /system/lib/libc.so
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
148 I/DEBUG ( 31): #01 pc 0001ccf6 /system/lib/libc.so
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
149 I/DEBUG ( 31): #02 pc 000014bc /data/data/org.libsdl.app/lib/libmain.so
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
150 I/DEBUG ( 31): #03 pc 00001506 /data/data/org.libsdl.app/lib/libmain.so
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
151
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
152 You can see that there's a crash in the C library being called from the main code. I run addr2line with the debug version of my code:
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
153 arm-eabi-addr2line -C -f -e obj/local/armeabi/libmain.so
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
154 and then paste in the number after "pc" in the call stack, from the line that I care about:
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
155 000014bc
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
156
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
157 I get output from addr2line showing that it's in the quit function, in testspriteminimal.c, on line 23.
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
158
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
159 You can add logging to your code to help show what's happening:
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
160
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
161 #include <android/log.h>
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
162
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
163 __android_log_print(ANDROID_LOG_INFO, "foo", "Something happened! x = %d", x);
067b6ec8b751 Added information about decoding native stack traces
Sam Lantinga <slouken@libsdl.org>
parents: 4967
diff changeset
164
4974
1cd0a891b69a Added info for building your code without optimizations on
Sam Lantinga <slouken@libsdl.org>
parents: 4973
diff changeset
165 If you need to build without optimization turned on, you can create a file called "Application.mk" in the jni directory, with the following line in it:
1cd0a891b69a Added info for building your code without optimizations on
Sam Lantinga <slouken@libsdl.org>
parents: 4973
diff changeset
166 APP_OPTIM := debug
1cd0a891b69a Added info for building your code without optimizations on
Sam Lantinga <slouken@libsdl.org>
parents: 4973
diff changeset
167
4727
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
168
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
169 ================================================================================
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
170 Known issues
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
171 ================================================================================
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
172
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
173 - SDL audio (although it's mostly written, just not working properly yet)
8087bb208acf Updated the readme
Paul Hunkin <paul@bieh.net>
parents: 4726
diff changeset
174 - TODO. I'm sure there's a bunch more stuff I haven't thought of