docs/README-android.md
changeset 9066 c2af3ff967cc
parent 9065 c8a8b11fd0ad
child 10092 f1949a74dce5
     1.1 --- a/docs/README-android.md	Fri Aug 15 23:18:57 2014 +0200
     1.2 +++ b/docs/README-android.md	Fri Aug 15 23:39:14 2014 +0200
     1.3 @@ -18,9 +18,9 @@
     1.4  
     1.5  - Android applications are Java-based, optionally with parts written in C
     1.6  - As SDL apps are C-based, we use a small Java shim that uses JNI to talk to 
     1.7 -the SDL library
     1.8 +  the SDL library
     1.9  - This means that your application C code must be placed inside an Android 
    1.10 -Java project, along with some C support code that communicates with Java
    1.11 +  Java project, along with some C support code that communicates with Java
    1.12  - This eventually produces a standard Android .apk package
    1.13  
    1.14  The Android Java code implements an "Activity" and can be found in:
    1.15 @@ -42,15 +42,15 @@
    1.16  
    1.17  There's two ways of using it:
    1.18  
    1.19 -androidbuild.sh com.yourcompany.yourapp < sources.list
    1.20 -androidbuild.sh com.yourcompany.yourapp source1.c source2.c ...sourceN.c
    1.21 +    androidbuild.sh com.yourcompany.yourapp < sources.list
    1.22 +    androidbuild.sh com.yourcompany.yourapp source1.c source2.c ...sourceN.c
    1.23  
    1.24  sources.list should be a text file with a source file name in each line
    1.25  Filenames should be specified relative to the current directory, for example if
    1.26  you are in the build-scripts directory and want to create the testgles.c test, you'll
    1.27  run:
    1.28 -    
    1.29 -./androidbuild.sh org.libsdl.testgles ../test/testgles.c
    1.30 +
    1.31 +    ./androidbuild.sh org.libsdl.testgles ../test/testgles.c
    1.32  
    1.33  One limitation of this script is that all sources provided will be aggregated into
    1.34  a single directory, thus all your source files should have a unique name.
    1.35 @@ -74,7 +74,9 @@
    1.36  If you want to use the Eclipse IDE, skip to the Eclipse section below.
    1.37  
    1.38  5. Create <project>/local.properties and use that to point to the Android SDK directory, by writing a line with the following form:
    1.39 -sdk.dir=PATH_TO_ANDROID_SDK
    1.40 +
    1.41 +       sdk.dir=PATH_TO_ANDROID_SDK
    1.42 +
    1.43  6. Run 'ant debug' in android/project. This compiles the .java and eventually 
    1.44     creates a .apk with the native code embedded
    1.45  7. 'ant debug install' will push the apk to the device or emulator (if connected)
    1.46 @@ -125,7 +127,7 @@
    1.47  4. create and export an environment variable named NDK_MODULE_PATH that points
    1.48     to the parent directory of this SDL directory. e.g.:
    1.49  
    1.50 -   export NDK_MODULE_PATH="$PWD"/..
    1.51 +       export NDK_MODULE_PATH="$PWD"/..
    1.52  
    1.53  5. Edit <project>/src/org/libsdl/app/SDLActivity.java and remove the call to
    1.54     System.loadLibrary("SDL2").
    1.55 @@ -142,7 +144,7 @@
    1.56  Then create a Java class extending SDLActivity and place it in a directory
    1.57  under src matching your package, e.g.
    1.58  
    1.59 -	src/com/gamemaker/game/MyGame.java
    1.60 +    src/com/gamemaker/game/MyGame.java
    1.61  
    1.62  Here's an example of a minimal class file:
    1.63  
    1.64 @@ -184,9 +186,9 @@
    1.65  
    1.66  There are also a few Android specific functions that allow you to get other
    1.67  useful paths for saving and loading data:
    1.68 -SDL_AndroidGetInternalStoragePath()
    1.69 -SDL_AndroidGetExternalStorageState()
    1.70 -SDL_AndroidGetExternalStoragePath()
    1.71 +* SDL_AndroidGetInternalStoragePath()
    1.72 +* SDL_AndroidGetExternalStorageState()
    1.73 +* SDL_AndroidGetExternalStoragePath()
    1.74  
    1.75  See SDL_system.h for more details on these functions.
    1.76  
    1.77 @@ -228,6 +230,7 @@
    1.78  
    1.79  For a quick tour on how Linux native threads interoperate with the Java VM, take
    1.80  a look here: http://developer.android.com/guide/practices/jni.html
    1.81 +
    1.82  If you want to use threads in your SDL app, it's strongly recommended that you
    1.83  do so by creating them using SDL functions. This way, the required attach/detach
    1.84  handling is managed by SDL automagically. If you have threads created by other
    1.85 @@ -242,7 +245,8 @@
    1.86  
    1.87  You can use STL in your project by creating an Application.mk file in the jni
    1.88  folder and adding the following line:
    1.89 -APP_STL := stlport_static
    1.90 +
    1.91 +    APP_STL := stlport_static
    1.92  
    1.93  For more information check out CPLUSPLUS-SUPPORT.html in the NDK documentation.
    1.94  
    1.95 @@ -293,39 +297,39 @@
    1.96  
    1.97  You can see if adb can see any devices with the following command:
    1.98  
    1.99 -	adb devices
   1.100 +    adb devices
   1.101  
   1.102  You can see the output of log messages on the default device with:
   1.103  
   1.104 -	adb logcat
   1.105 +    adb logcat
   1.106  
   1.107  You can push files to the device with:
   1.108  
   1.109 -	adb push local_file remote_path_and_file
   1.110 +    adb push local_file remote_path_and_file
   1.111  
   1.112  You can push files to the SD Card at /sdcard, for example:
   1.113  
   1.114 -	adb push moose.dat /sdcard/moose.dat
   1.115 +    adb push moose.dat /sdcard/moose.dat
   1.116  
   1.117  You can see the files on the SD card with a shell command:
   1.118  
   1.119 -	adb shell ls /sdcard/
   1.120 +    adb shell ls /sdcard/
   1.121  
   1.122  You can start a command shell on the default device with:
   1.123  
   1.124 -	adb shell
   1.125 +    adb shell
   1.126  
   1.127  You can remove the library files of your project (and not the SDL lib files) with:
   1.128  
   1.129 -	ndk-build clean
   1.130 +    ndk-build clean
   1.131  
   1.132  You can do a build with the following command:
   1.133  
   1.134 -	ndk-build
   1.135 +    ndk-build
   1.136  
   1.137  You can see the complete command line that ndk-build is using by passing V=1 on the command line:
   1.138  
   1.139 -	ndk-build V=1
   1.140 +    ndk-build V=1
   1.141  
   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 @@ -345,7 +349,7 @@
   1.145  You can see that there's a crash in the C library being called from the main code.
   1.146  I run addr2line with the debug version of my code:
   1.147  
   1.148 -	arm-eabi-addr2line -C -f -e obj/local/armeabi/libmain.so
   1.149 +    arm-eabi-addr2line -C -f -e obj/local/armeabi/libmain.so
   1.150  
   1.151  and then paste in the number after "pc" in the call stack, from the line that I care about:
   1.152  000014bc
   1.153 @@ -360,7 +364,8 @@
   1.154  
   1.155  If you need to build without optimization turned on, you can create a file called
   1.156  "Application.mk" in the jni directory, with the following line in it:
   1.157 -APP_OPTIM := debug
   1.158 +
   1.159 +    APP_OPTIM := debug
   1.160  
   1.161  
   1.162  ================================================================================
   1.163 @@ -370,7 +375,7 @@
   1.164  The best (and slowest) way to debug memory issues on Android is valgrind.
   1.165  Valgrind has support for Android out of the box, just grab code using:
   1.166  
   1.167 -	svn co svn://svn.valgrind.org/valgrind/trunk valgrind
   1.168 +    svn co svn://svn.valgrind.org/valgrind/trunk valgrind
   1.169  
   1.170  ... and follow the instructions in the file README.android to build it.
   1.171  
   1.172 @@ -389,15 +394,15 @@
   1.173  
   1.174  Then push it to the device:
   1.175  
   1.176 -	adb push start_valgrind_app /data/local
   1.177 +    adb push start_valgrind_app /data/local
   1.178  
   1.179  and make it executable:
   1.180  
   1.181 -	adb shell chmod 755 /data/local/start_valgrind_app
   1.182 +    adb shell chmod 755 /data/local/start_valgrind_app
   1.183  
   1.184  and tell Android to use the script to launch your application:
   1.185  
   1.186 -	adb shell setprop wrap.org.libsdl.app "logwrapper /data/local/start_valgrind_app"
   1.187 +    adb shell setprop wrap.org.libsdl.app "logwrapper /data/local/start_valgrind_app"
   1.188  
   1.189  If the setprop command says "could not set property", it's likely that
   1.190  your package name is too long and you should make it shorter by changing
   1.191 @@ -408,11 +413,11 @@
   1.192  when it's done (or even while it's running) you can grab the valgrind
   1.193  output file:
   1.194  
   1.195 -	adb pull /sdcard/valgrind.log
   1.196 +    adb pull /sdcard/valgrind.log
   1.197  
   1.198  When you're done instrumenting with valgrind, you can disable the wrapper:
   1.199  
   1.200 -	adb shell setprop wrap.org.libsdl.app ""
   1.201 +    adb shell setprop wrap.org.libsdl.app ""
   1.202  
   1.203  ================================================================================
   1.204   Why is API level 10 the minimum required?