Updated the Android project template and README.android
authorSam Lantinga <slouken@libsdl.org>
Fri, 02 Nov 2012 02:37:49 -0700
changeset 663147ab7ba21530
parent 6630 55910871076b
child 6632 147f85ac2e4b
Updated the Android project template and README.android
Added information on how to customize your application name and icon.
Added information on using STL with an Android application
Increased the minimum API level to 10, because that's the lowest API
that currently has an emulator image for testing.
README.Platforms
README.android
android-project/AndroidManifest.xml
android-project/ant.properties
android-project/build.xml
android-project/default.properties
android-project/jni/Application.mk
android-project/local.properties
android-project/proguard-project.txt
android-project/project.properties
android-project/src/org/libsdl/app/SDLActivity.java
     1.1 --- a/README.Platforms	Fri Nov 02 02:22:32 2012 -0700
     1.2 +++ b/README.Platforms	Fri Nov 02 02:37:49 2012 -0700
     1.3 @@ -11,13 +11,12 @@
     1.4  Mac OS X 10.4+
     1.5  Linux 2.6+
     1.6  iOS 3.1.3+
     1.7 -Android 1.6+
     1.8 +Android 2.1+
     1.9  
    1.10  Unofficially supported platforms
    1.11  ================================
    1.12  (code compiles, but not thoroughly tested)
    1.13  ================================
    1.14 -Windows CE
    1.15  FreeBSD
    1.16  NetBSD
    1.17  OpenBSD
     2.1 --- a/README.android	Fri Nov 02 02:22:32 2012 -0700
     2.2 +++ b/README.android	Fri Nov 02 02:37:49 2012 -0700
     2.3 @@ -39,18 +39,16 @@
     2.4  
     2.5  Instructions:
     2.6  1. Copy the android-project directory wherever you want to keep your projects and rename it to the name of your project.
     2.7 -2. Move this SDL directory into the <project>/jni directory and then copy
     2.8 -SDL_config_android.h to SDL_config.h inside the include folder
     2.9 -3. Place your application source files in the <project>/jni/src directory
    2.10 -4. Edit <project>/jni/src/Android.mk to include your source files
    2.11 -5. Run 'ndk-build' (a script provided by the NDK). This compiles the C source
    2.12 +2. Move or symlink this SDL directory into the <project>/jni directory
    2.13 +3. Edit <project>/jni/src/Android.mk to include your source files
    2.14 +4. Run 'ndk-build' (a script provided by the NDK). This compiles the C source
    2.15  
    2.16  If you want to use the Eclipse IDE, skip to the Eclipse section below.
    2.17  
    2.18 -6. Edit <project>/local.properties to point to the Android SDK directory
    2.19 -7. Run 'ant debug' in android/project. This compiles the .java and eventually 
    2.20 +5. Edit <project>/local.properties to point to the Android SDK directory
    2.21 +6. Run 'ant debug' in android/project. This compiles the .java and eventually 
    2.22  creates a .apk with the native code embedded
    2.23 -8. 'ant install' will push the apk to the device or emulator (if connected)
    2.24 +7. 'ant install' will push the apk to the device or emulator (if connected)
    2.25  
    2.26  Here's an explanation of the files in the Android project, so you can customize them:
    2.27  
    2.28 @@ -74,6 +72,58 @@
    2.29  
    2.30  
    2.31  ================================================================================
    2.32 + Customizing your application name
    2.33 +================================================================================
    2.34 +
    2.35 +To customize your application name, edit AndroidManifest.xml and replace
    2.36 +"org.libsdl.app" with an identifier for your product package.
    2.37 +
    2.38 +Then create a Java class extending SDLActivity and place it in a directory
    2.39 +under src matching your package, e.g.
    2.40 +	src/com/gamemaker/game/MyGame.java
    2.41 +
    2.42 +Here's an example of a minimal class file:
    2.43 +--- MyGame.java --------------------------
    2.44 +package com.gamemaker.game;
    2.45 +
    2.46 +import org.libsdl.app.SDLActivity; 
    2.47 +import android.os.*; 
    2.48 +
    2.49 +/* 
    2.50 + * A sample wrapper class that just calls SDLActivity 
    2.51 + */ 
    2.52 +
    2.53 +public class MyGame extends SDLActivity { 
    2.54 +    protected void onCreate(Bundle savedInstanceState) { 
    2.55 +	super.onCreate(savedInstanceState); 
    2.56 +    } 
    2.57 +   
    2.58 +    protected void onDestroy() { 
    2.59 +	super.onDestroy(); 
    2.60 +    } 
    2.61 +}
    2.62 +------------------------------------------
    2.63 +
    2.64 +Then replace "SDLActivity" in AndroidManifest.xml with the name of your
    2.65 +class, .e.g. "MyGame"
    2.66 +
    2.67 +================================================================================
    2.68 + Customizing your application icon
    2.69 +================================================================================
    2.70 +
    2.71 +Conceptually changing your icon is just replacing the icon.png files in the
    2.72 +drawable directories under the res directory.
    2.73 +
    2.74 +The easiest way to create a set of icons for your project is to remove all
    2.75 +the existing icon.png files, and then use the Eclipse IDE to create a dummy
    2.76 +project.  During the process of doing this Eclipse will prompt you to create
    2.77 +an icon. Then just copy the drawable directories it creates over to your
    2.78 +res directory.
    2.79 +
    2.80 +You may need to change the name of your icon in AndroidManifest.xml to match
    2.81 +the filename used by Eclipse.
    2.82 +
    2.83 +================================================================================
    2.84   Pause / Resume behaviour
    2.85  ================================================================================
    2.86  
    2.87 @@ -106,6 +156,16 @@
    2.88  detach it.
    2.89  
    2.90  ================================================================================
    2.91 + Using STL
    2.92 +================================================================================
    2.93 +
    2.94 +You can use STL in your project by creating an Application.mk file in the jni
    2.95 +folder and adding the following line:
    2.96 +APP_STL := stlport_static
    2.97 +
    2.98 +For more information check out CPLUSPLUS-SUPPORT.html in the NDK documentation.
    2.99 +
   2.100 +================================================================================
   2.101   Additional documentation
   2.102  ================================================================================
   2.103  
     3.1 --- a/android-project/AndroidManifest.xml	Fri Nov 02 02:22:32 2012 -0700
     3.2 +++ b/android-project/AndroidManifest.xml	Fri Nov 02 02:37:49 2012 -0700
     3.3 @@ -1,12 +1,44 @@
     3.4  <?xml version="1.0" encoding="utf-8"?>
     3.5  <manifest xmlns:android="http://schemas.android.com/apk/res/android"
     3.6 +    <!-- Replace org.libsdl.app with the identifier of your game, e.g.
     3.7 +         com.gamemaker.game
     3.8 +     -->
     3.9        package="org.libsdl.app"
    3.10        android:versionCode="1"
    3.11 -      android:versionName="1.0">
    3.12 +      android:versionName="1.0"
    3.13 +      android:installLocation="auto">
    3.14  
    3.15 -    <uses-sdk android:minSdkVersion="5" />
    3.16 +    <!-- Create a Java class extending SDLActivity and place it in a
    3.17 +         directory under src matching the package, e.g.
    3.18 +         	src/com/gamemaker/game/MyGame.java
    3.19  
    3.20 -    <application android:label="@string/app_name" android:icon="@drawable/icon">
    3.21 +        /**********************************************************/
    3.22 +	package com.gamemaker.game;
    3.23 +
    3.24 +	import org.libsdl.app.SDLActivity; 
    3.25 +	import android.os.*; 
    3.26 +
    3.27 +	/* 
    3.28 +	 * A sample wrapper class that just calls SDLActivity 
    3.29 +	 */ 
    3.30 +
    3.31 +	public class MyGame extends SDLActivity { 
    3.32 +	    protected void onCreate(Bundle savedInstanceState) { 
    3.33 +	        super.onCreate(savedInstanceState); 
    3.34 +	    } 
    3.35 +	   
    3.36 +	    protected void onDestroy() { 
    3.37 +	        super.onDestroy(); 
    3.38 +	    } 
    3.39 +	}
    3.40 +        /**********************************************************/
    3.41 +
    3.42 +         then replace "SDLActivity" in the XML below with the name of
    3.43 +         your class, e.g. "MyGame" ...
    3.44 +    -->
    3.45 +    <application android:label="@string/app_name"
    3.46 +                 android:icon="@drawable/icon"
    3.47 +	         android:theme="@android:style/Theme.NoTitleBar.Fullscreen">
    3.48          <activity android:name="SDLActivity"
    3.49                    android:label="@string/app_name">
    3.50              <intent-filter>
    3.51 @@ -15,4 +47,13 @@
    3.52              </intent-filter>
    3.53          </activity>
    3.54      </application>
    3.55 +
    3.56 +    <!-- Android 2.1 -->
    3.57 +    <uses-sdk android:minSdkVersion="10" /> 
    3.58 +
    3.59 +    <!-- OpenGL ES 2.0 -->
    3.60 +    <uses-feature android:glEsVersion="0x00020000" /> 
    3.61 +
    3.62 +    <!-- Allow writing to external storage -->
    3.63 +    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" /> 
    3.64  </manifest> 
     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/android-project/ant.properties	Fri Nov 02 02:37:49 2012 -0700
     4.3 @@ -0,0 +1,17 @@
     4.4 +# This file is used to override default values used by the Ant build system.
     4.5 +#
     4.6 +# This file must be checked into Version Control Systems, as it is
     4.7 +# integral to the build system of your project.
     4.8 +
     4.9 +# This file is only used by the Ant script.
    4.10 +
    4.11 +# You can use this to override default values such as
    4.12 +#  'source.dir' for the location of your java source folder and
    4.13 +#  'out.dir' for the location of your output folder.
    4.14 +
    4.15 +# You can also use it define how the release builds are signed by declaring
    4.16 +# the following properties:
    4.17 +#  'key.store' for the location of your keystore and
    4.18 +#  'key.alias' for the name of the key to use.
    4.19 +# The password will be asked during the build when you use the 'release' target.
    4.20 +
     5.1 --- a/android-project/build.xml	Fri Nov 02 02:22:32 2012 -0700
     5.2 +++ b/android-project/build.xml	Fri Nov 02 02:37:49 2012 -0700
     5.3 @@ -1,67 +1,93 @@
     5.4  <?xml version="1.0" encoding="UTF-8"?>
     5.5 -<project name="SDLApp" default="help">
     5.6 +<!-- This should be changed to the name of your project -->
     5.7 +<project name="SDLActivity" default="help">
     5.8  
     5.9      <!-- The local.properties file is created and updated by the 'android' tool.
    5.10 -         It contains the path to the SDK. It should *NOT* be checked in in Version
    5.11 -         Control Systems. -->
    5.12 +         It contains the path to the SDK. It should *NOT* be checked into
    5.13 +         Version Control Systems. -->
    5.14      <property file="local.properties" />
    5.15  
    5.16 -    <!-- The build.properties file can be created by you and is never touched
    5.17 -         by the 'android' tool. This is the place to change some of the default property values
    5.18 -         used by the Ant rules.
    5.19 +    <!-- The ant.properties file can be created by you. It is only edited by the
    5.20 +         'android' tool to add properties to it.
    5.21 +         This is the place to change some Ant specific build properties.
    5.22           Here are some properties you may want to change/update:
    5.23  
    5.24 -         application.package
    5.25 -             the name of your application package as defined in the manifest. Used by the
    5.26 -             'uninstall' rule.
    5.27           source.dir
    5.28 -             the name of the source directory. Default is 'src'.
    5.29 +             The name of the source directory. Default is 'src'.
    5.30           out.dir
    5.31 -             the name of the output directory. Default is 'bin'.
    5.32 +             The name of the output directory. Default is 'bin'.
    5.33  
    5.34 -         Properties related to the SDK location or the project target should be updated
    5.35 -          using the 'android' tool with the 'update' action.
    5.36 +         For other overridable properties, look at the beginning of the rules
    5.37 +         files in the SDK, at tools/ant/build.xml
    5.38  
    5.39 -         This file is an integral part of the build system for your application and
    5.40 -         should be checked in in Version Control Systems.
    5.41 +         Properties related to the SDK location or the project target should
    5.42 +         be updated using the 'android' tool with the 'update' action.
    5.43 +
    5.44 +         This file is an integral part of the build system for your
    5.45 +         application and should be checked into Version Control Systems.
    5.46  
    5.47           -->
    5.48 -    <property file="build.properties" />
    5.49 +    <property file="ant.properties" />
    5.50  
    5.51 -    <!-- The default.properties file is created and updated by the 'android' tool, as well
    5.52 -         as ADT.
    5.53 -         This file is an integral part of the build system for your application and
    5.54 -         should be checked in in Version Control Systems. -->
    5.55 -    <property file="default.properties" />
    5.56 +    <!-- if sdk.dir was not set from one of the property file, then
    5.57 +         get it from the ANDROID_HOME env var.
    5.58 +         This must be done before we load project.properties since
    5.59 +         the proguard config can use sdk.dir -->
    5.60 +    <property environment="env" />
    5.61 +    <condition property="sdk.dir" value="${env.ANDROID_HOME}">
    5.62 +        <isset property="env.ANDROID_HOME" />
    5.63 +    </condition>
    5.64  
    5.65 -    <!-- Custom Android task to deal with the project target, and import the proper rules.
    5.66 -         This requires ant 1.6.0 or above. -->
    5.67 -    <path id="android.antlibs">
    5.68 -        <pathelement path="${sdk.dir}/tools/lib/anttasks.jar" />
    5.69 -        <pathelement path="${sdk.dir}/tools/lib/sdklib.jar" />
    5.70 -        <pathelement path="${sdk.dir}/tools/lib/androidprefs.jar" />
    5.71 -        <pathelement path="${sdk.dir}/tools/lib/apkbuilder.jar" />
    5.72 -        <pathelement path="${sdk.dir}/tools/lib/jarutils.jar" />
    5.73 -    </path>
    5.74 +    <!-- The project.properties file is created and updated by the 'android'
    5.75 +         tool, as well as ADT.
    5.76  
    5.77 -    <taskdef name="setup"
    5.78 -        classname="com.android.ant.SetupTask"
    5.79 -        classpathref="android.antlibs" />
    5.80 +         This contains project specific properties such as project target, and library
    5.81 +         dependencies. Lower level build properties are stored in ant.properties
    5.82 +         (or in .classpath for Eclipse projects).
    5.83  
    5.84 -    <!-- Execute the Android Setup task that will setup some properties specific to the target,
    5.85 -         and import the build rules files.
    5.86 +         This file is an integral part of the build system for your
    5.87 +         application and should be checked into Version Control Systems. -->
    5.88 +    <loadproperties srcFile="project.properties" />
    5.89  
    5.90 -         The rules file is imported from
    5.91 -            <SDK>/platforms/<target_platform>/templates/android_rules.xml
    5.92 +    <!-- quick check on sdk.dir -->
    5.93 +    <fail
    5.94 +            message="sdk.dir is missing. Make sure to generate local.properties using 'android update project' or to inject it through the ANDROID_HOME environment variable."
    5.95 +            unless="sdk.dir"
    5.96 +    />
    5.97  
    5.98 -         To customize some build steps for your project:
    5.99 -         - copy the content of the main node <project> from android_rules.xml
   5.100 -         - paste it in this build.xml below the <setup /> task.
   5.101 -         - disable the import by changing the setup task below to <setup import="false" />
   5.102 +    <!--
   5.103 +        Import per project custom build rules if present at the root of the project.
   5.104 +        This is the place to put custom intermediary targets such as:
   5.105 +            -pre-build
   5.106 +            -pre-compile
   5.107 +            -post-compile (This is typically used for code obfuscation.
   5.108 +                           Compiled code location: ${out.classes.absolute.dir}
   5.109 +                           If this is not done in place, override ${out.dex.input.absolute.dir})
   5.110 +            -post-package
   5.111 +            -post-build
   5.112 +            -pre-clean
   5.113 +    -->
   5.114 +    <import file="custom_rules.xml" optional="true" />
   5.115  
   5.116 -         This will ensure that the properties are setup correctly but that your customized
   5.117 -         build steps are used.
   5.118 +    <!-- Import the actual build file.
   5.119 +
   5.120 +         To customize existing targets, there are two options:
   5.121 +         - Customize only one target:
   5.122 +             - copy/paste the target into this file, *before* the
   5.123 +               <import> task.
   5.124 +             - customize it to your needs.
   5.125 +         - Customize the whole content of build.xml
   5.126 +             - copy/paste the content of the rules files (minus the top node)
   5.127 +               into this file, replacing the <import> task.
   5.128 +             - customize to your needs.
   5.129 +
   5.130 +         ***********************
   5.131 +         ****** IMPORTANT ******
   5.132 +         ***********************
   5.133 +         In all cases you must update the value of version-tag below to read 'custom' instead of an integer,
   5.134 +         in order to avoid having your file be overridden by tools such as "android update project"
   5.135      -->
   5.136 -    <setup />
   5.137 +    <!-- version-tag: 1 -->
   5.138 +    <import file="${sdk.dir}/tools/ant/build.xml" />
   5.139  
   5.140  </project>
     6.1 --- a/android-project/default.properties	Fri Nov 02 02:22:32 2012 -0700
     6.2 +++ b/android-project/default.properties	Fri Nov 02 02:37:49 2012 -0700
     6.3 @@ -8,4 +8,4 @@
     6.4  # project structure.
     6.5  
     6.6  # Project target.
     6.7 -target=android-5
     6.8 +target=android-7
     7.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     7.2 +++ b/android-project/jni/Application.mk	Fri Nov 02 02:37:49 2012 -0700
     7.3 @@ -0,0 +1,4 @@
     7.4 +
     7.5 +# Uncomment this if you're using STL in your project
     7.6 +# See CPLUSPLUS-SUPPORT.html in the NDK documentation for more information
     7.7 +# APP_STL := stlport_static 
     8.1 --- a/android-project/local.properties	Fri Nov 02 02:22:32 2012 -0700
     8.2 +++ b/android-project/local.properties	Fri Nov 02 02:37:49 2012 -0700
     8.3 @@ -7,4 +7,4 @@
     8.4  # location of the SDK. This is only used by Ant
     8.5  # For customization when using a Version Control System, please read the
     8.6  # header note.
     8.7 -sdk.dir=/Users/hercules/eclipse/android-sdk-mac_86
     8.8 +sdk.dir=/Users/slouken/android-sdk-macosx
     9.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     9.2 +++ b/android-project/proguard-project.txt	Fri Nov 02 02:37:49 2012 -0700
     9.3 @@ -0,0 +1,20 @@
     9.4 +# To enable ProGuard in your project, edit project.properties
     9.5 +# to define the proguard.config property as described in that file.
     9.6 +#
     9.7 +# Add project specific ProGuard rules here.
     9.8 +# By default, the flags in this file are appended to flags specified
     9.9 +# in ${sdk.dir}/tools/proguard/proguard-android.txt
    9.10 +# You can edit the include path and order by changing the ProGuard
    9.11 +# include property in project.properties.
    9.12 +#
    9.13 +# For more details, see
    9.14 +#   http://developer.android.com/guide/developing/tools/proguard.html
    9.15 +
    9.16 +# Add any project specific keep options here:
    9.17 +
    9.18 +# If your project uses WebView with JS, uncomment the following
    9.19 +# and specify the fully qualified class name to the JavaScript interface
    9.20 +# class:
    9.21 +#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
    9.22 +#   public *;
    9.23 +#}
    10.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
    10.2 +++ b/android-project/project.properties	Fri Nov 02 02:37:49 2012 -0700
    10.3 @@ -0,0 +1,14 @@
    10.4 +# This file is automatically generated by Android Tools.
    10.5 +# Do not modify this file -- YOUR CHANGES WILL BE ERASED!
    10.6 +#
    10.7 +# This file must be checked in Version Control Systems.
    10.8 +#
    10.9 +# To customize properties used by the Ant build system edit
   10.10 +# "ant.properties", and override values to adapt the script to your
   10.11 +# project structure.
   10.12 +#
   10.13 +# To enable ProGuard to shrink and obfuscate your code, uncomment this (available properties: sdk.dir, user.home):
   10.14 +#proguard.config=${sdk.dir}/tools/proguard/proguard-android.txt:proguard-project.txt
   10.15 +
   10.16 +# Project target.
   10.17 +target=android-10
    11.1 --- a/android-project/src/org/libsdl/app/SDLActivity.java	Fri Nov 02 02:22:32 2012 -0700
    11.2 +++ b/android-project/src/org/libsdl/app/SDLActivity.java	Fri Nov 02 02:37:49 2012 -0700
    11.3 @@ -734,7 +734,7 @@
    11.4          ic = new SDLInputConnection(this, true);
    11.5  
    11.6          outAttrs.imeOptions = EditorInfo.IME_FLAG_NO_EXTRACT_UI
    11.7 -                | EditorInfo.IME_FLAG_NO_FULLSCREEN;
    11.8 +                | 33554432 /* API 11: EditorInfo.IME_FLAG_NO_FULLSCREEN */;
    11.9  
   11.10          return ic;
   11.11      }