README-android.txt
author Sam Lantinga <slouken@libsdl.org>
Thu, 10 Oct 2013 21:51:39 -0700
changeset 7804 1f85fb33694b
parent 7793 6463a850229d
child 7907 24b4e98c6010
permissions -rw-r--r--
Fixed bug 2146 - Enable static linking of libSDL on Android Denis Bernard This patch to Android.mk adds support for static linking of libSDL for Android applications. A patched readme with static build instructions is also provided. It does not break existing build environments setup according to the README-android.txt since the static library version will not be built in not required. The static build uses the Android NDK module system (see docs/IMPORT-MODULE.html in the NDK folder and step 5 in the instructions below). Instructions: 1. Copy the android-project directory wherever you want to keep your projects and rename it to the name of your project. 2. Create a symlink to SDL/src/main/android/SDL_android_main.c as <project>/jni/src/SDL_android_main.c 3. Rename <project>/jni/src/Android_static.mk to <project>/jni/src/Android.mk (overwrite the existing one) 4. Edit <project>/jni/src/Android.mk to include your source files 5. create and export an environment variable named NDK_MODULE_PATH that points to the parent directory of this SDL directory. e.g.: export NDK_MODULE_PATH="$PWD"/.. 6. Edit <project>/src/org/libsdl/app/SDLActivity.java and remove the call to System.loadLibrary("SDL2") line 42. 7. Run 'ndk-build' (a script provided by the NDK). This compiles the C source Although this requires an environment variable to be setup, it can be added once and for all to the main Android.mk of the project.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
7222
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
     1
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
     2
Simple DirectMedia Layer for Android
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
     3
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
     4
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
     5
Requirements:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
     6
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
     7
Android SDK (version 10 or later)
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
     8
http://developer.android.com/sdk/index.html
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
     9
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    10
Android NDK r7 or later
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    11
http://developer.android.com/sdk/ndk/index.html
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    12
7241
28602f5ca96d Fixed recently deleted Ms in READMEs.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 7222
diff changeset
    13
Minimum API level supported by SDL: 10 (Android 2.3.3)
7222
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    14
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    15
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    16
 How the port works
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    17
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    18
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    19
- Android applications are Java-based, optionally with parts written in C
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    20
- As SDL apps are C-based, we use a small Java shim that uses JNI to talk to 
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    21
the SDL library
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    22
- This means that your application C code must be placed inside an Android 
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    23
Java project, along with some C support code that communicates with Java
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    24
- This eventually produces a standard Android .apk package
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    25
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    26
The Android Java code implements an "Activity" and can be found in:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    27
android-project/src/org/libsdl/app/SDLActivity.java
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    28
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    29
The Java code loads your game code, the SDL shared library, and
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    30
dispatches to native functions implemented in the SDL library:
7501
b27825bb5879 Android: Removed all unnecessary dependencies on C++.
Eric Wing <ewing . public |-at-| gmail . com>
parents: 7241
diff changeset
    31
src/SDL_android.c
7222
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    32
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    33
Your project must include some glue code that starts your main() routine:
7501
b27825bb5879 Android: Removed all unnecessary dependencies on C++.
Eric Wing <ewing . public |-at-| gmail . com>
parents: 7241
diff changeset
    34
src/main/android/SDL_android_main.c
7222
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    35
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    36
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    37
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    38
 Building an app
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    39
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    40
7793
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    41
For simple projects you can use the script located at build-scripts/androidbuild.sh
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    42
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    43
There's two ways of using it:
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    44
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    45
androidbuild.sh com.yourcompany.yourapp < sources.list
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    46
androidbuild.sh com.yourcompany.yourapp source1.c source2.c ...sourceN.c
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    47
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    48
sources.list should be a text file with a source file name in each line
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    49
Filenames should be specified relative to the current directory, for example if
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    50
you are in the build-scripts directory and want to create the testgles.c test, you'll
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    51
run:
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    52
    
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    53
./androidbuild.sh org.libsdl.testgles ../test/testgles.c
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    54
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    55
One limitation of this script is that all sources provided will be aggregated into
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    56
a single directory, thus all your source files should have a unique name.
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    57
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    58
Once the project is complete the script will tell you where the debug APK is located.
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    59
If you want to create a signed release APK, you can use the project created by this
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    60
utility to generate it.
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    61
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    62
Finally, a word of caution: re running androidbuild.sh wipes any changes you may have
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    63
done in the build directory for the app!
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    64
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    65
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    66
For more complex projects, follow these instructions:
6463a850229d Adds test framework to Android.mk and a simple utility to build Android projects
Gabriel Jacobo <gabomdq@gmail.com>
parents: 7501
diff changeset
    67
    
7222
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    68
1. Copy the android-project directory wherever you want to keep your projects
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    69
   and rename it to the name of your project.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    70
2. Move or symlink this SDL directory into the <project>/jni directory
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    71
3. Edit <project>/jni/src/Android.mk to include your source files
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    72
4. Run 'ndk-build' (a script provided by the NDK). This compiles the C source
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    73
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    74
If you want to use the Eclipse IDE, skip to the Eclipse section below.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    75
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    76
5. Create <project>/local.properties and use that to point to the Android SDK directory, by writing a line with the following form:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    77
sdk.dir=PATH_TO_ANDROID_SDK
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    78
6. Run 'ant debug' in android/project. This compiles the .java and eventually 
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    79
   creates a .apk with the native code embedded
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    80
7. 'ant debug install' will push the apk to the device or emulator (if connected)
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    81
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    82
Here's an explanation of the files in the Android project, so you can customize them:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    83
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    84
android-project/
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    85
	AndroidManifest.xml	- package manifest. Among others, it contains the class name
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    86
				  of the main Activity and the package name of the application.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    87
	build.properties	- empty
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    88
	build.xml		- build description file, used by ant. The actual application name
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    89
				  is specified here.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    90
	default.properties	- holds the target ABI for the application, android-10 and up
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    91
	project.properties	- holds the target ABI for the application, android-10 and up
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    92
	local.properties	- holds the SDK path, you should change this to the path to your SDK
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    93
	jni/			- directory holding native code
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    94
	jni/Android.mk		- Android makefile that can call recursively the Android.mk files
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    95
				  in all subdirectories
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    96
	jni/SDL/		- (symlink to) directory holding the SDL library files
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    97
	jni/SDL/Android.mk	- Android makefile for creating the SDL shared library
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    98
	jni/src/		- directory holding your C/C++ source
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
    99
	jni/src/Android.mk	- Android makefile that you should customize to include your 
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   100
                                  source code and any library references
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   101
	res/			- directory holding resources for your application
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   102
	res/drawable-*		- directories holding icons for different phone hardware. Could be
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   103
				  one dir called "drawable".
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   104
	res/layout/main.xml	- Usually contains a file main.xml, which declares the screen layout.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   105
				  We don't need it because we use the SDL video output.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   106
	res/values/strings.xml	- strings used in your application, including the application name
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   107
				  shown on the phone.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   108
	src/org/libsdl/app/SDLActivity.java - the Java class handling the initialization and binding
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   109
				  to SDL.  Be very careful changing this, as the SDL library relies
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   110
				  on this implementation.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   111
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   112
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   113
================================================================================
7804
1f85fb33694b Fixed bug 2146 - Enable static linking of libSDL on Android
Sam Lantinga <slouken@libsdl.org>
parents: 7793
diff changeset
   114
 Build an app with static linking of libSDL
1f85fb33694b Fixed bug 2146 - Enable static linking of libSDL on Android
Sam Lantinga <slouken@libsdl.org>
parents: 7793
diff changeset
   115
================================================================================
1f85fb33694b Fixed bug 2146 - Enable static linking of libSDL on Android
Sam Lantinga <slouken@libsdl.org>
parents: 7793
diff changeset
   116
1f85fb33694b Fixed bug 2146 - Enable static linking of libSDL on Android
Sam Lantinga <slouken@libsdl.org>
parents: 7793
diff changeset
   117
This build uses the Android NDK module system.
1f85fb33694b Fixed bug 2146 - Enable static linking of libSDL on Android
Sam Lantinga <slouken@libsdl.org>
parents: 7793
diff changeset
   118
1f85fb33694b Fixed bug 2146 - Enable static linking of libSDL on Android
Sam Lantinga <slouken@libsdl.org>
parents: 7793
diff changeset
   119
Instructions:
1f85fb33694b Fixed bug 2146 - Enable static linking of libSDL on Android
Sam Lantinga <slouken@libsdl.org>
parents: 7793
diff changeset
   120
1. Copy the android-project directory wherever you want to keep your projects
1f85fb33694b Fixed bug 2146 - Enable static linking of libSDL on Android
Sam Lantinga <slouken@libsdl.org>
parents: 7793
diff changeset
   121
   and rename it to the name of your project.
1f85fb33694b Fixed bug 2146 - Enable static linking of libSDL on Android
Sam Lantinga <slouken@libsdl.org>
parents: 7793
diff changeset
   122
2. Rename <project>/jni/src/Android_static.mk to <project>/jni/src/Android.mk
1f85fb33694b Fixed bug 2146 - Enable static linking of libSDL on Android
Sam Lantinga <slouken@libsdl.org>
parents: 7793
diff changeset
   123
   (overwrite the existing one)
1f85fb33694b Fixed bug 2146 - Enable static linking of libSDL on Android
Sam Lantinga <slouken@libsdl.org>
parents: 7793
diff changeset
   124
3. Edit <project>/jni/src/Android.mk to include your source files
1f85fb33694b Fixed bug 2146 - Enable static linking of libSDL on Android
Sam Lantinga <slouken@libsdl.org>
parents: 7793
diff changeset
   125
4. create and export an environment variable named NDK_MODULE_PATH that points
1f85fb33694b Fixed bug 2146 - Enable static linking of libSDL on Android
Sam Lantinga <slouken@libsdl.org>
parents: 7793
diff changeset
   126
   to the parent directory of this SDL directory. e.g.:
1f85fb33694b Fixed bug 2146 - Enable static linking of libSDL on Android
Sam Lantinga <slouken@libsdl.org>
parents: 7793
diff changeset
   127
1f85fb33694b Fixed bug 2146 - Enable static linking of libSDL on Android
Sam Lantinga <slouken@libsdl.org>
parents: 7793
diff changeset
   128
   export NDK_MODULE_PATH="$PWD"/..
1f85fb33694b Fixed bug 2146 - Enable static linking of libSDL on Android
Sam Lantinga <slouken@libsdl.org>
parents: 7793
diff changeset
   129
1f85fb33694b Fixed bug 2146 - Enable static linking of libSDL on Android
Sam Lantinga <slouken@libsdl.org>
parents: 7793
diff changeset
   130
5. Edit <project>/src/org/libsdl/app/SDLActivity.java and remove the call to
1f85fb33694b Fixed bug 2146 - Enable static linking of libSDL on Android
Sam Lantinga <slouken@libsdl.org>
parents: 7793
diff changeset
   131
   System.loadLibrary("SDL2") line 42.
1f85fb33694b Fixed bug 2146 - Enable static linking of libSDL on Android
Sam Lantinga <slouken@libsdl.org>
parents: 7793
diff changeset
   132
6. Run 'ndk-build' (a script provided by the NDK). This compiles the C source
1f85fb33694b Fixed bug 2146 - Enable static linking of libSDL on Android
Sam Lantinga <slouken@libsdl.org>
parents: 7793
diff changeset
   133
1f85fb33694b Fixed bug 2146 - Enable static linking of libSDL on Android
Sam Lantinga <slouken@libsdl.org>
parents: 7793
diff changeset
   134
1f85fb33694b Fixed bug 2146 - Enable static linking of libSDL on Android
Sam Lantinga <slouken@libsdl.org>
parents: 7793
diff changeset
   135
================================================================================
7222
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   136
 Customizing your application name
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   137
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   138
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   139
To customize your application name, edit AndroidManifest.xml and replace
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   140
"org.libsdl.app" with an identifier for your product package.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   141
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   142
Then create a Java class extending SDLActivity and place it in a directory
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   143
under src matching your package, e.g.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   144
	src/com/gamemaker/game/MyGame.java
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   145
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   146
Here's an example of a minimal class file:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   147
--- MyGame.java --------------------------
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   148
package com.gamemaker.game;
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   149
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   150
import org.libsdl.app.SDLActivity; 
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   151
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   152
/* 
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   153
 * A sample wrapper class that just calls SDLActivity 
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   154
 */ 
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   155
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   156
public class MyGame extends SDLActivity { }
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   157
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   158
------------------------------------------
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   159
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   160
Then replace "SDLActivity" in AndroidManifest.xml with the name of your
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   161
class, .e.g. "MyGame"
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   162
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   163
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   164
 Customizing your application icon
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   165
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   166
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   167
Conceptually changing your icon is just replacing the "ic_launcher.png" files in
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   168
the drawable directories under the res directory. There are four directories for
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   169
different screen sizes. These can be replaced with one dir called "drawable",
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   170
containing an icon file "ic_launcher.png" with dimensions 48x48 or 72x72.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   171
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   172
You may need to change the name of your icon in AndroidManifest.xml to match
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   173
this icon filename.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   174
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   175
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   176
 Loading assets
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   177
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   178
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   179
Any files you put in the "assets" directory of your android-project directory
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   180
will get bundled into the application package and you can load them using the
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   181
standard functions in SDL_rwops.h.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   182
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   183
There are also a few Android specific functions that allow you to get other
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   184
useful paths for saving and loading data:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   185
SDL_AndroidGetInternalStoragePath()
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   186
SDL_AndroidGetExternalStorageState()
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   187
SDL_AndroidGetExternalStoragePath()
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   188
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   189
See SDL_system.h for more details on these functions.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   190
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   191
The asset packaging system will, by default, compress certain file extensions.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   192
SDL includes two asset file access mechanisms, the preferred one is the so
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   193
called "File Descriptor" method, which is faster and doesn't involve the Dalvik
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   194
GC, but given this method does not work on compressed assets, there is also the
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   195
"Input Stream" method, which is automatically used as a fall back by SDL. You
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   196
may want to keep this fact in mind when building your APK, specially when large
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   197
files are involved.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   198
For more information on which extensions get compressed by default and how to
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   199
disable this behaviour, see for example:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   200
    
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   201
http://ponystyle.com/blog/2010/03/26/dealing-with-asset-compression-in-android-apps/
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   202
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   203
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   204
 Pause / Resume behaviour
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   205
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   206
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   207
If SDL is compiled with SDL_ANDROID_BLOCK_ON_PAUSE defined (the default),
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   208
the event loop will block itself when the app is paused (ie, when the user
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   209
returns to the main Android dashboard). Blocking is better in terms of battery
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   210
use, and it allows your app to spring back to life instantaneously after resume
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   211
(versus polling for a resume message).
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   212
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   213
Upon resume, SDL will attempt to restore the GL context automatically.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   214
In modern devices (Android 3.0 and up) this will most likely succeed and your
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   215
app can continue to operate as it was.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   216
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   217
However, there's a chance (on older hardware, or on systems under heavy load),
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   218
where the GL context can not be restored. In that case you have to listen for
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   219
a specific message, (which is not yet implemented!) and restore your textures
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   220
manually or quit the app (which is actually the kind of behaviour you'll see
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   221
under iOS, if the OS can not restore your GL context it will just kill your app)
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   222
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   223
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   224
 Threads and the Java VM
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   225
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   226
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   227
For a quick tour on how Linux native threads interoperate with the Java VM, take
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   228
a look here: http://developer.android.com/guide/practices/jni.html
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   229
If you want to use threads in your SDL app, it's strongly recommended that you
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   230
do so by creating them using SDL functions. This way, the required attach/detach
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   231
handling is managed by SDL automagically. If you have threads created by other
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   232
means and they make calls to SDL functions, make sure that you call
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   233
Android_JNI_SetupThread before doing anything else otherwise SDL will attach
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   234
your thread automatically anyway (when you make an SDL call), but it'll never
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   235
detach it.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   236
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   237
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   238
 Using STL
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   239
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   240
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   241
You can use STL in your project by creating an Application.mk file in the jni
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   242
folder and adding the following line:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   243
APP_STL := stlport_static
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   244
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   245
For more information check out CPLUSPLUS-SUPPORT.html in the NDK documentation.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   246
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   247
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   248
 Additional documentation
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   249
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   250
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   251
The documentation in the NDK docs directory is very helpful in understanding the
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   252
build process and how to work with native code on the Android platform.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   253
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   254
The best place to start is with docs/OVERVIEW.TXT
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   255
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   256
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   257
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   258
 Using Eclipse
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   259
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   260
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   261
First make sure that you've installed Eclipse and the Android extensions as described here:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   262
	http://developer.android.com/sdk/eclipse-adt.html
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   263
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   264
Once you've copied the SDL android project and customized it, you can create an Eclipse project from it:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   265
 * File -> New -> Other
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   266
 * Select the Android -> Android Project wizard and click Next
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   267
 * Enter the name you'd like your project to have
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   268
 * Select "Create project from existing source" and browse for your project directory
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   269
 * Make sure the Build Target is set to Android 2.0
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   270
 * Click Finish
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   271
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   272
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   273
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   274
 Using the emulator
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   275
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   276
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   277
There are some good tips and tricks for getting the most out of the
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   278
emulator here: http://developer.android.com/tools/devices/emulator.html
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   279
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   280
Especially useful is the info on setting up OpenGL ES 2.0 emulation.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   281
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   282
Notice that this software emulator is incredibly slow and needs a lot of disk space.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   283
Using a real device works better.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   284
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   285
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   286
 Troubleshooting
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   287
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   288
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   289
You can create and run an emulator from the Eclipse IDE:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   290
 * Window -> Android SDK and AVD Manager
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   291
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   292
You can see if adb can see any devices with the following command:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   293
	adb devices
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   294
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   295
You can see the output of log messages on the default device with:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   296
	adb logcat
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   297
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   298
You can push files to the device with:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   299
	adb push local_file remote_path_and_file
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   300
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   301
You can push files to the SD Card at /sdcard, for example:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   302
	adb push moose.dat /sdcard/moose.dat
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   303
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   304
You can see the files on the SD card with a shell command:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   305
	adb shell ls /sdcard/
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   306
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   307
You can start a command shell on the default device with:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   308
	adb shell
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   309
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   310
You can remove the library files of your project (and not the SDL lib files) with:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   311
	ndk-build clean
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   312
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   313
You can do a build with the following command:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   314
	ndk-build
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   315
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   316
You can see the complete command line that ndk-build is using by passing V=1 on the command line:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   317
	ndk-build V=1
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   318
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   319
If your application crashes in native code, you can use addr2line to convert the
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   320
addresses in the stack trace to lines in your code.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   321
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   322
For example, if your crash looks like this:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   323
I/DEBUG   (   31): signal 11 (SIGSEGV), code 2 (SEGV_ACCERR), fault addr 400085d0
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   324
I/DEBUG   (   31):  r0 00000000  r1 00001000  r2 00000003  r3 400085d4
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   325
I/DEBUG   (   31):  r4 400085d0  r5 40008000  r6 afd41504  r7 436c6a7c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   326
I/DEBUG   (   31):  r8 436c6b30  r9 435c6fb0  10 435c6f9c  fp 4168d82c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   327
I/DEBUG   (   31):  ip 8346aff0  sp 436c6a60  lr afd1c8ff  pc afd1c902  cpsr 60000030
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   328
I/DEBUG   (   31):          #00  pc 0001c902  /system/lib/libc.so
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   329
I/DEBUG   (   31):          #01  pc 0001ccf6  /system/lib/libc.so
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   330
I/DEBUG   (   31):          #02  pc 000014bc  /data/data/org.libsdl.app/lib/libmain.so
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   331
I/DEBUG   (   31):          #03  pc 00001506  /data/data/org.libsdl.app/lib/libmain.so
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   332
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   333
You can see that there's a crash in the C library being called from the main code.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   334
I run addr2line with the debug version of my code:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   335
	arm-eabi-addr2line -C -f -e obj/local/armeabi/libmain.so
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   336
and then paste in the number after "pc" in the call stack, from the line that I care about:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   337
000014bc
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   338
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   339
I get output from addr2line showing that it's in the quit function, in testspriteminimal.c, on line 23.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   340
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   341
You can add logging to your code to help show what's happening:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   342
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   343
#include <android/log.h>
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   344
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   345
	__android_log_print(ANDROID_LOG_INFO, "foo", "Something happened! x = %d", x);
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   346
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   347
If you need to build without optimization turned on, you can create a file called
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   348
"Application.mk" in the jni directory, with the following line in it:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   349
APP_OPTIM := debug
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   350
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   351
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   352
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   353
 Memory debugging
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   354
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   355
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   356
The best (and slowest) way to debug memory issues on Android is valgrind.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   357
Valgrind has support for Android out of the box, just grab code using:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   358
	svn co svn://svn.valgrind.org/valgrind/trunk valgrind
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   359
... and follow the instructions in the file README.android to build it.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   360
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   361
One thing I needed to do on Mac OS X was change the path to the toolchain,
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   362
and add ranlib to the environment variables:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   363
export RANLIB=$NDKROOT/toolchains/arm-linux-androideabi-4.4.3/prebuilt/darwin-x86/bin/arm-linux-androideabi-ranlib
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   364
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   365
Once valgrind is built, you can create a wrapper script to launch your
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   366
application with it, changing org.libsdl.app to your package identifier:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   367
--- start_valgrind_app -------------------
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   368
#!/system/bin/sh
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   369
export TMPDIR=/data/data/org.libsdl.app
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   370
exec /data/local/Inst/bin/valgrind --log-file=/sdcard/valgrind.log --error-limit=no $*
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   371
------------------------------------------
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   372
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   373
Then push it to the device:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   374
	adb push start_valgrind_app /data/local
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   375
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   376
and make it executable:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   377
	adb shell chmod 755 /data/local/start_valgrind_app
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   378
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   379
and tell Android to use the script to launch your application:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   380
	adb shell setprop wrap.org.libsdl.app "logwrapper /data/local/start_valgrind_app"
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   381
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   382
If the setprop command says "could not set property", it's likely that
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   383
your package name is too long and you should make it shorter by changing
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   384
AndroidManifest.xml and the path to your class file in android-project/src
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   385
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   386
You can then launch your application normally and waaaaaaaiiittt for it.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   387
You can monitor the startup process with the logcat command above, and
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   388
when it's done (or even while it's running) you can grab the valgrind
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   389
output file:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   390
	adb pull /sdcard/valgrind.log
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   391
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   392
When you're done instrumenting with valgrind, you can disable the wrapper:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   393
	adb shell setprop wrap.org.libsdl.app ""
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   394
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   395
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   396
 Why is API level 10 the minimum required?
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   397
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   398
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   399
API level 10 is required because SDL requires some functionality for running not
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   400
available on older devices and some for building which is not in older NDK/SDKs.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   401
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   402
Support for native OpenGL ES and ES2 applications was introduced in the NDK for
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   403
API level 4 and 8. EGL was made a stable API in the NDK for API level 9, which
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   404
has since then been obsoleted, with the recommendation to developers to bump the
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   405
required API level to 10.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   406
As of this writing, according to http://developer.android.com/about/dashboards/index.html
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   407
about 90% of the Android devices accessing Google Play support API level 10 or
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   408
higher (March 2013).
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   409
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   410
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   411
 A note regarding the use of the "dirty rectangles" rendering technique
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   412
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   413
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   414
If your app uses a variation of the "dirty rectangles" rendering technique,
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   415
where you only update a portion of the screen on each frame, you may notice a
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   416
variety of visual glitches on Android, that are not present on other platforms.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   417
This is caused by SDL's use of EGL as the support system to handle OpenGL ES/ES2
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   418
contexts, in particular the use of the eglSwapBuffers function. As stated in the
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   419
documentation for the function "The contents of ancillary buffers are always 
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   420
undefined after calling eglSwapBuffers".
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   421
Setting the EGL_SWAP_BEHAVIOR attribute of the surface to EGL_BUFFER_PRESERVED
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   422
is not possible for SDL as it requires EGL 1.4, available only on the API level
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   423
17+, so the only workaround available on this platform is to redraw the entire
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   424
screen each frame.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   425
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   426
Reference: http://www.khronos.org/registry/egl/specs/EGLTechNote0001.html
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   427
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   428
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   429
 Known issues
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   430
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   431
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   432
- TODO. I'm sure there's a bunch more stuff I haven't thought of