diff options
| -rw-r--r-- | MANIFEST | 1 | ||||
| -rw-r--r-- | README.android | 168 | ||||
| -rw-r--r-- | pod/.gitignore | 1 | ||||
| -rw-r--r-- | pod/perl.pod | 1 | ||||
| -rw-r--r-- | win32/Makefile | 20 | ||||
| -rw-r--r-- | win32/makefile.mk | 20 |
6 files changed, 193 insertions, 18 deletions
@@ -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 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 diff --git a/pod/.gitignore b/pod/.gitignore index 3e862d7d6c..884e6c32c6 100644 --- 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 4abe433ffa..89c6d0b4fa 100644 --- 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 9a10f34712..b63b3bf651 100644 --- 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 f97657d508..3328e8b428 100644 --- 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 |