README.android
changeset 6631 47ab7ba21530
parent 6387 58f0fb54bf88
child 6646 dd32cce44d3c
equal deleted inserted replaced
6630:55910871076b 6631:47ab7ba21530
    37  Building an app
    37  Building an app
    38 ================================================================================
    38 ================================================================================
    39 
    39 
    40 Instructions:
    40 Instructions:
    41 1. Copy the android-project directory wherever you want to keep your projects and rename it to the name of your project.
    41 1. Copy the android-project directory wherever you want to keep your projects and rename it to the name of your project.
    42 2. Move this SDL directory into the <project>/jni directory and then copy
    42 2. Move or symlink this SDL directory into the <project>/jni directory
    43 SDL_config_android.h to SDL_config.h inside the include folder
    43 3. Edit <project>/jni/src/Android.mk to include your source files
    44 3. Place your application source files in the <project>/jni/src directory
    44 4. Run 'ndk-build' (a script provided by the NDK). This compiles the C source
    45 4. Edit <project>/jni/src/Android.mk to include your source files
       
    46 5. Run 'ndk-build' (a script provided by the NDK). This compiles the C source
       
    47 
    45 
    48 If you want to use the Eclipse IDE, skip to the Eclipse section below.
    46 If you want to use the Eclipse IDE, skip to the Eclipse section below.
    49 
    47 
    50 6. Edit <project>/local.properties to point to the Android SDK directory
    48 5. Edit <project>/local.properties to point to the Android SDK directory
    51 7. Run 'ant debug' in android/project. This compiles the .java and eventually 
    49 6. Run 'ant debug' in android/project. This compiles the .java and eventually 
    52 creates a .apk with the native code embedded
    50 creates a .apk with the native code embedded
    53 8. 'ant install' will push the apk to the device or emulator (if connected)
    51 7. 'ant install' will push the apk to the device or emulator (if connected)
    54 
    52 
    55 Here's an explanation of the files in the Android project, so you can customize them:
    53 Here's an explanation of the files in the Android project, so you can customize them:
    56 
    54 
    57 android-project/
    55 android-project/
    58 	AndroidManifest.xml	- package manifest, do not modify
    56 	AndroidManifest.xml	- package manifest, do not modify
    72 	res/values/strings.xml	- strings used in your application, including the application name shown on the phone.
    70 	res/values/strings.xml	- strings used in your application, including the application name shown on the phone.
    73 	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.
    71 	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.
    74 
    72 
    75 
    73 
    76 ================================================================================
    74 ================================================================================
       
    75  Customizing your application name
       
    76 ================================================================================
       
    77 
       
    78 To customize your application name, edit AndroidManifest.xml and replace
       
    79 "org.libsdl.app" with an identifier for your product package.
       
    80 
       
    81 Then create a Java class extending SDLActivity and place it in a directory
       
    82 under src matching your package, e.g.
       
    83 	src/com/gamemaker/game/MyGame.java
       
    84 
       
    85 Here's an example of a minimal class file:
       
    86 --- MyGame.java --------------------------
       
    87 package com.gamemaker.game;
       
    88 
       
    89 import org.libsdl.app.SDLActivity; 
       
    90 import android.os.*; 
       
    91 
       
    92 /* 
       
    93  * A sample wrapper class that just calls SDLActivity 
       
    94  */ 
       
    95 
       
    96 public class MyGame extends SDLActivity { 
       
    97     protected void onCreate(Bundle savedInstanceState) { 
       
    98 	super.onCreate(savedInstanceState); 
       
    99     } 
       
   100    
       
   101     protected void onDestroy() { 
       
   102 	super.onDestroy(); 
       
   103     } 
       
   104 }
       
   105 ------------------------------------------
       
   106 
       
   107 Then replace "SDLActivity" in AndroidManifest.xml with the name of your
       
   108 class, .e.g. "MyGame"
       
   109 
       
   110 ================================================================================
       
   111  Customizing your application icon
       
   112 ================================================================================
       
   113 
       
   114 Conceptually changing your icon is just replacing the icon.png files in the
       
   115 drawable directories under the res directory.
       
   116 
       
   117 The easiest way to create a set of icons for your project is to remove all
       
   118 the existing icon.png files, and then use the Eclipse IDE to create a dummy
       
   119 project.  During the process of doing this Eclipse will prompt you to create
       
   120 an icon. Then just copy the drawable directories it creates over to your
       
   121 res directory.
       
   122 
       
   123 You may need to change the name of your icon in AndroidManifest.xml to match
       
   124 the filename used by Eclipse.
       
   125 
       
   126 ================================================================================
    77  Pause / Resume behaviour
   127  Pause / Resume behaviour
    78 ================================================================================
   128 ================================================================================
    79 
   129 
    80 If SDL is compiled with SDL_ANDROID_BLOCK_ON_PAUSE defined, the event loop will
   130 If SDL is compiled with SDL_ANDROID_BLOCK_ON_PAUSE defined, the event loop will
    81 block itself when the app is paused (ie, when the user returns to the main
   131 block itself when the app is paused (ie, when the user returns to the main
   104 Android_JNI_SetupThread before doing anything else otherwise SDL will attach
   154 Android_JNI_SetupThread before doing anything else otherwise SDL will attach
   105 your thread automatically anyway (when you make an SDL call), but it'll never
   155 your thread automatically anyway (when you make an SDL call), but it'll never
   106 detach it.
   156 detach it.
   107 
   157 
   108 ================================================================================
   158 ================================================================================
       
   159  Using STL
       
   160 ================================================================================
       
   161 
       
   162 You can use STL in your project by creating an Application.mk file in the jni
       
   163 folder and adding the following line:
       
   164 APP_STL := stlport_static
       
   165 
       
   166 For more information check out CPLUSPLUS-SUPPORT.html in the NDK documentation.
       
   167 
       
   168 ================================================================================
   109  Additional documentation
   169  Additional documentation
   110 ================================================================================
   170 ================================================================================
   111 
   171 
   112 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.
   172 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.
   113 
   173