README-android.txt
author Gabriel Jacobo <gabomdq@gmail.com>
Wed, 09 Oct 2013 10:29:01 -0300
changeset 7793 6463a850229d
parent 7501 b27825bb5879
child 7804 1f85fb33694b
permissions -rw-r--r--
Adds test framework to Android.mk and a simple utility to build Android projects
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
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   114
 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
   115
================================================================================
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   116
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   117
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
   118
"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
   119
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   120
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
   121
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
   122
	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
   123
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   124
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
   125
--- 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
   126
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
   127
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   128
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
   129
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   130
/* 
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   131
 * 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
   132
 */ 
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   133
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 7166
diff changeset
   134
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
   135
2435b221d77d Renamed documentation files to .txt 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
------------------------------------------
2435b221d77d Renamed documentation files to .txt 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
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
   139
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
   140
2435b221d77d Renamed documentation files to .txt 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
 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
   143
================================================================================
2435b221d77d Renamed documentation files to .txt 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
2435b221d77d Renamed documentation files to .txt 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
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
   146
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
   147
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
   148
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
   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
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
   151
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
   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
================================================================================
2435b221d77d Renamed documentation files to .txt 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
 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
   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
2435b221d77d Renamed documentation files to .txt 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
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
   158
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
   159
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
   160
2435b221d77d Renamed documentation files to .txt 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
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
   162
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
   163
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
   164
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
   165
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
   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
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
   168
2435b221d77d Renamed documentation files to .txt 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
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
   170
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
   171
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
   172
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
   173
"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
   174
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
   175
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
   176
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
   177
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
   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
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
   180
2435b221d77d Renamed documentation files to .txt 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
================================================================================
2435b221d77d Renamed documentation files to .txt 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
 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
   183
================================================================================
2435b221d77d Renamed documentation files to .txt 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
2435b221d77d Renamed documentation files to .txt 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
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
   186
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
   187
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
   188
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
   189
(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
   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
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
   192
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
   193
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
   194
2435b221d77d Renamed documentation files to .txt 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
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
   196
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
   197
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
   198
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
   199
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
   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
================================================================================
2435b221d77d Renamed documentation files to .txt 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
 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
   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
2435b221d77d Renamed documentation files to .txt 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
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
   206
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
   207
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
   208
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
   209
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
   210
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
   211
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
   212
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
   213
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
   214
2435b221d77d Renamed documentation files to .txt 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
================================================================================
2435b221d77d Renamed documentation files to .txt 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
 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
   217
================================================================================
2435b221d77d Renamed documentation files to .txt 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
2435b221d77d Renamed documentation files to .txt 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
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
   220
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
   221
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
   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
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
   224
2435b221d77d Renamed documentation files to .txt 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
 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
   227
================================================================================
2435b221d77d Renamed documentation files to .txt 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
2435b221d77d Renamed documentation files to .txt 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
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
   230
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
   231
2435b221d77d Renamed documentation files to .txt 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
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
   233
2435b221d77d Renamed documentation files to .txt 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
2435b221d77d Renamed documentation files to .txt 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
================================================================================
2435b221d77d Renamed documentation files to .txt 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
 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
   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
2435b221d77d Renamed documentation files to .txt 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
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
   240
	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
   241
2435b221d77d Renamed documentation files to .txt 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
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
   243
 * 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
   244
 * 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
   245
 * 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
   246
 * 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
   247
 * 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
   248
 * 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
   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
================================================================================
2435b221d77d Renamed documentation files to .txt 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
 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
   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
2435b221d77d Renamed documentation files to .txt 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
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
   256
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
   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
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
   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
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
   261
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
   262
2435b221d77d Renamed documentation files to .txt 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
 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
   265
================================================================================
2435b221d77d Renamed documentation files to .txt 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
2435b221d77d Renamed documentation files to .txt 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
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
   268
 * 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
   269
2435b221d77d Renamed documentation files to .txt 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
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
   271
	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
   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
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
   274
	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
   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
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
   277
	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
   278
2435b221d77d Renamed documentation files to .txt 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
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
   280
	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
   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
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
   283
	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
   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
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
   286
	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
   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
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
   289
	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
   290
2435b221d77d Renamed documentation files to .txt 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
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
   292
	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
   293
2435b221d77d Renamed documentation files to .txt 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
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
   295
	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
   296
2435b221d77d Renamed documentation files to .txt 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
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
   298
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
   299
2435b221d77d Renamed documentation files to .txt 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
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
   301
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
   302
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
   303
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
   304
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
   305
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
   306
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
   307
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
   308
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
   309
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
   310
2435b221d77d Renamed documentation files to .txt 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
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
   312
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
   313
	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
   314
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
   315
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
   316
2435b221d77d Renamed documentation files to .txt 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
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
   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
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
   320
2435b221d77d Renamed documentation files to .txt 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
#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
   322
2435b221d77d Renamed documentation files to .txt 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
	__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
   324
2435b221d77d Renamed documentation files to .txt 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
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
   326
"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
   327
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
   328
2435b221d77d Renamed documentation files to .txt 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
2435b221d77d Renamed documentation files to .txt 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
================================================================================
2435b221d77d Renamed documentation files to .txt 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
 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
   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
2435b221d77d Renamed documentation files to .txt 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
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
   335
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
   336
	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
   337
... 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
   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
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
   340
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
   341
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
   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
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
   344
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
   345
--- 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
   346
#!/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
   347
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
   348
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
   349
------------------------------------------
2435b221d77d Renamed documentation files to .txt 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
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
   352
	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
   353
2435b221d77d Renamed documentation files to .txt 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
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
   355
	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
   356
2435b221d77d Renamed documentation files to .txt 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
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
   358
	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
   359
2435b221d77d Renamed documentation files to .txt 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
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
   361
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
   362
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
   363
2435b221d77d Renamed documentation files to .txt 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
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
   365
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
   366
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
   367
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
   368
	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
   369
2435b221d77d Renamed documentation files to .txt 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
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
   371
	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
   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
================================================================================
2435b221d77d Renamed documentation files to .txt 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
 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
   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
2435b221d77d Renamed documentation files to .txt 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
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
   378
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
   379
2435b221d77d Renamed documentation files to .txt 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
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
   381
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
   382
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
   383
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
   384
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
   385
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
   386
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
   387
2435b221d77d Renamed documentation files to .txt 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
================================================================================
2435b221d77d Renamed documentation files to .txt 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
 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
   390
================================================================================
2435b221d77d Renamed documentation files to .txt 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
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
   393
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
   394
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
   395
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
   396
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
   397
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
   398
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
   399
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
   400
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
   401
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
   402
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
   403
2435b221d77d Renamed documentation files to .txt 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
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
   405
2435b221d77d Renamed documentation files to .txt 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
================================================================================
2435b221d77d Renamed documentation files to .txt 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
 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
   408
================================================================================
2435b221d77d Renamed documentation files to .txt 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
- TODO. I'm sure there's a bunch more stuff I haven't thought of