Added README.android

diff --git a/MANIFEST b/MANIFEST
index 7d7c2bf..72608d6 100644 (file)
--- a/MANIFEST
+++ b/MANIFEST
@@ -4747,6 +4747,7 @@ qnx/qnx.c                 QNX silent matherr callback
 README                         The Instructions
 README.aix                     Perl notes for AIX
 README.amiga                   Perl notes for AmigaOS
+README.android                 Perl notes for Android
 README.bs2000                  Perl notes for POSIX-BC BS2000
 README.ce                      Perl notes for WinCE
 README.cn                      Perl for Simplified Chinese (in EUC-CN)

diff --git a/README.android b/README.android
new file mode 100644 (file)
index 0000000..cc6d7ed
--- /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

diff --git a/pod/.gitignore b/pod/.gitignore
index 3e862d7..884e6c3 100644 (file)
--- a/pod/.gitignore
+++ b/pod/.gitignore
@@ -1,6 +1,7 @@
 # arch-specific pods
 /perlaix.pod
 /perlamiga.pod
+/perlandroid.pod
 /perlbeos.pod
 /perlbs2000.pod
 /perlce.pod

diff --git a/pod/perl.pod b/pod/perl.pod
index 4abe433..89c6d0b 100644 (file)
--- a/pod/perl.pod
+++ b/pod/perl.pod
@@ -240,6 +240,7 @@ aux a2p c2ph h2ph h2xs perlbug pl2pm pod2html pod2man s2p splain xsubpp
 
     perlaix            Perl notes for AIX
     perlamiga          Perl notes for AmigaOS
+    perlandroid                Perl notes for Android
     perlbs2000         Perl notes for POSIX-BC BS2000
     perlce             Perl notes for WinCE
     perlcygwin         Perl notes for Cygwin

diff --git a/win32/Makefile b/win32/Makefile
index 9a10f34..b63b3bf 100644 (file)
--- a/win32/Makefile
+++ b/win32/Makefile
@@ -1148,6 +1148,7 @@ utils: $(PERLEXE) $(X2P) ..\utils\Makefile
        cd ..\pod
        copy ..\README.aix      ..\pod\perlaix.pod
        copy ..\README.amiga    ..\pod\perlamiga.pod
+       copy ..\README.android  ..\pod\perlandroid.pod
        copy ..\README.bs2000   ..\pod\perlbs2000.pod
        copy ..\README.ce       ..\pod\perlce.pod
        copy ..\README.cn       ..\pod\perlcn.pod
@@ -1276,15 +1277,16 @@ distclean: realclean
        -if exist $(LIBDIR)\Win32API rmdir /s /q $(LIBDIR)\Win32API
        -if exist $(LIBDIR)\XS rmdir /s /q $(LIBDIR)\XS
        -cd $(PODDIR) && del /f *.html *.bat roffitall \
-           perl5199delta.pod perlaix.pod perlamiga.pod perlapi.pod \
-           perlbs2000.pod perlce.pod perlcn.pod perlcygwin.pod perldos.pod \
-           perlfreebsd.pod perlhaiku.pod perlhpux.pod perlhurd.pod \
-           perlintern.pod perlirix.pod perljp.pod perlko.pod perllinux.pod \
-           perlmacos.pod perlmacosx.pod perlmodlib.pod perlnetware.pod \
-           perlopenbsd.pod perlos2.pod perlos390.pod perlos400.pod \
-           perlplan9.pod perlqnx.pod perlriscos.pod perlsolaris.pod \
-           perlsymbian.pod perlsynology.pod perltoc.pod perltru64.pod \
-           perltw.pod perluniprops.pod perlvos.pod perlwin32.pod
+           perl5199delta.pod perlaix.pod perlamiga.pod perlandroid.pod \
+           perlapi.pod perlbs2000.pod perlce.pod perlcn.pod perlcygwin.pod \
+           perldos.pod perlfreebsd.pod perlhaiku.pod perlhpux.pod \
+           perlhurd.pod perlintern.pod perlirix.pod perljp.pod perlko.pod \
+           perllinux.pod perlmacos.pod perlmacosx.pod perlmodlib.pod \
+           perlnetware.pod perlopenbsd.pod perlos2.pod perlos390.pod \
+           perlos400.pod perlplan9.pod perlqnx.pod perlriscos.pod \
+           perlsolaris.pod perlsymbian.pod perlsynology.pod perltoc.pod \
+           perltru64.pod perltw.pod perluniprops.pod perlvos.pod \
+           perlwin32.pod
        -cd ..\utils && del /f h2ph splain perlbug pl2pm c2ph pstruct h2xs \
            perldoc perlivp libnetcfg enc2xs piconv cpan *.bat \
            xsubpp pod2html instmodsh json_pp prove ptar ptardiff ptargrep shasum corelist config_data zipdetails

diff --git a/win32/makefile.mk b/win32/makefile.mk
index f97657d..3328e8b 100644 (file)
--- a/win32/makefile.mk
+++ b/win32/makefile.mk
@@ -1332,6 +1332,7 @@ utils: $(PERLEXE) $(X2P) ..\utils\Makefile
        cd ..\utils && $(MAKE) PERL=$(MINIPERL)
        copy ..\README.aix      ..\pod\perlaix.pod
        copy ..\README.amiga    ..\pod\perlamiga.pod
+       copy ..\README.android  ..\pod\perlandroid.pod
        copy ..\README.bs2000   ..\pod\perlbs2000.pod
        copy ..\README.ce       ..\pod\perlce.pod
        copy ..\README.cn       ..\pod\perlcn.pod
@@ -1459,15 +1460,16 @@ distclean: realclean
        -if exist $(LIBDIR)\Win32API rmdir /s /q $(LIBDIR)\Win32API
        -if exist $(LIBDIR)\XS rmdir /s /q $(LIBDIR)\XS
        -cd $(PODDIR) && del /f *.html *.bat roffitall \
-           perl5199delta.pod perlaix.pod perlamiga.pod perlapi.pod \
-           perlbs2000.pod perlce.pod perlcn.pod perlcygwin.pod perldos.pod \
-           perlfreebsd.pod perlhaiku.pod perlhpux.pod perlhurd.pod \
-           perlintern.pod perlirix.pod perljp.pod perlko.pod perllinux.pod \
-           perlmacos.pod perlmacosx.pod perlmodlib.pod perlnetware.pod \
-           perlopenbsd.pod perlos2.pod perlos390.pod perlos400.pod \
-           perlplan9.pod perlqnx.pod perlriscos.pod perlsolaris.pod \
-           perlsymbian.pod perlsynology.pod perltoc.pod perltru64.pod \
-           perltw.pod perluniprops.pod perlvos.pod perlwin32.pod
+           perl5199delta.pod perlaix.pod perlamiga.pod perlandroid.pod \
+           perlapi.pod perlbs2000.pod perlce.pod perlcn.pod perlcygwin.pod \
+           perldos.pod perlfreebsd.pod perlhaiku.pod perlhpux.pod \
+           perlhurd.pod perlintern.pod perlirix.pod perljp.pod perlko.pod \
+           perllinux.pod perlmacos.pod perlmacosx.pod perlmodlib.pod \
+           perlnetware.pod perlopenbsd.pod perlos2.pod perlos390.pod \
+           perlos400.pod perlplan9.pod perlqnx.pod perlriscos.pod \
+           perlsolaris.pod perlsymbian.pod perlsynology.pod perltoc.pod \
+           perltru64.pod perltw.pod perluniprops.pod perlvos.pod \
+           perlwin32.pod
        -cd ..\utils && del /f h2ph splain perlbug pl2pm c2ph pstruct h2xs \
            perldoc perlivp libnetcfg enc2xs piconv cpan *.bat \
            xsubpp pod2html instmodsh json_pp prove ptar ptardiff ptargrep shasum corelist config_data zipdetails