1PERLANDROID(1)         Perl Programmers Reference Guide         PERLANDROID(1)
2
3
4

NAME

6       perlandroid - Perl under Android
7

SYNOPSIS

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

DESCRIPTION

15       This document describes how to set up your host environment when
16       attempting to build Perl for Android.
17

Cross-compilation

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
25       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
31   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
36   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
41       With those two in hand, you should add
42
43         $ANDROID_NDK/toolchains/$TARGETARCH-4.8/prebuilt/`uname | tr '[A-Z]' '[a-z]'`-x86_64/bin
44
45       to your "PATH", where $ANDROID_NDK is the location where you unpacked
46       the NDK, and $TARGETARCH is your target's architecture.
47
48   Set up a standalone toolchain
49       This creates a working sysroot that we can feed to Configure later.
50
51           $ 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
59   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
66       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
74       adb
75
76       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
81       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
86       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
93           $ export TARGETDIR=/mnt/asec/perl
94           $ adb -s $DEVICE shell "echo sh -c '\"mkdir $TARGETDIR\"' | su --"
95
96       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
100       If your device is not rooted, you may still be in luck. Try running
101       this:
102
103           $ export TARGETDIR=/data/local/tmp/perl
104           $ adb -s $DEVICE shell "mkdir $TARGETDIR"
105
106       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
111       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
114       ssh
115
116       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
121       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
125       Since you're using ssh, you'll have to pass some extra arguments to
126       Configure:
127
128         -Dtargetrun=ssh -Dtargethost=$TARGETHOST -Dtargetuser=$TARGETUSER -Dtargetport=$TARGETPORT
129
130   Configure and beyond
131       With all of the previous done, you're now ready to call Configure.
132
133       If using adb, a "basic" Configure line will look like this:
134
135         $ ./Configure -des -Dusedevel -Dusecrosscompile -Dtargetrun=adb \
136             -Dcc=$TARGETARCH-gcc   \
137             -Dsysroot=$SYSROOT     \
138             -Dtargetdir=$TARGETDIR \
139             -Dtargethost=$DEVICE
140
141       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
145         $ ./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
153       Now you're ready to run "make" and "make test"!
154
155       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
160       Notes
161
162       •   If you are targetting x86 Android, you will have to change
163           "$TARGETARCH-gcc" to "i686-linux-android-gcc".
164
165       •   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

Native Builds

170       While Google doesn't provide a native toolchain for Android, you can
171       still get one from the Play Store.
172
173   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
179       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
185        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
189   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
194       Natively compiling perl 5.30 or later should be as straightforward as:
195
196        sh Configure -des -Alibpth="/system/lib /vendor/lib"
197
198       This certainly works on Android 8.1 (Oreo) at least...
199

AUTHOR

201       Brian Fraser <fraserbn@gmail.com>
202
203
204
205perl v5.34.1                      2022-03-15                    PERLANDROID(1)
Impressum