Build DMD for Android

All druntime and phobos tests from 2.070 git master pass on Android/x86, I need to try the dmd test suite next. Almost all of the druntime/phobos tests pass on Android/ARM with ldc. A C/OpenGLES 1.0 purely native sample app from the NDK has been ported to D. I list work that still needs to be done at the end.

Prerequisites

• linux host on which to build dmd
  • A virtual machine like VirtualBox/VMware will do fine, but you should have at least 512 MB of memory allocated and 1 GB of swap, particularly if building the phobos unit tests, and 10 GB of disk space.
• C++ compiler and toolchain, to build dmd
• A pre-built D compiler for linux, needed because the D frontend has been translated to D.
• dmd/druntime/phobos source
  • Get the source from git, as the following Android patches have only been tested on the master branch of each repo.
• Android native toolchain, the NDK and optionally the SDK
  • You don't need the SDK if you only want to build command-line binaries, the SDK is only needed to package and sign GUI apps. The "SDK Tools only" version of the SDK is enough, if you don't plan on using their IDE integration. I will only write about using the command-line tools. The SDK requires JDK 7: follow their instructions to make sure it's installed right.
• Android/x86, whether a device or VM
  • The SDK comes with an emulator and Intel puts out their own. I use the builds put out by the android-x86 project and recommend the deprecated 4.3 build, as it's the least buggy one I've dealt with. I run the iso in a VM with 512 MBs of memory without installing to disk.

To run Android/x86 in a VM

Download the Android-x86 iso and install as normal. It'll put you through a configuration process, but you can skip every step. Go to Settings->Security and disable the Verify Apps option, or it'll ask you about that every time you install a test app. Alt-F1 will take you to a root shell, which you'll want to do any time you're not using Android/x86 for a couple minutes, or the screen will eventually go black and the VM will freeze up. Alt-F7 takes you back to the normal GUI screen.

Build D for Android/x86

Download the patch for dmd, apply it, and build normally:

cd dmd
git apply 3643.patch
make -f posix.mak -j5

This patch adds emulated TLS for Android/x86, more info can be found on the pull request.

Assuming druntime and phobos are in the same directory as dmd, download and apply the patch for druntime and the patch for phobos, then set the NDK environment variable to the path of wherever you installed the NDK:

cd ../druntime
export NDK=/path/to/your/android-ndk-r10
git apply druntime_android
make -f posix.mak

cd ../phobos
git apply phobos_android
make -f posix.mak

Both patches avoid building druntime/phobos as a shared library and set the appropriate C compiler and linker path and flags, along with a couple small fixes for Android that haven't been upstreamed yet. The remaining changes are for the unit tests and are addressed below.

Build an Android sample app

I've put up an android repository which contains several translated headers and a sample C app translated to D. Clone it into the same directory as dmd/druntime/phobos:

cd ..
git clone https://github.com/joakim-noah/android.git

Default build of the C sample app

First, let's see how it's done by default by compiling the C version. Go to the sample native-activity app in my android repo, which is almost copied verbatim from the NDK/samples. The only differences are that it also contains a translation of the given jni/main.c source to jni/main.d, changes one line in jni/Application.mk to build for x86 by default, and includes a dmd.conf for building with dmd.

Run the following commands to compile the C source into a debug app that you can install on Android, these commands are taken from the NDK instructions:

cd android/samples/native-activity
NDK_TOOLCHAIN_VERSION=clang $NDK/ndk-build V=1

Looking at the output, it compiles jni/main.c, a small wrapper library called android_native_app_glue, and links everything together into a shared library. Let's look at the command that compiles jni/main.c:

/opt/ndk/toolchains/llvm-3.5/prebuilt/linux-x86/bin/clang -MMD -MP -MF
./obj/local/x86/objs/native-activity/main.o.d -gcc-toolchain
/opt/ndk/toolchains/x86-4.8/prebuilt/linux-x86 -target i686-none-linux-android
-ffunction-sections -funwind-tables -fstack-protector -fPIC
-Wno-invalid-command-line-argument -Wno-unused-command-line-argument
-no-canonical-prefixes -O2 -g -DNDEBUG -fomit-frame-pointer -fstrict-aliasing
-I/opt/ndk/sources/android/native_app_glue -Ijni -DANDROID -Wa,--noexecstack
-Wformat -Werror=format-security -I/opt/ndk/platforms/android-9/arch-x86/usr/include
-c jni/main.c -o ./obj/local/x86/objs/native-activity/main.o

This is where I extracted the C compiler path and flags for the previous druntime/phobos patches, leaving out the dependency file (-MMD -MP -MF).

This command links the shared library that gets packaged into the native app:

/opt/ndk/toolchains/llvm-3.5/prebuilt/linux-x86/bin/clang++
-Wl,-soname,libnative-activity.so -shared
--sysroot=/opt/ndk/platforms/android-9/arch-x86
./obj/local/x86/objs/native-activity/main.o
./obj/local/x86/libandroid_native_app_glue.a -lgcc -gcc-toolchain
/opt/ndk/toolchains/x86-4.8/prebuilt/linux-x86 -target i686-none-linux-android
-no-canonical-prefixes -Wl,--no-undefined -Wl,-z,noexecstack -Wl,-z,relro
-Wl,-z,now -L/opt/ndk/platforms/android-9/arch-x86/usr/lib -llog -landroid
-lEGL -lGLESv1_CM -llog -lc -lm -o ./obj/local/x86/libnative-activity.so

You'll use a modified version of the above command to link your D source later.

Getting back to building the C app, set the SDK environment variable for the path to your SDK and run the commands to package an Android app/apk:

export SDK=/path/to/your/android-sdk-linux
$SDK/tools/android update project -p . -s --target 1
ant debug

Now you'll push the final app, NativeActivity-debug.apk, to your Android/x86 environment. Connecting to Android will vary based on which Android/x86 you're using: I'll show you how I do it for Android/x86 installed in a VM, using the first method shown in the Android-x86 docs. Hit Alt-F1 inside the VM to go to the root shell and type "netcfg" to get its IP address: let's say it's 192.168.0.1. Hit Alt-F7 to go back to the UI, then go to Settings->Apps. It should be empty.

Going back to the linux host:

$SDK/platform-tools/adb connect 192.168.0.1:5555
$SDK/platform-tools/adb install bin/NativeActivity-debug.apk
$SDK/platform-tools/adb logcat native-activity *:S

The NativeActivity app should show up in the Settings->Apps list in Android/x86. Go to the app launcher and click on NativeActivity to run it. Move the mouse and you should see a bunch of colors continuously flashing on the screen. Looking at the log dump in the linux host, you'll see some numbers from the accelerometer, which are being reported by the app.

Build the translated D app

I've translated jni/main.c to a D version, jni/main.d. First, you'll need to recompile the android_native_app_glue library so that it calls a couple functions necessary for a D shared library. Hit ctrl-c to get out of the Android log and open $NDK/sources/android/native_app_glue/android_native_app_glue.c in an editor. Find the android_main function and add the following rt_init()/rt_term() calls before and after it:

    rt_init();
    android_main(android_app);
    rt_term();

Clean up and compile as before:

$NDK/ndk-build clean
NDK_TOOLCHAIN_VERSION=clang $NDK/ndk-build V=1

You should see the following linker error, as the linker can't find the rt_init and rt_term functions you just added:

/home/joakim/android-ndk-r10/sources/android/native_app_glue/android_native_app_glue.c:232:
error: undefined reference to 'rt_init'
/home/joakim/android-ndk-r10/sources/android/native_app_glue/android_native_app_glue.c:234:
error: undefined reference to 'rt_term'
clang++: error: linker command failed with exit code 1 (use -v to see invocation)
make: *** [obj/local/x86/libnative-activity.so] Error 1

That's fine, now let's build and link the D source in instead:

../../../dmd/src/dmd -android -I../.. -ofobj/local/x86/objs/native-activity/main.o
-c jni/main.d ../../android/sensor.d

$NDK/toolchains/llvm-3.5/prebuilt/linux-x86/bin/clang
-Wl,-soname,libnative-activity.so -shared
--sysroot=$NDK/platforms/android-9/arch-x86
./obj/local/x86/objs/native-activity/main.o
./obj/local/x86/libandroid_native_app_glue.a -lgcc  -gcc-toolchain 
$NDK/toolchains/x86-4.8/prebuilt/linux-x86 -target i686-none-linux-android
-no-canonical-prefixes  -Wl,--no-undefined -Wl,-z,noexecstack -Wl,-z,relro
-Wl,-z,now  -L$NDK/platforms/android-9/arch-x86/usr/lib -llog -landroid
-lEGL -lGLESv1_CM -llog -lc -lm -fuse-ld=bfd
-L../../../phobos/generated/linux/release/32 -l:libphobos2.a 
-o ./libs/x86/libnative-activity.so

android/sensor.d is included in the first command to avoid a dmd bug with unions declared in a separate file. Note the final linker command is a lightly modified version of the one issued when linking the C shared library above, with phobos added to the mix. -fuse-ld=bfd was added to force the use of the ld.bfd linker instead of the gold linker, because only ld.bfd works with the Android/x86 TLS patch.

Finally, you can build an apk and install to the Android/x86 VM as before:

ant debug
$SDK/platform-tools/adb uninstall com.example.native_activity
$SDK/platform-tools/adb install bin/NativeActivity-debug.apk
$SDK/platform-tools/adb logcat native-activity *:S

Run the D app and you should see the same results.

Build a command-line executable

This might be useful if you want to run your unit tests on the command-line, as I'll show with the druntime/phobos unit tests later.

Let's try building one of the sample files that come with dmd:

../../../dmd/src/dmd -android -c ../../../dmd/samples/sieve.d

$NDK/toolchains/llvm-3.5/prebuilt/linux-x86/bin/clang
-Wl,-z,nocopyreloc --sysroot=$NDK/platforms/android-9/arch-x86 -lgcc 
-gcc-toolchain $NDK/toolchains/x86-4.8/prebuilt/linux-x86 -target
i686-none-linux-android -no-canonical-prefixes -fuse-ld=bfd 
-Wl,--no-undefined -Wl,-z,noexecstack -Wl,-z,relro -Wl,-z,now
-Wl,--export-dynamic -lc -lm sieve.o
-L../../../phobos/generated/linux/release/32 -l:libphobos2.a -o ./sieve

The linker command was extracted by building the sample test-libstdc++ executable from the NDK and removing a handful of flags that weren't needed.

Now we can push it to Android: there are some quirks however. Android doesn't allow you to run executables from the /sdcard partition, but you can only push files to the sdcard. I route around these restrictions by pushing to the sdcard and then copying the executable as root to the /data partition.

$SDK/platform-tools/adb push sieve /sdcard/

Switch to the Android VM and hit Alt-F1 to get a root shell:

mkdir /data/test
cd /data/test
cp /sdcard/sieve .
chmod 755 sieve
./sieve

You'll see the following output if everything went well:

10 iterations
1899 primes

Run the druntime and phobos unit tests

Go back to the linux host and build the druntime and phobos unit tests:

cd ../../../druntime
make -f posix.mak unittest

If everything went right, you should see the following error, as the tests were compiled but won't be run on the linux host:

make: obj/32/test_runner: Command not found
posix.mak:234: recipe for target 'obj/32/object_' failed
make: *** [obj/32/object_] Error 127

The patch for phobos adds support for extracting timezone data from Android's concatenated tzdata file to std.datetime, includes some workarounds for Android, and makes a few function call and formatting changes because "long double" and "double" are both 64-bit on Android:

cd ../phobos
make -f posix.mak unittest BUILD=release

Again, it will error out as the resulting test_runner binary won't run on the linux host:

make: generated/linux/release/32/unittest/test_runner: Command not found
posix.mak:384: recipe for target 'unittest/std/array.run' failed
make: *** [unittest/std/array.run] Error 127

Download these lists of tests for druntime and phobos and push them and the test runners to the Android VM:

$SDK/platform-tools/adb push ../druntime/test_runner /sdcard/druntime_test_runner
$SDK/platform-tools/adb push druntime_tests /sdcard/
$SDK/platform-tools/adb push phobos_tests /sdcard/
$SDK/platform-tools/adb push test_runner /sdcard/

Switch to the root shell in the Android VM and run the tests:

cp /sdcard/druntime_test_runner test_runner
cp /sdcard/druntime_tests /sdcard/phobos_tests .
chmod 755 test_runner
source druntime_tests > druntime_tests.log

cp /sdcard/test_runner .
mkdir std
echo test > std/string.d
source phobos_tests > phobos_tests.log

I get the following results for druntime and phobos: all modules pass their tests.

Directions for future work

• Two modules, core.thread and std.parallelism, have tests that cause the test runner to hang when run from inside an apk as opposed to on the command line. Trying to suspend a thread from another thread, either directly by calling thread_suspendAll() or indirectly when the GC runs a full collect on a multi-threaded app, fails, because pthread_kill doesn't return and hangs the calling thread. It appears that this is related to using SIGUSR1/2 for suspending and resuming threads: simply switching the two signals works around this issue for now.

• You may notice that I added an empty main function in the D translation of the C sample app: that's a hack to build a shared library. Some of the linux shared library support in druntime's rt.sections_elf_shared may eventually be integrated with Android to get rid of that.

• The android_native_app_glue C wrapper can probably be replaced by D startup code, so that little to no C wrapper is necessary.

• Now that we can write D code for Android, it'll make building easier if the D cross-compilers are integrated with a build tool like reggae.

• I want to try running the dmd test suite on Android/x86. Since dmd's tests depend on phobos, I couldn't run them till I got phobos passing its tests.