README.android
changeset 6678 afb9be20f8d2
parent 6664 2deb17aefbaf
child 6816 b3d3ef1e15b5
equal deleted inserted replaced
6677:c3202c29e352 6678:afb9be20f8d2
    36 ================================================================================
    36 ================================================================================
    37  Building an app
    37  Building an app
    38 ================================================================================
    38 ================================================================================
    39 
    39 
    40 Instructions:
    40 Instructions:
    41 1. Copy the android-project directory wherever you want to keep your projects and rename it to the name of your project.
    41 1. Copy the android-project directory wherever you want to keep your projects
       
    42    and rename it to the name of your project.
    42 2. Move or symlink this SDL directory into the <project>/jni directory
    43 2. Move or symlink this SDL directory into the <project>/jni directory
    43 3. Edit <project>/jni/src/Android.mk to include your source files
    44 3. Edit <project>/jni/src/Android.mk to include your source files
    44 4. Run 'ndk-build' (a script provided by the NDK). This compiles the C source
    45 4. Run 'ndk-build' (a script provided by the NDK). This compiles the C source
    45 
    46 
    46 If you want to use the Eclipse IDE, skip to the Eclipse section below.
    47 If you want to use the Eclipse IDE, skip to the Eclipse section below.
    47 
    48 
    48 5. Edit <project>/local.properties to point to the Android SDK directory
    49 5. Edit <project>/local.properties to point to the Android SDK directory
    49 6. Run 'ant debug' in android/project. This compiles the .java and eventually 
    50 6. Run 'ant debug' in android/project. This compiles the .java and eventually 
    50 creates a .apk with the native code embedded
    51    creates a .apk with the native code embedded
    51 7. 'ant debug install' will push the apk to the device or emulator (if connected)
    52 7. 'ant debug install' will push the apk to the device or emulator (if connected)
    52 
    53 
    53 Here's an explanation of the files in the Android project, so you can customize them:
    54 Here's an explanation of the files in the Android project, so you can customize them:
    54 
    55 
    55 android-project/
    56 android-project/
    56 	AndroidManifest.xml	- package manifest, customize this for your app
    57 	AndroidManifest.xml	- package manifest. Among others, it contains the class name
       
    58 				  of the main activity.
    57 	build.properties	- empty
    59 	build.properties	- empty
    58 	build.xml		- build description file, used by ant
    60 	build.xml		- build description file, used by ant. The actual application name
    59 	default.properties	- holds the ABI for the application, currently android-5 which corresponds to the Android 2.0 system image
    61 				  is specified here.
       
    62 	default.properties	- holds the target ABI for the application, can range between
       
    63 				  android-5 and android-16
    60 	local.properties	- holds the SDK path, you should change this to the path to your SDK
    64 	local.properties	- holds the SDK path, you should change this to the path to your SDK
    61 	jni/			- directory holding native code
    65 	jni/			- directory holding native code
    62 	jni/Android.mk		- Android makefile that includes all subdirectories
    66 	jni/Android.mk		- Android makefile that can call recursively the Android.mk files
    63 	jni/SDL/		- directory holding the SDL library files
    67 				  in all subdirectories
       
    68 	jni/SDL/		- (symlink to) directory holding the SDL library files
    64 	jni/SDL/Android.mk	- Android makefile for creating the SDL shared library
    69 	jni/SDL/Android.mk	- Android makefile for creating the SDL shared library
    65 	jni/src/		- directory holding your C/C++ source
    70 	jni/src/		- directory holding your C/C++ source
    66 	jni/src/Android.mk	- Android makefile that you should customize to include your source code and any library references
    71 	jni/src/Android.mk	- Android makefile that you should customize to include your 
       
    72                                   source code and any library references
    67 	res/			- directory holding resources for your application
    73 	res/			- directory holding resources for your application
    68 	res/drawable-*		- directories holding icons for different phone hardware
    74 	res/drawable-*		- directories holding icons for different phone hardware. Could be
    69 	res/layout/main.xml	- place holder for the main screen layout, overridden by the SDL video output
    75 				  one dir called "drawable".
    70 	res/values/strings.xml	- strings used in your application, including the application name shown on the phone.
    76 	res/layout/main.xml	- Usually contains a file main.xml, which declares the screen layout.
    71 	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.
    77 				  We don't need it because we use the SDL video output.
       
    78 	res/values/strings.xml	- strings used in your application, including the application name
       
    79 				  shown on the phone.
       
    80 	src/org/libsdl/app/SDLActivity.java - the Java class handling the initialization and binding
       
    81 				  to SDL.  Be very careful changing this, as the SDL library relies
       
    82 				  on this implementation.
    72 
    83 
    73 
    84 
    74 ================================================================================
    85 ================================================================================
    75  Customizing your application name
    86  Customizing your application name
    76 ================================================================================
    87 ================================================================================
    85 Here's an example of a minimal class file:
    96 Here's an example of a minimal class file:
    86 --- MyGame.java --------------------------
    97 --- MyGame.java --------------------------
    87 package com.gamemaker.game;
    98 package com.gamemaker.game;
    88 
    99 
    89 import org.libsdl.app.SDLActivity; 
   100 import org.libsdl.app.SDLActivity; 
    90 import android.os.*; 
       
    91 
   101 
    92 /* 
   102 /* 
    93  * A sample wrapper class that just calls SDLActivity 
   103  * A sample wrapper class that just calls SDLActivity 
    94  */ 
   104  */ 
    95 
   105 
    96 public class MyGame extends SDLActivity { 
   106 public class MyGame extends SDLActivity { }
    97     protected void onCreate(Bundle savedInstanceState) { 
   107 
    98 	super.onCreate(savedInstanceState); 
       
    99     } 
       
   100    
       
   101     protected void onDestroy() { 
       
   102 	super.onDestroy(); 
       
   103     } 
       
   104 }
       
   105 ------------------------------------------
   108 ------------------------------------------
   106 
   109 
   107 Then replace "SDLActivity" in AndroidManifest.xml with the name of your
   110 Then replace "SDLActivity" in AndroidManifest.xml with the name of your
   108 class, .e.g. "MyGame"
   111 class, .e.g. "MyGame"
   109 
   112 
   110 ================================================================================
   113 ================================================================================
   111  Customizing your application icon
   114  Customizing your application icon
   112 ================================================================================
   115 ================================================================================
   113 
   116 
   114 Conceptually changing your icon is just replacing the icon.png files in the
   117 Conceptually changing your icon is just replacing the icon.png files in the
   115 drawable directories under the res directory.
   118 drawable directories under the res directory. There are 3 directories for
   116 
   119 different screen sizes. These can be replaced with 1 dir called 'drawable',
   117 The easiest way to create a set of icons for your project is to remove all
   120 containing an icon file 'icon.png' with dimensions 48x48 or 72x72.
   118 the existing icon.png files, and then use the Eclipse IDE to create a dummy
       
   119 project.  During the process of doing this Eclipse will prompt you to create
       
   120 an icon. Then just copy the drawable directories it creates over to your
       
   121 res directory.
       
   122 
   121 
   123 You may need to change the name of your icon in AndroidManifest.xml to match
   122 You may need to change the name of your icon in AndroidManifest.xml to match
   124 the filename used by Eclipse.
   123 this icon filename.
   125 
   124 
   126 ================================================================================
   125 ================================================================================
   127  Loading assets
   126  Loading assets
   128 ================================================================================
   127 ================================================================================
   129 
   128 
   185 
   184 
   186 ================================================================================
   185 ================================================================================
   187  Additional documentation
   186  Additional documentation
   188 ================================================================================
   187 ================================================================================
   189 
   188 
   190 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.
   189 The documentation in the NDK docs directory is very helpful in understanding the
       
   190 build process and how to work with native code on the Android platform.
   191 
   191 
   192 The best place to start is with docs/OVERVIEW.TXT
   192 The best place to start is with docs/OVERVIEW.TXT
   193 
   193 
   194 
   194 
   195 ================================================================================
   195 ================================================================================
   215 There are some good tips and tricks for getting the most out of the
   215 There are some good tips and tricks for getting the most out of the
   216 emulator here: http://developer.android.com/tools/devices/emulator.html
   216 emulator here: http://developer.android.com/tools/devices/emulator.html
   217 
   217 
   218 Especially useful is the info on setting up OpenGL ES 2.0 emulation.
   218 Especially useful is the info on setting up OpenGL ES 2.0 emulation.
   219 
   219 
       
   220 Notice that this software emulator is incredibly slow and needs a lot of disk space.
       
   221 Using a real device works better.
   220 
   222 
   221 ================================================================================
   223 ================================================================================
   222  Troubleshooting
   224  Troubleshooting
   223 ================================================================================
   225 ================================================================================
   224 
   226 
   241 	adb shell ls /sdcard/
   243 	adb shell ls /sdcard/
   242 
   244 
   243 You can start a command shell on the default device with:
   245 You can start a command shell on the default device with:
   244 	adb shell
   246 	adb shell
   245 
   247 
   246 You can do a clean build with the following commands:
   248 You can remove the library files of your project (and not the SDL lib files) with:
   247 	ndk-build clean
   249 	ndk-build clean
       
   250 
       
   251 You can do a build with the following command:
   248 	ndk-build
   252 	ndk-build
   249 
   253 
   250 You can see the complete command line that ndk-build is using by passing V=1 on the command line:
   254 You can see the complete command line that ndk-build is using by passing V=1 on the command line:
   251 	ndk-build V=1
   255 	ndk-build V=1
   252 
   256 
   253 If your application crashes in native code, you can use addr2line to convert the addresses in the stack trace to lines in your code.
   257 If your application crashes in native code, you can use addr2line to convert the
       
   258 addresses in the stack trace to lines in your code.
   254 
   259 
   255 For example, if your crash looks like this:
   260 For example, if your crash looks like this:
   256 I/DEBUG   (   31): signal 11 (SIGSEGV), code 2 (SEGV_ACCERR), fault addr 400085d0
   261 I/DEBUG   (   31): signal 11 (SIGSEGV), code 2 (SEGV_ACCERR), fault addr 400085d0
   257 I/DEBUG   (   31):  r0 00000000  r1 00001000  r2 00000003  r3 400085d4
   262 I/DEBUG   (   31):  r0 00000000  r1 00001000  r2 00000003  r3 400085d4
   258 I/DEBUG   (   31):  r4 400085d0  r5 40008000  r6 afd41504  r7 436c6a7c
   263 I/DEBUG   (   31):  r4 400085d0  r5 40008000  r6 afd41504  r7 436c6a7c
   261 I/DEBUG   (   31):          #00  pc 0001c902  /system/lib/libc.so
   266 I/DEBUG   (   31):          #00  pc 0001c902  /system/lib/libc.so
   262 I/DEBUG   (   31):          #01  pc 0001ccf6  /system/lib/libc.so
   267 I/DEBUG   (   31):          #01  pc 0001ccf6  /system/lib/libc.so
   263 I/DEBUG   (   31):          #02  pc 000014bc  /data/data/org.libsdl.app/lib/libmain.so
   268 I/DEBUG   (   31):          #02  pc 000014bc  /data/data/org.libsdl.app/lib/libmain.so
   264 I/DEBUG   (   31):          #03  pc 00001506  /data/data/org.libsdl.app/lib/libmain.so
   269 I/DEBUG   (   31):          #03  pc 00001506  /data/data/org.libsdl.app/lib/libmain.so
   265 
   270 
   266 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:
   271 You can see that there's a crash in the C library being called from the main code.
       
   272 I run addr2line with the debug version of my code:
   267 	arm-eabi-addr2line -C -f -e obj/local/armeabi/libmain.so
   273 	arm-eabi-addr2line -C -f -e obj/local/armeabi/libmain.so
   268 and then paste in the number after "pc" in the call stack, from the line that I care about:
   274 and then paste in the number after "pc" in the call stack, from the line that I care about:
   269 000014bc
   275 000014bc
   270 
   276 
   271 I get output from addr2line showing that it's in the quit function, in testspriteminimal.c, on line 23.
   277 I get output from addr2line showing that it's in the quit function, in testspriteminimal.c, on line 23.
   274 
   280 
   275 #include <android/log.h>
   281 #include <android/log.h>
   276 
   282 
   277 	__android_log_print(ANDROID_LOG_INFO, "foo", "Something happened! x = %d", x);
   283 	__android_log_print(ANDROID_LOG_INFO, "foo", "Something happened! x = %d", x);
   278 
   284 
   279 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:
   285 If you need to build without optimization turned on, you can create a file called
       
   286 "Application.mk" in the jni directory, with the following line in it:
   280 APP_OPTIM := debug
   287 APP_OPTIM := debug
   281 
   288 
   282 
   289 
   283 ================================================================================
   290 ================================================================================
   284  Memory debugging
   291  Memory debugging
   326 
   333 
   327 ================================================================================
   334 ================================================================================
   328  Known issues
   335  Known issues
   329 ================================================================================
   336 ================================================================================
   330 
   337 
   331 - SDL audio (although it's mostly written, just not working properly yet)
       
   332 - TODO. I'm sure there's a bunch more stuff I haven't thought of 
   338 - TODO. I'm sure there's a bunch more stuff I haven't thought of