README.android improvements by W. Boeke, bug #1637
authorGabriel Jacobo <gabomdq@gmail.com>
Wed, 21 Nov 2012 08:27:36 -0300
changeset 6678afb9be20f8d2
parent 6677 c3202c29e352
child 6679 9f0d4046f3d6
README.android improvements by W. Boeke, bug #1637
README.android
     1.1 --- a/README.android	Mon Nov 19 20:38:52 2012 -0800
     1.2 +++ b/README.android	Wed Nov 21 08:27:36 2012 -0300
     1.3 @@ -38,7 +38,8 @@
     1.4  ================================================================================
     1.5  
     1.6  Instructions:
     1.7 -1. Copy the android-project directory wherever you want to keep your projects and rename it to the name of your project.
     1.8 +1. Copy the android-project directory wherever you want to keep your projects
     1.9 +   and rename it to the name of your project.
    1.10  2. Move or symlink this SDL directory into the <project>/jni directory
    1.11  3. Edit <project>/jni/src/Android.mk to include your source files
    1.12  4. Run 'ndk-build' (a script provided by the NDK). This compiles the C source
    1.13 @@ -47,28 +48,38 @@
    1.14  
    1.15  5. Edit <project>/local.properties to point to the Android SDK directory
    1.16  6. Run 'ant debug' in android/project. This compiles the .java and eventually 
    1.17 -creates a .apk with the native code embedded
    1.18 +   creates a .apk with the native code embedded
    1.19  7. 'ant debug install' will push the apk to the device or emulator (if connected)
    1.20  
    1.21  Here's an explanation of the files in the Android project, so you can customize them:
    1.22  
    1.23  android-project/
    1.24 -	AndroidManifest.xml	- package manifest, customize this for your app
    1.25 +	AndroidManifest.xml	- package manifest. Among others, it contains the class name
    1.26 +				  of the main activity.
    1.27  	build.properties	- empty
    1.28 -	build.xml		- build description file, used by ant
    1.29 -	default.properties	- holds the ABI for the application, currently android-5 which corresponds to the Android 2.0 system image
    1.30 +	build.xml		- build description file, used by ant. The actual application name
    1.31 +				  is specified here.
    1.32 +	default.properties	- holds the target ABI for the application, can range between
    1.33 +				  android-5 and android-16
    1.34  	local.properties	- holds the SDK path, you should change this to the path to your SDK
    1.35  	jni/			- directory holding native code
    1.36 -	jni/Android.mk		- Android makefile that includes all subdirectories
    1.37 -	jni/SDL/		- directory holding the SDL library files
    1.38 +	jni/Android.mk		- Android makefile that can call recursively the Android.mk files
    1.39 +				  in all subdirectories
    1.40 +	jni/SDL/		- (symlink to) directory holding the SDL library files
    1.41  	jni/SDL/Android.mk	- Android makefile for creating the SDL shared library
    1.42  	jni/src/		- directory holding your C/C++ source
    1.43 -	jni/src/Android.mk	- Android makefile that you should customize to include your source code and any library references
    1.44 +	jni/src/Android.mk	- Android makefile that you should customize to include your 
    1.45 +                                  source code and any library references
    1.46  	res/			- directory holding resources for your application
    1.47 -	res/drawable-*		- directories holding icons for different phone hardware
    1.48 -	res/layout/main.xml	- place holder for the main screen layout, overridden by the SDL video output
    1.49 -	res/values/strings.xml	- strings used in your application, including the application name shown on the phone.
    1.50 -	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.
    1.51 +	res/drawable-*		- directories holding icons for different phone hardware. Could be
    1.52 +				  one dir called "drawable".
    1.53 +	res/layout/main.xml	- Usually contains a file main.xml, which declares the screen layout.
    1.54 +				  We don't need it because we use the SDL video output.
    1.55 +	res/values/strings.xml	- strings used in your application, including the application name
    1.56 +				  shown on the phone.
    1.57 +	src/org/libsdl/app/SDLActivity.java - the Java class handling the initialization and binding
    1.58 +				  to SDL.  Be very careful changing this, as the SDL library relies
    1.59 +				  on this implementation.
    1.60  
    1.61  
    1.62  ================================================================================
    1.63 @@ -87,21 +98,13 @@
    1.64  package com.gamemaker.game;
    1.65  
    1.66  import org.libsdl.app.SDLActivity; 
    1.67 -import android.os.*; 
    1.68  
    1.69  /* 
    1.70   * A sample wrapper class that just calls SDLActivity 
    1.71   */ 
    1.72  
    1.73 -public class MyGame extends SDLActivity { 
    1.74 -    protected void onCreate(Bundle savedInstanceState) { 
    1.75 -	super.onCreate(savedInstanceState); 
    1.76 -    } 
    1.77 -   
    1.78 -    protected void onDestroy() { 
    1.79 -	super.onDestroy(); 
    1.80 -    } 
    1.81 -}
    1.82 +public class MyGame extends SDLActivity { }
    1.83 +
    1.84  ------------------------------------------
    1.85  
    1.86  Then replace "SDLActivity" in AndroidManifest.xml with the name of your
    1.87 @@ -112,16 +115,12 @@
    1.88  ================================================================================
    1.89  
    1.90  Conceptually changing your icon is just replacing the icon.png files in the
    1.91 -drawable directories under the res directory.
    1.92 -
    1.93 -The easiest way to create a set of icons for your project is to remove all
    1.94 -the existing icon.png files, and then use the Eclipse IDE to create a dummy
    1.95 -project.  During the process of doing this Eclipse will prompt you to create
    1.96 -an icon. Then just copy the drawable directories it creates over to your
    1.97 -res directory.
    1.98 +drawable directories under the res directory. There are 3 directories for
    1.99 +different screen sizes. These can be replaced with 1 dir called 'drawable',
   1.100 +containing an icon file 'icon.png' with dimensions 48x48 or 72x72.
   1.101  
   1.102  You may need to change the name of your icon in AndroidManifest.xml to match
   1.103 -the filename used by Eclipse.
   1.104 +this icon filename.
   1.105  
   1.106  ================================================================================
   1.107   Loading assets
   1.108 @@ -187,7 +186,8 @@
   1.109   Additional documentation
   1.110  ================================================================================
   1.111  
   1.112 -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.
   1.113 +The documentation in the NDK docs directory is very helpful in understanding the
   1.114 +build process and how to work with native code on the Android platform.
   1.115  
   1.116  The best place to start is with docs/OVERVIEW.TXT
   1.117  
   1.118 @@ -217,6 +217,8 @@
   1.119  
   1.120  Especially useful is the info on setting up OpenGL ES 2.0 emulation.
   1.121  
   1.122 +Notice that this software emulator is incredibly slow and needs a lot of disk space.
   1.123 +Using a real device works better.
   1.124  
   1.125  ================================================================================
   1.126   Troubleshooting
   1.127 @@ -243,14 +245,17 @@
   1.128  You can start a command shell on the default device with:
   1.129  	adb shell
   1.130  
   1.131 -You can do a clean build with the following commands:
   1.132 +You can remove the library files of your project (and not the SDL lib files) with:
   1.133  	ndk-build clean
   1.134 +
   1.135 +You can do a build with the following command:
   1.136  	ndk-build
   1.137  
   1.138  You can see the complete command line that ndk-build is using by passing V=1 on the command line:
   1.139  	ndk-build V=1
   1.140  
   1.141 -If your application crashes in native code, you can use addr2line to convert the addresses in the stack trace to lines in your code.
   1.142 +If your application crashes in native code, you can use addr2line to convert the
   1.143 +addresses in the stack trace to lines in your code.
   1.144  
   1.145  For example, if your crash looks like this:
   1.146  I/DEBUG   (   31): signal 11 (SIGSEGV), code 2 (SEGV_ACCERR), fault addr 400085d0
   1.147 @@ -263,7 +268,8 @@
   1.148  I/DEBUG   (   31):          #02  pc 000014bc  /data/data/org.libsdl.app/lib/libmain.so
   1.149  I/DEBUG   (   31):          #03  pc 00001506  /data/data/org.libsdl.app/lib/libmain.so
   1.150  
   1.151 -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:
   1.152 +You can see that there's a crash in the C library being called from the main code.
   1.153 +I run addr2line with the debug version of my code:
   1.154  	arm-eabi-addr2line -C -f -e obj/local/armeabi/libmain.so
   1.155  and then paste in the number after "pc" in the call stack, from the line that I care about:
   1.156  000014bc
   1.157 @@ -276,7 +282,8 @@
   1.158  
   1.159  	__android_log_print(ANDROID_LOG_INFO, "foo", "Something happened! x = %d", x);
   1.160  
   1.161 -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:
   1.162 +If you need to build without optimization turned on, you can create a file called
   1.163 +"Application.mk" in the jni directory, with the following line in it:
   1.164  APP_OPTIM := debug
   1.165  
   1.166  
   1.167 @@ -328,5 +335,4 @@
   1.168   Known issues
   1.169  ================================================================================
   1.170  
   1.171 -- SDL audio (although it's mostly written, just not working properly yet)
   1.172  - TODO. I'm sure there's a bunch more stuff I haven't thought of