This document explains how to build DCSS for Android, and some of the technical details. Introduction ------------ DCSS for Android is based on a port of the SDL library written by "pelya" (https://github.com/pelya/commandergenius). The library was originally put together for an Android version of Commander Genius, but has subsequently been repurposed for other apps. It provides a number of features that would otherwise need to be written from scratch: * pop-up keyboard * configurable soft- and hard-keys * a multitude of mouse settings suitable for phones and tablets * bindings for native foreground/background events * .apk packaging The trade-off is a build process that is somewhat different from the traditional "./configure; make; make install" that you might expect. Build Process ------------- * Get the latest Android SDK (here: http://developer.android.com/sdk/index.html) * Run "android" and fetch the files for the android-14 platform * get the latest Android NDK, r8d (here: http://developer.android.com/sdk/ndk/index.html) * Configure your PATH. Assuming you've installed the SDK in $SDK and the NDK in $NDK: export PATH=$SDK/tools:$SDK/platform-tools:$NDK:$PATH * Ensure that you have all of the dependent host libraries required to use the SDK, NDK and build crawl's host tools. For a recent ubuntu host these are: - ia32-libs - build-essential - libpng12-dev - libsdl1.2-dev - libsdl-image1.2-dev - libfreetype6-dev (you may also require libvorbis-dev and zip) * If you don't have them already, you need Oracle's JDK and ant installed * Get the SDL android port (a modified version of pelya's): git submodule update --checkout crawl-ref/source/contrib/sdl-android * run "make android" * If it fails, run it again (happens a lot on the first build). * you'll find the apk in the source directory. It should be more than 10 MB. If it's only 5.5 MB, run "make android" again. Project Structure ----------------- At a high level, the SDL library and DCSS are laid out on disk as follows: crawl-ref/source/contrib/sdl-android build.sh # script to build DCSS project/ bin/ # where the .apk gets put java/ # Java code that wraps the native game+libs jni/ # where contrib libraries live, including SDL application/src # symlink to the directory containing crawl-ref Within the crawl-ref directory there are some additional configuration and build scripts that are required to integrate the Android libraries with DCSS: * AndroidBuild.sh This is the point of integration between the NDK's build scripts and Crawl's makefile. By default, Android builds want to use an "Android.mk" file to track compiling/linking tasks, which is no good for DCSS. The exact CFLAGS, LDFLAGS, libraries to link, etc., etc. are also passed from this script into make, in place of any kind of "configure" script. Finally, this script takes care of compressing all of tiles' assets into a resource bundle suitable for inclusion with the .apk. * AndroidAppSettings.cfg Configuration file that tells the SDL library and its build scripts exactly how to integrate with DCSS, including things like which libraries to use, default key bindings and the like. Technical Notes --------------- * this port currently uses r8d of the Android NDK. Even minor revisions of the native dev kit can prevent the app from compiling, or working properly on all Android platforms: be aware if using an earlier (or later!) version * there are lots of Android-specifics in the makefile, because (a) the custom toolchain needs lots of CFLAGS and LDFLAGS to work properly and (b) the target paths for the data directory are completely different to where the "executable" lives on Android, and also completely different to the host OS * the majority of the changes to the DCSS code are changing GLES calls so that they work correctly with Android's GLES implementation and integrate properly with the Java-side SDL. The integration is necessary because the SDL library provides overlays for the soft- keyboard and configurable keys, which interferes with some of the OpenGL state * the rltiles/ tools get compiled using native tools not the NDK ones, and the environment is cleared for the sub-make. This might cause the build to fail, depending on your environment * don't rename the NDK directory: it contains the revision (e.g. -r8d) and some of the build scripts use this to determine which libraries to include * the build framework will return "build successful" even if the crawl application is not compiled successfully. A failed build will produce a very small .apk. The error message will be mid-way through the log