This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
Added README.android
[perl5.git] / README.android
CommitLineData
6001596e
BF
1If you read this file _as_is_, just ignore the funny characters you
2see. It is written in the POD format (see pod/perlpod.pod) which is
3specially designed to be readable as is.
4
5=head1 NAME
6
7perlandroid - Perl under Android
8
9=head1 SYNOPSIS
10
11These are instructions for cross-compiling Perl for Android 2.0 and later.
12
13As of the writing of this document, Google only provides NDKs for
14a 64-bit versions of Linux and OS X, and we assume that you will be
15using those as the host OS; Google also provides an NDK for Windows,
16but the instructions below will not work there, although using
17Windows to cross-compile to Android should be possible through
18different means.
19
20=head1 DESCRIPTION
21
22This document describes how to set up your host environment when
23attempting to cross-compile Perl for Android.
24
25=head2 Get the Android Native Development Kit (NDK)
26
27You can download the NDK from L<https://developer.android.com/tools/sdk/ndk/index.html>.
28You'll want the normal, non-legacy version.
29
30=head2 Determine the architecture you'll be cross-compiling for
31
32There's three possible options: arm-linux-androideabi for ARM,
33mipsel-linux-android for MIPS, and simply x86 for x86.
34As of 2014, most Android devices run on ARM, so that is generally a safe bet.
35
36With those two in hand, you should add
37
38$ANDROID_NDK/toolchains/$TARGETARCH-4.4.3/prebuilt/`uname | tr '[A-Z]' '[a-z]'`-x86_64/bin
39
40to your PATH, where $ANDROID_NDK is the location where you unpacked the
41NDK, and $TARGETARCH is your target's architecture.
42
43=head2 Set up a standalone toolchain
44
45This creates a working sysroot that we can feed to Configure later.
46
47 $ export ANDROID_TOOLCHAIN=/tmp/my-toolchain-$TARGETARCH
48 $ export SYSROOT=$ANDROID_TOOLCHAIN/sysroot
49 $ $ANDROID_NDK/build/tools/make-standalone-toolchain.sh \
50 --platform=android-9 \
51 --install-dir=$ANDROID_TOOLCHAIN \
52 --system=`uname | tr '[A-Z]' '[a-z]'`-x86_64 \
53 --toolchain=$TARGETARCH-4.4.3
54
55=head2 adb or ssh?
56
57adb is the Android Debug Bridge. For our purposes, it's basically a way
58of establishing an ssh connection to an Android device using USB.
59Perl can be cross-compiled using either adb or a normal ssh connection;
60in general, if you can connect your device to the host using a USB port,
61you may want to use adb, although you may be forced to switch to ssh if
62your device is not rooted and you're unlucky -- more on that later.
63Alternatively, if you're cross-compiling for an emulator, you'll have to
64use adb.
65
66=head3 adb
67
68To use adb, download the Android SDK from L<https://developer.android.com/sdk/index.html>.
69The "SDK Tools Only" version should suffice -- if you downloaded the ADT
70Bundle, you can find the sdk under $ADT_BUNDLE/sdk/.
71
72Add $ANDROID_SDK/platform-tools to your PATH, which should give you access
73to adb. You'll now have to find your device's name using 'adb devices',
74and later pass that to Configure through '-Dtargethost=$DEVICE'.
75
76However, before calling Configure, you need to check if using adb is a
77viable choice in the first place. Because Android doesn't have a /tmp,
78nor does it allow executables in the sdcard, we need to find somewhere in
79the device for Configure to put some files in, as well as for the tests
80to run in. If your device is rooted, then you're good. Try running these:
81
82 $ export TARGETDIR=/mnt/asec/perl
83 $ adb -s $DEVICE shell "echo sh -c '\"mkdir $TARGETDIR\"' | su --"
84
85Which will create the directory we need, and you can move on to the next
86step. /mnt/asec is mounted as a tmpfs in Android, but it's only
87accessible to root.
88
89If your device is not rooted, you may still be in luck. Try running this:
90
91 $ export TARGETDIR=/data/local/tmp/perl
92 $ adb -s $DEVICE shell "mkdir $TARGETDIR"
93
94If the command works, you can move to the next step, but beware:
95B<You'll have to remove the directory from the device once you are done!
96Unlike /mnt/asec, /data/local/tmp may not get automatically garbage
97collected once you shut off the phone>.
98
99If neither of those work, then you can't use adb to cross-compile to your
100device. Either try rooting it, or go for the ssh route.
101
102=head3 ssh
103
104To use ssh, you'll need to install and run a sshd app and set it up
105properly. There are several paid and free apps that do this rather
106easily, so you should be able to spot one easily.
107Remember that Perl requires a passwordless connection, so set up a
108public key.
109
110Note that several apps spew crap to stderr every time you
111connect, which can throw off Configure. You may need to monkeypatch
112the part of Configure that creates 'run-ssh' to have it discard stderr.
113
114Since you're using ssh, you'll have to pass some extra arguments to
115Configure: -Dtargetrun=ssh -Dtargethost=$TARGETHOST -Dtargetuser=$TARGETUSER -Dtargetport=$TARGETPORT
116
117=head2 Configure and beyond
118
119With all of the previous done, you're now ready to call Configure.
120
121If using adb, a "basic" Configure line will look like this:
122
123$ ./Configure -des -Dusedevel -Dusecrosscompile -Dtargetrun=adb \
124 -Dcc=$TARGETARCH-gcc \
125 -Dsysroot=$SYSROOT \
126 -Dtargetdir=$TARGETDIR \
127 -Dtargethost=$DEVICE
128
129If using ssh, it's not too different -- we just change targetrun to ssh,
130and pass in targetuser and targetport. It ends up looking like this:
131
132$ ./Configure -des -Dusedevel -Dusecrosscompile -Dtargetrun=ssh \
133 -Dcc=$TARGETARCH-gcc \
134 -Dsysroot=$SYSROOT \
135 -Dtargetdir=$TARGETDIR \
136 -Dtargethost="$TARGETHOST" \
137 -Dtargetuser=$TARGETUSER \
138 -Dtargetport=$TARGETPORT
139
140Now you're ready to run make and make test!
141
142As a final word of warning, if you're using adb, make test may appear to
143hang; this is because it doesn't output anything until it finishes
144running all tests. You can check its progress by logging into the
145device, moving to $TARGETDIR, and looking at the file output.stdout.
146
147=head3 Notes
148
149=over
150
151=item *
152
153If you are targetting x86 Android, you will have to change $TARGETARCH-gcc
154to i686-linux-android-gcc.
155
156=item *
157
158On some older low-end devices -- think early 2.2 era -- some tests,
159particularly t/re/uniprops, may crash the phone, causing it to turn
160itself off once, and then back on again.
161
162=back
163
164=head1 AUTHOR
165
166Brian Fraser <fraserbn@gmail.com>
167
168=cut