The AndroWish Software Development Kit
This is a preliminary description of the AndroWish SDK. It consists of a large ZIP file made up of prebuilt components (Java classes, shared libraries, Tcl library files, and other resource and property files) and a small graphical tool called bones to customize these components and to finally create an installable Android package (an APK file).
Thus, in theory it is not necessary anymore to mess with the many pieces of source code which make up AndroWish but to boldly click with the mouse some ten times to get a Tcl based Android App.
Prerequisites
- A recent Java Development Kit, version 1.6 or 1.7
- Android Standalone SDK tools.
- Optionally Apache ant, often available as an optional installable package of a Linux distribution
- Tcl/Tk wish version 8.5 or 8.6 (preferred) e.g. from ActiveState's ActiveTcl, but like ant, often available as an optional installable package of a Linux distribution
AndroWish SDK Setup
The current AndroWish SDK has been tested on some Linux distributions (CentOS 6, Linux Mint 17.1) and on Windows 7 (32 bit). It is reported to be usable on MacOSX, too.
Download the current AWSDK.zip and unpack it. Ensure, that you've set up your environment and/or path so that the Android SDK tools can be found by the build tools (gradle or ant). Ensure, that you can run Tcl programs using wish.
Experimental! For the adventurous there's a single file Win32 (32 bit) binary in bones.exe which contains both a current wish and AWSDK.zip. It should be copied to a directory of its own where it unpacks the built-in AWSDK.zip when executed for the first time.
Directory Structure of the SDK
After the AWZIP.zip has been unpacked, the resulting AWSDK directory contains these files and directories (only the most important ones shown):
| File/Directory | Remarks |
| AndroidManifest.xml | App descriptor, read/written by the bones tool. Contains App's entry point and permissions. |
| ant.properties | Build information for gradle or ant. Read/written by the bones tool for keystore information (code signing). |
| assets/* | Tcl/Tk libraries and additional support files (e.g. version information and package inventory). Content controlled by the bones tool. |
| assets/app/* | User code. The file main.tcl is automatically run by the App. Other user/App specific files should go here, too. |
| build.gradle | Control file for gradle (like Makefile for make). |
| build.xml | Control file for ant (like Makefile for make). |
| _casket/* | Directory where the bones tool moves and keeps track of unselected optional components (Tcl/Tk and native shared libraries). |
| gradle/* | Wrapper/support files for gradle. |
| gradlew | Shell script to run gradle on UN*X platforms. |
| gradlew.bat | Batch file to run gradle on Windows platforms. |
| libs/*.jar | Precompiled Java libraries built into the App. |
| libs/armeabi/*.so | Precompiled native shared libraries for ARM processors. Content controlled by the bones tool. |
| libs/x86/*.so | Precompiled native shared libraries for x86 processors. Content controlled by the bones tool. |
| local.properties | Information for ant to locate the Android SDK. Updated once on first run of the bones tool. |
| res/* | App resources, e.g. PNG icon files in various resolutions. Modified by the bones tool for App icons. |
| settings.gradle | Project settings for gradle. |
| src/* | Java sources, App entry point (an empty Java class deriving from the AndroWish activity super class). Modified by the bones tool according to the user chosen package/class names. |
| tools/bones | Tcl source of the bones tool |
Except for the "assets/app" directory the layout and content of the AndroWish SDK directory tree should not be altered manually in order to not confuse the bones tool.
External Tools
The following table lists the external programs which are used throughout operation of the bones tool.
| Program | Location | Remarks |
| adb | $ANDROID_HOME/platform-tools/adb (Unix) %ANDROID_HOME%/platform-tools/adb (Win32) adb (fallback, all) |
Android Debug Bridge used to optionally install final package and to start it on device or emulator. |
| android | $ANDROID_HOME/tools/android (Unix) %ANDROID_HOME%/tools/android (Win32) android (fallback, all) |
Android SDK Platform Manager used to setup project initially. Required. |
| ant | $ANT_HOME/bin/ant (Unix) %ANT_HOME%/bin/ant (Win32) ant (fallback, all) |
Apache ant used to control the APK build process. Optional, deprecated. |
| fossil | fossil | Fossil repository program, optionally used on startup to verify state of source tree. |
| keytool | keytool | Key tool from the Java Development Kit. Only used when an new keystore for code signing is to be generated. |
So the bones tool prefers to find the essential external programs using the two environment variables ANDROID_HOME and ANT_HOME, and the common fallback strategy is to search for the external programs using the normal search path for executable programs.
Since AndroWish version "Asteroid Day (2018-06-30)" ant is deprecated and gradle is used instead. To switch back to using ant the two files gradlew and gradlew.bat can be renamed in order to force the bones tool to fall back to ant.
Start the bones Tool
$ wish <path-where-AWSDK.zip-has-been-unpacked-to>/tools/bones
Fraction 1: Package Selection
The first page of bones allows to remove optional pieces of AndroWish. An overview of included components gives Batteries Included. Uncheck unneeded packages in the list and remove them by pressing the Remove packages button. This moves the selected packages out of the staging area that they will not be added later to the APK. The Revert button moves all removed packages back to the staging area. When satisfied with your choice press the Next button for the next page.
When all optional components are omitted and CPU support is limited to ARM only (described below), the size of the resulting APK can be shrinked down to about 4 MByte instead of nearly 30 MByte with everything included.
Fraction 2: Add App Specific Files
This page allows to add files to the folder assets/app within the staging area. The most important script is main.tcl which when found gets sourced on start up of AndroWish and thus allows to make your own App. Use the right mouse button to paste or deleted files and directories into the assets/app folder. This works from file managers which place their selected files into the clipboard. Otherwise use the Browse files ... button to open a simple file browser. When finished with this step press the Next button to continue.
Fraction 3: The App Manifest
The manifest file (AndroidManifest.xml) is the application descriptor of the APK. It describes the App's unique name (the combination of Package name and Class name) and its label on the home screen (the App name). A good choice is a reversed domain name plus an optional package name component plus the final class name (example: the XZing barcode scanner is com.google.zxing.BarcodeScanner, i.e. com.google.zxing is the package, and BarcodeScanner the class name). The list box with App permissions allows to grant or revoke specific access permissions on device components. When you're satisfied with your selection press Make manifest to write your settings into the AndroidManifest.xml. After the new manifest settings have been written the Next button becomes sensitive to switch to the next page.
NB: Under the hood when writing the AndroidManifest.xml an additional directory tree with a Java file based on the package/class name fields is written, too, which contains an empty class definition deriving from tk.tcl.wish.AndroWish. This is the App's worm hole from the Java universe into our little Tcl/Tk galaxy. Its singular purpose is to satisfy the App naming requirement imposed by the Android empire.
Fraction 3a: Set App Icons
The icon(s) of the App shown in the home screen or in the notification area can be changed by pasting PNG files into the image labels. New icons should be provided in the four sizes 144x144 (XXHDPI), 96x96 (XHDPI), 72x72 (HDPI), and 48x48 (MDPI). When finished with the icons press the Next button to switch to the next page.
Fraction 4: Build Options, Code Signing
The CPU support selects which shared libraries are packaged into the APK. Currently, prebuilt support for ARM and x86 exists. However, latest experiments with various x86 devices (Intel Atom) showed, that usually ARM CPU support is sufficient since the x86 devices have an ARM emulation built in. Omitting x86 support squeezes about 7 MByte out of the APK when all possible packages have been selected.
The Build mode and various key store related fields control if a debug APK shall be built (which is signed with a special debug key). Alternatively, your own key shall be used to sign the APK. To create a key store from scratch enter the values as shown in the image and press the Make keystore button. Otherwise use an already existing keystore (e.g. ~/.keystore , the default of Java's keytool) with approriate values for the key alias and passwords.
When ready for the final APK build step, press the Next button.
Fraction 5: APK Building
Building the APK (the Cleanup & build button) is equivalent to invoking
$ gradlew clean assembleDebug|assembleReleaseor
$ ant clean debug|releaseon the command line within the install directory of the AndroWish SDK. If everything went well, one of the last lines of output should read BUILD SUCCESSFUL. In this case the APK file can be found in .../build/outputs/apk/AndroWishApp-debug.apk for a gradle debug build, .../bin/AndroWishApp-debug.apk for an ant debug build, .../build/outputs/apk/AndroWishApp-release.apk for a gradle release build, or .../bin/AndroWishApp-release.apk for an ant release build, and be transferred to a device or emulator. If an Android device is connected to your development system the middle button changes to Install & run and allows to install and start the new APK when clicked.
Fraction 5a: Installing/Running the APK
The Install & run button opens a log window which displays the output of adb logcat (the log facility of the Android Debug Bridge). An example is shown below which displays an error message originating from the App (the lines with "libtk" showing a Tcl error message). The check buttons with the single capital letters can be used to filter the log output according to its log level, e.g. "V" for verbose, "D" for debug, "E" for error. The Lock/Scroll button disables scrolling of the output window, the Clear button clears the output window, and the Run button allows to restart the App on the device or emulator.
