Added the Android project and lots of info to README.android

libsdl-org · Jan 7, 2011 · 69a41fa · 69a41fa
1 parent ef311c6
commit 69a41fa
Show file tree

Hide file tree

Showing 14 changed files with 608 additions and 6 deletions.
diff --git a/README.android b/README.android
@@ -2,8 +2,13 @@
 Simple DirectMedia Layer for Android
 ================================================================================
 
-Requirements: Android SDK and Android NDK r4 or later
-http://developer.android.com/
+Requirements:
+
+Android SDK
+http://developer.android.com/sdk/index.html
+
+Android NDK r4 or later
+http://developer.android.com/sdk/ndk/index.html
 
 ================================================================================
  How the port works
@@ -22,7 +27,7 @@ Java project, along with some C support code that communicates with Java
 ================================================================================
 
 Instructions:
-1. Copy the android-project directory wherever you want your Android project to go
+1. Copy the android-project directory wherever you want to keep your projects and rename it to the name of your project.
 2. Move this SDL directory into the <project>/jni directory
 3. Place your application source files in the <project>/jni/src directory
 4. Edit <project>/jni/src/Android.mk to include your source files
@@ -35,16 +40,54 @@ If you want to use the Eclipse IDE, skip to the Eclipse section below.
 creates a .apk with the native code embedded
 8. 'ant install' will push the apk to the device or emulator (if connected)
 
+Here's an explanation of the files in the Android project, so you can customize them:
+
+android-project/
+	AndroidManifest.xml	- package manifest, do not modify
+	build.properties	- empty
+	build.xml		- build description file, used by ant
+	default.properties	- holds the ABI for the application, currently android-4 which corresponds to the Android 1.6 system image
+	local.properties	- holds the SDK path, you should change this to the path to your SDK
+	jni/			- directory holding native code and Android.mk
+	jni/Android.mk		- Android makefile that includes all subdirectories
+	jni/SDL/		- directory holding the SDL library files
+	jni/SDL/Android.mk	- Android makefile for creating the SDL shared library
+	jni/src/		- directory holding your application source
+	jni/src/Android.mk	- Android makefile that you should customize to include your source code and any library references
+	res/			- directory holding resources for your application
+	res/drawable-*		- directories holding icons for different phone hardware
+	res/layout/main.xml	- place holder for the main screen layout, overridden by the SDL video output
+	res/values/strings.xml	- strings used in your application, including the application name shown on the phone.
+	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.
+
+
+================================================================================
+ Additional documentation
+================================================================================
+
+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.
+
+The best place to start is with docs/OVERVIEW.TXT
+
 
 ================================================================================
  Using Eclipse
 ================================================================================
 
-NEED CONTENT
+First make sure that you've installed Eclipse and the Android extensions as described here:
+	http://developer.android.com/sdk/eclipse-adt.html
+
+Once you've copied the SDL android project and customized it, you can create an Eclipse project from it:
+ * File -> New -> Other
+ * Select the Android -> Android Project wizard and click Next
+ * Enter the name you'd like your project to have
+ * Select "Create project from existing source" and browse for your project directory
+ * Make sure the Build Target is set to Android 1.6
+ * Click Finish
 
 
 ================================================================================
- Loading files
+ Loading files and resources
 ================================================================================
 
 NEED CONTENT
@@ -54,7 +97,20 @@ NEED CONTENT
  Troubleshooting
 ================================================================================
 
-NEED CONTENT
+You can create and run an emulator from the Eclipse IDE:
+ * Window -> Android SDK and AVD Manager
+
+You can see if adb can see any devices with the following command:
+	adb devices
+
+You can see the output of log messages on the default device with:
+	adb logcat
+
+You can push files to the device with:
+	adb push local_file remote_path_and_file
+
+You can push files to the SD Card at /sdcard, for example:
+	adb push moose.dat /sdcard/moose.dat
 
 
 ================================================================================

diff --git a/android-project/AndroidManifest.xml b/android-project/AndroidManifest.xml
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+      package="org.libsdl.app"
+      android:versionCode="1"
+      android:versionName="1.0">
+    <application android:label="@string/app_name" android:icon="@drawable/icon">
+        <activity android:name="SDLActivity"
+                  android:label="@string/app_name">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
+</manifest> 
diff --git a/android-project/build.properties b/android-project/build.properties
@@ -0,0 +1,17 @@
+# This file is used to override default values used by the Ant build system.
+# 
+# This file must be checked in Version Control Systems, as it is
+# integral to the build system of your project.
+
+# This file is only used by the Ant script.
+
+# You can use this to override default values such as
+#  'source.dir' for the location of your java source folder and
+#  'out.dir' for the location of your output folder.
+
+# You can also use it define how the release builds are signed by declaring
+# the following properties:
+#  'key.store' for the location of your keystore and
+#  'key.alias' for the name of the key to use.
+# The password will be asked during the build when you use the 'release' target.
+
diff --git a/android-project/build.xml b/android-project/build.xml
@@ -0,0 +1,67 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project name="SDLApp" default="help">
+
+    <!-- The local.properties file is created and updated by the 'android' tool.
+         It contains the path to the SDK. It should *NOT* be checked in in Version
+         Control Systems. -->
+    <property file="local.properties" />
+
+    <!-- The build.properties file can be created by you and is never touched
+         by the 'android' tool. This is the place to change some of the default property values
+         used by the Ant rules.
+         Here are some properties you may want to change/update:
+
+         application.package
+             the name of your application package as defined in the manifest. Used by the
+             'uninstall' rule.
+         source.dir
+             the name of the source directory. Default is 'src'.
+         out.dir
+             the name of the output directory. Default is 'bin'.
+
+         Properties related to the SDK location or the project target should be updated
+          using the 'android' tool with the 'update' action.
+
+         This file is an integral part of the build system for your application and
+         should be checked in in Version Control Systems.
+
+         -->
+    <property file="build.properties" />
+
+    <!-- The default.properties file is created and updated by the 'android' tool, as well
+         as ADT.
+         This file is an integral part of the build system for your application and
+         should be checked in in Version Control Systems. -->
+    <property file="default.properties" />
+
+    <!-- Custom Android task to deal with the project target, and import the proper rules.
+         This requires ant 1.6.0 or above. -->
+    <path id="android.antlibs">
+        <pathelement path="${sdk.dir}/tools/lib/anttasks.jar" />
+        <pathelement path="${sdk.dir}/tools/lib/sdklib.jar" />
+        <pathelement path="${sdk.dir}/tools/lib/androidprefs.jar" />
+        <pathelement path="${sdk.dir}/tools/lib/apkbuilder.jar" />
+        <pathelement path="${sdk.dir}/tools/lib/jarutils.jar" />
+    </path>
+
+    <taskdef name="setup"
+        classname="com.android.ant.SetupTask"
+        classpathref="android.antlibs" />
+
+    <!-- Execute the Android Setup task that will setup some properties specific to the target,
+         and import the build rules files.
+
+         The rules file is imported from
+            <SDK>/platforms/<target_platform>/templates/android_rules.xml
+
+         To customize some build steps for your project:
+         - copy the content of the main node <project> from android_rules.xml
+         - paste it in this build.xml below the <setup /> task.
+         - disable the import by changing the setup task below to <setup import="false" />
+
+         This will ensure that the properties are setup correctly but that your customized
+         build steps are used.
+    -->
+    <setup />
+
+</project>
diff --git a/android-project/default.properties b/android-project/default.properties
@@ -0,0 +1,11 @@
+# This file is automatically generated by Android Tools.
+# Do not modify this file -- YOUR CHANGES WILL BE ERASED!
+# 
+# This file must be checked in Version Control Systems.
+# 
+# To customize properties used by the Ant build system use,
+# "build.properties", and override values to adapt the script to your
+# project structure.
+
+# Project target.
+target=android-4
diff --git a/android-project/jni/Android.mk b/android-project/jni/Android.mk
@@ -0,0 +1 @@
+include $(call all-subdir-makefiles)
diff --git a/android-project/jni/src/Android.mk b/android-project/jni/src/Android.mk
@@ -0,0 +1,19 @@
+LOCAL_PATH := $(call my-dir)
+
+include $(CLEAR_VARS)
+
+LOCAL_MODULE := main
+
+SDL_PATH := ../SDL
+
+LOCAL_C_INCLUDES := $(LOCAL_PATH)/$(SDL_PATH)/include
+
+# Add your application source files here...
+LOCAL_SRC_FILES := $(SDL_PATH)/src/main/android/SDL_android_main.cpp \
+	YourSourceHere.c
+
+LOCAL_SHARED_LIBRARIES := SDL
+
+LOCAL_LDLIBS := -lGLESv1_CM -llog
+
+include $(BUILD_SHARED_LIBRARY)
diff --git a/android-project/local.properties b/android-project/local.properties
@@ -0,0 +1,10 @@
+# This file is automatically generated by Android Tools.
+# Do not modify this file -- YOUR CHANGES WILL BE ERASED!
+# 
+# This file must *NOT* be checked in Version Control Systems,
+# as it contains information specific to your local configuration.
+
+# location of the SDK. This is only used by Ant
+# For customization when using a Version Control System, please read the
+# header note.
+sdk.dir=/Users/hercules/eclipse/android-sdk-mac_86
diff --git a/android-project/res/drawable-hdpi/icon.png b/android-project/res/drawable-hdpi/icon.png
diff --git a/android-project/res/drawable-ldpi/icon.png b/android-project/res/drawable-ldpi/icon.png
diff --git a/android-project/res/drawable-mdpi/icon.png b/android-project/res/drawable-mdpi/icon.png
diff --git a/android-project/res/layout/main.xml b/android-project/res/layout/main.xml
@@ -0,0 +1,13 @@
+<?xml version="1.0" encoding="utf-8"?>
+<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
+    android:orientation="vertical"
+    android:layout_width="fill_parent"
+    android:layout_height="fill_parent"
+    >
+<TextView  
+    android:layout_width="fill_parent" 
+    android:layout_height="wrap_content" 
+    android:text="Hello World, SDLActivity"
+    />
+</LinearLayout>
+
diff --git a/android-project/res/values/strings.xml b/android-project/res/values/strings.xml
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="app_name">SDL App</string>
+</resources>