1PERLANDROID(1) Perl Programmers Reference Guide PERLANDROID(1)
2
6 perlandroid - Perl under Android
7
9 The first portions of this document contains instructions to cross-
10 compile Perl for Android 2.0 and later, using the binaries provided by
11 Google. The latter portions describe how to build perl native using
12 one of the toolchains available on the Play Store.
13
15 This document describes how to set up your host environment when
16 attempting to build Perl for Android.
17
19 These instructions assume an Unixish build environment on your host
20 system; they've been tested on Linux and OS X, and may work on Cygwin
21 and MSYS. While Google also provides an NDK for Windows, these steps
22 won't work native there, although it may be possible to cross-compile
23 through different means.
24 If your host system's architecture is 32 bits, remember to change the
26 "x86_64"'s below to "x86"'s. On a similar vein, the examples below use
27 the 4.8 toolchain; if you want to use something older or newer (for
28 example, the 4.4.3 toolchain included in the 8th revision of the NDK),
29 just change those to the relevant version.
30 Get the Android Native Development Kit (NDK)
32 You can download the NDK from
33 <https://developer.android.com/tools/sdk/ndk/index.html>. You'll want
34 the normal, non-legacy version.
35 Determine the architecture you'll be cross-compiling for
37 There's three possible options: arm-linux-androideabi for ARM, mipsel-
38 linux-android for MIPS, and simply x86 for x86. As of 2014, most
39 Android devices run on ARM, so that is generally a safe bet.
40 With those two in hand, you should add
42 $ANDROID_NDK/toolchains/$TARGETARCH-4.8/prebuilt/`uname | tr '[A-Z]' '[a-z]'`-x86_64/bin
44 to your "PATH", where $ANDROID_NDK is the location where you unpacked
46 the NDK, and $TARGETARCH is your target's architecture.
47 Set up a standalone toolchain
49 This creates a working sysroot that we can feed to Configure later.
50 $ export ANDROID_TOOLCHAIN=/tmp/my-toolchain-$TARGETARCH
52 $ export SYSROOT=$ANDROID_TOOLCHAIN/sysroot
53 $ $ANDROID_NDK/build/tools/make-standalone-toolchain.sh \
54 --platform=android-9 \
55 --install-dir=$ANDROID_TOOLCHAIN \
56 --system=`uname | tr '[A-Z]' '[a-z]'`-x86_64 \
57 --toolchain=$TARGETARCH-4.8
58 adb or ssh?
60 adb is the Android Debug Bridge. For our purposes, it's basically a
61 way of establishing an ssh connection to an Android device without
62 having to install anything on the device itself, as long as the device
63 is either on the same local network as the host, or it is connected to
64 the host through USB.
65 Perl can be cross-compiled using either adb or a normal ssh connection;
67 in general, if you can connect your device to the host using a USB
68 port, or if you don't feel like installing an sshd app on your device,
69 you may want to use adb, although you may be forced to switch to ssh if
70 your device is not rooted and you're unlucky -- more on that later.
71 Alternatively, if you're cross-compiling to an emulator, you'll have to
72 use adb.
73 adb
75 To use adb, download the Android SDK from
77 <https://developer.android.com/sdk/index.html>. The "SDK Tools Only"
78 version should suffice -- if you downloaded the ADT Bundle, you can
79 find the sdk under $ADT_BUNDLE/sdk/.
80 Add $ANDROID_SDK/platform-tools to your "PATH", which should give you
82 access to adb. You'll now have to find your device's name using "adb
83 devices", and later pass that to Configure through
84 "-Dtargethost=$DEVICE".
85 However, before calling Configure, you need to check if using adb is a
87 viable choice in the first place. Because Android doesn't have a /tmp,
88 nor does it allow executables in the sdcard, we need to find somewhere
89 in the device for Configure to put some files in, as well as for the
90 tests to run in. If your device is rooted, then you're good. Try
91 running these:
92 $ export TARGETDIR=/mnt/asec/perl
94 $ adb -s $DEVICE shell "echo sh -c '\"mkdir $TARGETDIR\"' | su --"
95 Which will create the directory we need, and you can move on to the
97 next step. /mnt/asec is mounted as a tmpfs in Android, but it's only
98 accessible to root.
99 If your device is not rooted, you may still be in luck. Try running
101 this:
102 $ export TARGETDIR=/data/local/tmp/perl
104 $ adb -s $DEVICE shell "mkdir $TARGETDIR"
105 If the command works, you can move to the next step, but beware: You'll
107 have to remove the directory from the device once you are done! Unlike
108 /mnt/asec, /data/local/tmp may not get automatically garbage collected
109 once you shut off the phone.
110 If neither of those work, then you can't use adb to cross-compile to
112 your device. Either try rooting it, or go for the ssh route.
113 ssh
115 To use ssh, you'll need to install and run a sshd app and set it up
117 properly. There are several paid and free apps that do this rather
118 easily, so you should be able to spot one on the store. Remember that
119 Perl requires a passwordless connection, so set up a public key.
120 Note that several apps spew crap to stderr every time you connect,
122 which can throw off Configure. You may need to monkeypatch the part of
123 Configure that creates "run-ssh" to have it discard stderr.
124 Since you're using ssh, you'll have to pass some extra arguments to
126 Configure:
127 -Dtargetrun=ssh -Dtargethost=$TARGETHOST -Dtargetuser=$TARGETUSER -Dtargetport=$TARGETPORT
129 Configure and beyond
131 With all of the previous done, you're now ready to call Configure.
132 If using adb, a "basic" Configure line will look like this:
134 $ ./Configure -des -Dusedevel -Dusecrosscompile -Dtargetrun=adb \
136 -Dcc=$TARGETARCH-gcc \
137 -Dsysroot=$SYSROOT \
138 -Dtargetdir=$TARGETDIR \
139 -Dtargethost=$DEVICE
140 If using ssh, it's not too different -- we just change targetrun to
142 ssh, and pass in targetuser and targetport. It ends up looking like
143 this:
144 $ ./Configure -des -Dusedevel -Dusecrosscompile -Dtargetrun=ssh \
146 -Dcc=$TARGETARCH-gcc \
147 -Dsysroot=$SYSROOT \
148 -Dtargetdir=$TARGETDIR \
149 -Dtargethost="$TARGETHOST" \
150 -Dtargetuser=$TARGETUSER \
151 -Dtargetport=$TARGETPORT
152 Now you're ready to run "make" and "make test"!
154 As a final word of warning, if you're using adb, "make test" may appear
156 to hang; this is because it doesn't output anything until it finishes
157 running all tests. You can check its progress by logging into the
158 device, moving to $TARGETDIR, and looking at the file output.stdout.
159 Notes
161 · If you are targetting x86 Android, you will have to change
163 "$TARGETARCH-gcc" to "i686-linux-android-gcc".
164 · On some older low-end devices -- think early 2.2 era -- some tests,
166 particularly t/re/uniprops.t, may crash the phone, causing it to
167 turn itself off once, and then back on again.
168
170 While Google doesn't provide a native toolchain for Android, you can
171 still get one from the Play Store.
172 CCTools
174 You may be able to get the CCTools app, which is free. Keep in mind
175 that you want a full toolchain; some apps tend to default to installing
176 only a barebones version without some important utilities, like ar or
177 nm.
178 Once you have the toolchain set up properly, the only remaining hurdle
180 is actually locating where in the device it was installed in. For
181 example, CCTools installs its toolchain in
182 /data/data/com.pdaxrom.cctools/root/cctools. With the path in hand,
183 compiling perl is little more than:
184 export SYSROOT=<location of the native toolchain>
186 export LD_LIBRARY_PATH="$SYSROOT/lib:`pwd`:`pwd`/lib:`pwd`/lib/auto:$LD_LIBRARY_PATH"
187 sh Configure -des -Dsysroot=$SYSROOT -Alibpth="/system/lib /vendor/lib"
188 Termux
190 Termux <https://termux.com/> provides an Android terminal emulator and
191 Linux environment. It comes with a cross-compiled perl already
192 installed.
193 Natively compiling perl 5.30 or later should be as straightforward as:
195 sh Configure -des -Alibpth="/system/lib /vendor/lib"
197 This certainly works on Android 8.1 (Oreo) at least...
199
201 Brian Fraser <fraserbn@gmail.com>
202perl v5.32.1 2021-03-31 PERLANDROID(1)