Added README.android

1 files changed, 168 insertions, 0 deletions

diff --git a/README.android b/README.android
new file mode 100644
index 0000000000..cc6d7edebe
--- /dev/null
+++ b/README.android
@@ -0,0 +1,168 @@
+If you read this file _as_is_, just ignore the funny characters you
+see. It is written in the POD format (see pod/perlpod.pod) which is
+specially designed to be readable as is.
+
+=head1 NAME
+
+perlandroid - Perl under Android
+
+=head1 SYNOPSIS
+
+These are instructions for cross-compiling Perl for Android 2.0 and later.
+
+As of the writing of this document, Google only provides NDKs for
+a 64-bit versions of Linux and OS X, and we assume that you will be
+using those as the host OS; Google also provides an NDK for Windows,
+but the instructions below will not work there, although using
+Windows to cross-compile to Android should be possible through
+different means.
+
+=head1 DESCRIPTION
+
+This document describes how to set up your host environment when
+attempting to cross-compile Perl for Android.
+
+=head2 Get the Android Native Development Kit (NDK)
+
+You can download the NDK from L<https://developer.android.com/tools/sdk/ndk/index.html>.
+You'll want the normal, non-legacy version.
+
+=head2 Determine the architecture you'll be cross-compiling for
+
+There's three possible options: arm-linux-androideabi for ARM,
+mipsel-linux-android for MIPS, and simply x86 for x86.
+As of 2014, most Android devices run on ARM, so that is generally a safe bet.
+
+With those two in hand, you should add
+
+$ANDROID_NDK/toolchains/$TARGETARCH-4.4.3/prebuilt/`uname | tr '[A-Z]' '[a-z]'`-x86_64/bin
+
+to your PATH, where $ANDROID_NDK is the location where you unpacked the
+NDK, and $TARGETARCH is your target's architecture.
+
+=head2 Set up a standalone toolchain
+
+This creates a working sysroot that we can feed to Configure later.
+
+    $ export ANDROID_TOOLCHAIN=/tmp/my-toolchain-$TARGETARCH
+    $ export SYSROOT=$ANDROID_TOOLCHAIN/sysroot
+    $ $ANDROID_NDK/build/tools/make-standalone-toolchain.sh \
+            --platform=android-9 \
+            --install-dir=$ANDROID_TOOLCHAIN \
+            --system=`uname | tr '[A-Z]' '[a-z]'`-x86_64 \
+            --toolchain=$TARGETARCH-4.4.3
+
+=head2 adb or ssh?
+
+adb is the Android Debug Bridge.  For our purposes, it's basically a way
+of establishing an ssh connection to an Android device using USB.
+Perl can be cross-compiled using either adb or a normal ssh connection;
+in general, if you can connect your device to the host using a USB port,
+you may want to use adb, although you may be forced to switch to ssh if
+your device is not rooted and you're unlucky -- more on that later.
+Alternatively, if you're cross-compiling for an emulator, you'll have to
+use adb.
+
+=head3 adb
+
+To use adb, download the Android SDK from L<https://developer.android.com/sdk/index.html>.
+The "SDK Tools Only" version should suffice -- if you downloaded the ADT
+Bundle, you can find the sdk under $ADT_BUNDLE/sdk/.
+
+Add $ANDROID_SDK/platform-tools to your PATH, which should give you access
+to adb.  You'll now have to find your device's name using 'adb devices',
+and later pass that to Configure through '-Dtargethost=$DEVICE'.
+
+However, before calling Configure, you need to check if using adb is a
+viable choice in the first place.  Because Android doesn't have a /tmp,
+nor does it allow executables in the sdcard, we need to find somewhere in
+the device for Configure to put some files in, as well as for the tests
+to run in. If your device is rooted, then you're good.  Try running these:
+
+    $ export TARGETDIR=/mnt/asec/perl
+    $ adb -s $DEVICE shell "echo sh -c '\"mkdir $TARGETDIR\"' | su --"
+
+Which will create the directory we need, and you can move on to the next
+step.  /mnt/asec is mounted as a tmpfs in Android, but it's only
+accessible to root.
+
+If your device is not rooted, you may still be in luck. Try running this:
+
+    $ export TARGETDIR=/data/local/tmp/perl
+    $ adb -s $DEVICE shell "mkdir $TARGETDIR"
+
+If the command works, you can move to the next step, but beware:
+B<You'll have to remove the directory from the device once you are done!
+Unlike /mnt/asec, /data/local/tmp may not get automatically garbage
+collected once you shut off the phone>.
+
+If neither of those work, then you can't use adb to cross-compile to your
+device.  Either try rooting it, or go for the ssh route.
+
+=head3 ssh
+
+To use ssh, you'll need to install and run a sshd app and set it up
+properly.  There are several paid and free apps that do this rather
+easily, so you should be able to spot one easily.
+Remember that Perl requires a passwordless connection, so set up a 
+public key.
+
+Note that several apps spew crap to stderr every time you
+connect, which can throw off Configure.  You may need to monkeypatch
+the part of Configure that creates 'run-ssh' to have it discard stderr.
+
+Since you're using ssh, you'll have to pass some extra arguments to
+Configure: -Dtargetrun=ssh -Dtargethost=$TARGETHOST -Dtargetuser=$TARGETUSER -Dtargetport=$TARGETPORT
+
+=head2 Configure and beyond
+
+With all of the previous done, you're now ready to call Configure.
+
+If using adb, a "basic" Configure line will look like this:
+
+$ ./Configure -des -Dusedevel -Dusecrosscompile -Dtargetrun=adb \
+    -Dcc=$TARGETARCH-gcc   \
+    -Dsysroot=$SYSROOT     \
+    -Dtargetdir=$TARGETDIR \
+    -Dtargethost=$DEVICE
+
+If using ssh, it's not too different -- we just change targetrun to ssh,
+and pass in targetuser and targetport.  It ends up looking like this:
+
+$ ./Configure -des -Dusedevel -Dusecrosscompile -Dtargetrun=ssh \
+    -Dcc=$TARGETARCH-gcc        \
+    -Dsysroot=$SYSROOT          \
+    -Dtargetdir=$TARGETDIR      \
+    -Dtargethost="$TARGETHOST"  \
+    -Dtargetuser=$TARGETUSER    \
+    -Dtargetport=$TARGETPORT
+
+Now you're ready to run make and make test!
+
+As a final word of warning, if you're using adb, make test may appear to
+hang; this is because it doesn't output anything until it finishes
+running all tests.  You can check its progress by logging into the
+device, moving to $TARGETDIR, and looking at the file output.stdout.
+
+=head3 Notes
+
+=over
+
+=item *
+
+If you are targetting x86 Android, you will have to change $TARGETARCH-gcc
+to i686-linux-android-gcc.
+
+=item *
+
+On some older low-end devices -- think early 2.2 era -- some tests,
+particularly t/re/uniprops, may crash the phone, causing it to turn
+itself off once, and then back on again.
+
+=back
+
+=head1 AUTHOR
+
+Brian Fraser <fraserbn@gmail.com>
+
+=cut