================================================================================
AndroWish - Tcl/Tk 8.6 port for Android
================================================================================

Requirements:

Android SDK (version 12 or later)
http://developer.android.com/sdk/index.html

Android NDK r7 or later
http://developer.android.com/tools/sdk/ndk/index.html

Minimum API level supported by SDL: 10 (Android 2.3.3)
Requested API level from project.properties: 14 (Android 4.0)
CPUs supported for native shared libraries (jni/Application.mk): armeabi x86
Joystick support is available for API level >=12 devices.

Building from scratch requires more than 800 MB disk space on Linux.

================================================================================
 How the port works
================================================================================

- Android applications are Java-based, optionally with parts written in C
- As Tcl/Tk is C-based, a layer using JNI is used to interface to the Java
  universe
- This means that C code is placed inside an Android Java project, along
  with some C support code that communicates with Java
- The drawing on screen and event handling is performed using SDL (included),
  AGG (included), and Freetype (included)
- This eventually produces a standard Android .apk package

The Android Java code implements an "Activity" and can be found in:

src/tk/tcl/wish/AndroWish.java
src/org/libsdl/app/SDLActivity.java

The Java code loads various shared libraries (tcl, tk, SDL, etc.) and
dispatches to native functions implemented in the SDL library:

jni/SDL2/src/core/android/SDL_android.c

Which dispatches to Tk_AppInit.c in

jni/src/tkAppInit.c

The interface from Tcl/Tk to Android is mainly contained in the files

jni/src/tkBorg.c
jni/src/tclRfcomm.c
jni/src/tclUsbserial.c

================================================================================
 Building and running AndroWish
================================================================================

1. Refresh the project settings using the android command from Android SDK:

   android update project

2. Review local.properties to point to the directory where Android SDK resides

3. Use ant to build AndroWish from scratch (currently only debug version):

   ant debug

   This includes building the C libraries using Android NDK. That step
   can be performed separately by running ndk-build in the jni directory,
   or by invoking "ant ndk-build".
   The C libraries are build for ARM and x86 (Atom) processors which can
   be changed in jni/Application.mk

4. Install AndroWish on emulator or device:

   adb install -r bin/AndroWish-debug.apk

5. Start AndroWish on emulator or device using adb from development system:

   adb shell am start tk.tcl.wish/.AndroWishLauncher

6. Clean the build tree:

   ant clean