README.android
author Sam Lantinga <slouken@libsdl.org>
Thu, 06 Jan 2011 17:12:31 -0800
changeset 4965 91d0085b7560
parent 4964 6c645018741e
child 4967 f74a3f94c408
permissions -rw-r--r--
Added the Android project and lots of info to README.android
paul@4727
     1
================================================================================
paul@4726
     2
Simple DirectMedia Layer for Android
paul@4727
     3
================================================================================
paul@4725
     4
slouken@4965
     5
Requirements:
slouken@4965
     6
slouken@4965
     7
Android SDK
slouken@4965
     8
http://developer.android.com/sdk/index.html
slouken@4965
     9
slouken@4965
    10
Android NDK r4 or later
slouken@4965
    11
http://developer.android.com/sdk/ndk/index.html
paul@4725
    12
paul@4727
    13
================================================================================
paul@4727
    14
 How the port works
paul@4727
    15
================================================================================
paul@4727
    16
paul@4727
    17
- Android applications are Java-based, optionally with parts written in C
paul@4727
    18
- As SDL apps are C-based, we use a small Java shim that uses JNI to talk to 
paul@4727
    19
the SDL library
paul@4727
    20
- This means that your application C code must be placed inside an android 
paul@4727
    21
Java project, along with some C support code that communicates with Java
paul@4727
    22
- This eventually produces a standard Android .apk package
paul@4727
    23
paul@4727
    24
paul@4727
    25
================================================================================
paul@4727
    26
 Building an app
paul@4727
    27
================================================================================
paul@4727
    28
paul@4725
    29
Instructions:
slouken@4965
    30
1. Copy the android-project directory wherever you want to keep your projects and rename it to the name of your project.
slouken@4964
    31
2. Move this SDL directory into the <project>/jni directory
slouken@4964
    32
3. Place your application source files in the <project>/jni/src directory
slouken@4964
    33
4. Edit <project>/jni/src/Android.mk to include your source files
paul@4727
    34
5. Run 'ndk-build' (a script provided by the NDK). This compiles the C source
paul@4725
    35
slouken@4964
    36
If you want to use the Eclipse IDE, skip to the Eclipse section below.
paul@4725
    37
slouken@4964
    38
6. Edit <project>/local.properties to point to the Android SDK directory
slouken@4964
    39
7. Run 'ant debug' in android/project. This compiles the .java and eventually 
slouken@4964
    40
creates a .apk with the native code embedded
slouken@4964
    41
8. 'ant install' will push the apk to the device or emulator (if connected)
slouken@4964
    42
slouken@4965
    43
Here's an explanation of the files in the Android project, so you can customize them:
slouken@4965
    44
slouken@4965
    45
android-project/
slouken@4965
    46
	AndroidManifest.xml	- package manifest, do not modify
slouken@4965
    47
	build.properties	- empty
slouken@4965
    48
	build.xml		- build description file, used by ant
slouken@4965
    49
	default.properties	- holds the ABI for the application, currently android-4 which corresponds to the Android 1.6 system image
slouken@4965
    50
	local.properties	- holds the SDK path, you should change this to the path to your SDK
slouken@4965
    51
	jni/			- directory holding native code and Android.mk
slouken@4965
    52
	jni/Android.mk		- Android makefile that includes all subdirectories
slouken@4965
    53
	jni/SDL/		- directory holding the SDL library files
slouken@4965
    54
	jni/SDL/Android.mk	- Android makefile for creating the SDL shared library
slouken@4965
    55
	jni/src/		- directory holding your application source
slouken@4965
    56
	jni/src/Android.mk	- Android makefile that you should customize to include your source code and any library references
slouken@4965
    57
	res/			- directory holding resources for your application
slouken@4965
    58
	res/drawable-*		- directories holding icons for different phone hardware
slouken@4965
    59
	res/layout/main.xml	- place holder for the main screen layout, overridden by the SDL video output
slouken@4965
    60
	res/values/strings.xml	- strings used in your application, including the application name shown on the phone.
slouken@4965
    61
	src/org/libsdl/app/SDLActivity.java	- the Java class handling the initialization and binding to SDL.  Be very careful changing this, as the SDL library relies on this implementation.
slouken@4965
    62
slouken@4965
    63
slouken@4965
    64
================================================================================
slouken@4965
    65
 Additional documentation
slouken@4965
    66
================================================================================
slouken@4965
    67
slouken@4965
    68
The documentation in the NDK docs directory is very helpful in understanding the build process and how to work with native code on the Android platform.
slouken@4965
    69
slouken@4965
    70
The best place to start is with docs/OVERVIEW.TXT
slouken@4965
    71
slouken@4964
    72
slouken@4964
    73
================================================================================
slouken@4964
    74
 Using Eclipse
slouken@4964
    75
================================================================================
slouken@4964
    76
slouken@4965
    77
First make sure that you've installed Eclipse and the Android extensions as described here:
slouken@4965
    78
	http://developer.android.com/sdk/eclipse-adt.html
slouken@4965
    79
slouken@4965
    80
Once you've copied the SDL android project and customized it, you can create an Eclipse project from it:
slouken@4965
    81
 * File -> New -> Other
slouken@4965
    82
 * Select the Android -> Android Project wizard and click Next
slouken@4965
    83
 * Enter the name you'd like your project to have
slouken@4965
    84
 * Select "Create project from existing source" and browse for your project directory
slouken@4965
    85
 * Make sure the Build Target is set to Android 1.6
slouken@4965
    86
 * Click Finish
slouken@4964
    87
slouken@4964
    88
slouken@4964
    89
================================================================================
slouken@4965
    90
 Loading files and resources
slouken@4964
    91
================================================================================
slouken@4964
    92
slouken@4964
    93
NEED CONTENT
slouken@4964
    94
slouken@4964
    95
slouken@4964
    96
================================================================================
slouken@4964
    97
 Troubleshooting
slouken@4964
    98
================================================================================
slouken@4964
    99
slouken@4965
   100
You can create and run an emulator from the Eclipse IDE:
slouken@4965
   101
 * Window -> Android SDK and AVD Manager
slouken@4965
   102
slouken@4965
   103
You can see if adb can see any devices with the following command:
slouken@4965
   104
	adb devices
slouken@4965
   105
slouken@4965
   106
You can see the output of log messages on the default device with:
slouken@4965
   107
	adb logcat
slouken@4965
   108
slouken@4965
   109
You can push files to the device with:
slouken@4965
   110
	adb push local_file remote_path_and_file
slouken@4965
   111
slouken@4965
   112
You can push files to the SD Card at /sdcard, for example:
slouken@4965
   113
	adb push moose.dat /sdcard/moose.dat
paul@4727
   114
paul@4727
   115
paul@4727
   116
================================================================================
paul@4727
   117
 Known issues
paul@4727
   118
================================================================================
paul@4727
   119
paul@4727
   120
- SDL audio (although it's mostly written, just not working properly yet)
paul@4727
   121
- TODO. I'm sure there's a bunch more stuff I haven't thought of