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