Files in the top-level directory in any check-in

================================================================================
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: 14 (Android 4.0)
Requested API level from project.properties: 16 (Android 4.1)
Target API level (jni/AndroidManifest.xml): 14 (Android 4.0)
Target API level (jni/AndroidManifest64.xml): 26 (Android 8)
CPUs supported for native shared libraries (jni/Application.mk): armeabi x86
CPUs supported for native shared libraries (jni/Application64.mk): armeabi-v7a arm64-v8a x86_64
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 (gradle based, new style)
================================================================================

0. Depending on your setup, before building AndroWish it can be
   necessary to set two environment variables ANDROID_HOME and
   ANDROID_NDK_HOME. The first must point to the Android SDK
   directory, the second to the Android NDK directory, e.g.

   export ANDROID_HOME=/some/where/android-sdk/
   export ANDROID_NDK_HOME=/some/where/android-sdk/ndk/<version>

1. Use gradle to build AndroWish from scratch (currently only debug version):

   ./gradlew assembleDebug

   This includes building the C libraries using Android NDK. That step
   can be performed separately by running ndk-build in the jni directory.
   The C libraries are build for ARM and x86 (Atom) processors which can
   be changed in jni/Application.mk
   Output appears in build/outputs/apk directory as AndroWish-debug.apk

2. Install AndroWish on emulator or device:

   adb install -r build/outputs/apk/AndroWish-debug.apk

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

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

4. Clean the build tree:

   ./gradlew clean

================================================================================
 Building and running AndroWish (ant based, old school)
================================================================================

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
   Output appears in bin directory as AndroWish-debug.apk

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