| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "PERLANDROID 1" |
| 58 |
.TH PERLANDROID 1 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
perlandroid \- Perl under Android |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
The first portions of this document contains instructions |
| 68 |
to cross-compile Perl for Android 2.0 and later, using the |
| 69 |
binaries provided by Google. The latter portions describe how to build |
| 70 |
perl native using one of the toolchains available on the Play Store. |
| 71 |
.SH DESCRIPTION |
| 72 |
.IX Header "DESCRIPTION" |
| 73 |
This document describes how to set up your host environment when |
| 74 |
attempting to build Perl for Android. |
| 75 |
.SH Cross-compilation |
| 76 |
.IX Header "Cross-compilation" |
| 77 |
These instructions assume an Unixish build environment on your host system; |
| 78 |
they've been tested on Linux and OS X, and may work on Cygwin and MSYS. |
| 79 |
While Google also provides an NDK for Windows, these steps won't work |
| 80 |
native there, although it may be possible to cross-compile through different |
| 81 |
means. |
| 82 |
.PP |
| 83 |
If your host system's architecture is 32 bits, remember to change the |
| 84 |
\&\f(CW\*(C`x86_64\*(C'\fR's below to \f(CW\*(C`x86\*(C'\fR's. On a similar vein, the examples below |
| 85 |
use the 4.8 toolchain; if you want to use something older or newer (for |
| 86 |
example, the 4.4.3 toolchain included in the 8th revision of the NDK), just |
| 87 |
change those to the relevant version. |
| 88 |
.SS "Get the Android Native Development Kit (NDK)" |
| 89 |
.IX Subsection "Get the Android Native Development Kit (NDK)" |
| 90 |
You can download the NDK from <https://developer.android.com/tools/sdk/ndk/index.html>. |
| 91 |
You'll want the normal, non-legacy version. |
| 92 |
.SS "Determine the architecture you'll be cross-compiling for" |
| 93 |
.IX Subsection "Determine the architecture you'll be cross-compiling for" |
| 94 |
There's three possible options: arm-linux-androideabi for ARM, |
| 95 |
mipsel-linux-android for MIPS, and simply x86 for x86. |
| 96 |
As of 2014, most Android devices run on ARM, so that is generally a safe bet. |
| 97 |
.PP |
| 98 |
With those two in hand, you should add |
| 99 |
.PP |
| 100 |
.Vb 1 |
| 101 |
\& $ANDROID_NDK/toolchains/$TARGETARCH\-4.8/prebuilt/\`uname | tr \*(Aq[A\-Z]\*(Aq \*(Aq[a\-z]\*(Aq\`\-x86_64/bin |
| 102 |
.Ve |
| 103 |
.PP |
| 104 |
to your \f(CW\*(C`PATH\*(C'\fR, where \f(CW$ANDROID_NDK\fR is the location where you unpacked the |
| 105 |
NDK, and \f(CW$TARGETARCH\fR is your target's architecture. |
| 106 |
.SS "Set up a standalone toolchain" |
| 107 |
.IX Subsection "Set up a standalone toolchain" |
| 108 |
This creates a working sysroot that we can feed to Configure later. |
| 109 |
.PP |
| 110 |
.Vb 7 |
| 111 |
\& $ export ANDROID_TOOLCHAIN=/tmp/my\-toolchain\-$TARGETARCH |
| 112 |
\& $ export SYSROOT=$ANDROID_TOOLCHAIN/sysroot |
| 113 |
\& $ $ANDROID_NDK/build/tools/make\-standalone\-toolchain.sh \e |
| 114 |
\& \-\-platform=android\-9 \e |
| 115 |
\& \-\-install\-dir=$ANDROID_TOOLCHAIN \e |
| 116 |
\& \-\-system=\`uname | tr \*(Aq[A\-Z]\*(Aq \*(Aq[a\-z]\*(Aq\`\-x86_64 \e |
| 117 |
\& \-\-toolchain=$TARGETARCH\-4.8 |
| 118 |
.Ve |
| 119 |
.SS "adb or ssh?" |
| 120 |
.IX Subsection "adb or ssh?" |
| 121 |
adb is the Android Debug Bridge. For our purposes, it's basically a way |
| 122 |
of establishing an ssh connection to an Android device without having to |
| 123 |
install anything on the device itself, as long as the device is either on |
| 124 |
the same local network as the host, or it is connected to the host through |
| 125 |
USB. |
| 126 |
.PP |
| 127 |
Perl can be cross-compiled using either adb or a normal ssh connection; |
| 128 |
in general, if you can connect your device to the host using a USB port, |
| 129 |
or if you don't feel like installing an sshd app on your device, |
| 130 |
you may want to use adb, although you may be forced to switch to ssh if |
| 131 |
your device is not rooted and you're unlucky \-\- more on that later. |
| 132 |
Alternatively, if you're cross-compiling to an emulator, you'll have to |
| 133 |
use adb. |
| 134 |
.PP |
| 135 |
\fIadb\fR |
| 136 |
.IX Subsection "adb" |
| 137 |
.PP |
| 138 |
To use adb, download the Android SDK from <https://developer.android.com/sdk/index.html>. |
| 139 |
The "SDK Tools Only" version should suffice \-\- if you downloaded the ADT |
| 140 |
Bundle, you can find the sdk under \fR\f(CI$ADT_BUNDLE\fR\fI/sdk/\fR. |
| 141 |
.PP |
| 142 |
Add \fR\f(CI$ANDROID_SDK\fR\fI/platform\-tools\fR to your \f(CW\*(C`PATH\*(C'\fR, which should give you access |
| 143 |
to adb. You'll now have to find your device's name using \f(CW\*(C`adb devices\*(C'\fR, |
| 144 |
and later pass that to Configure through \f(CW\*(C`\-Dtargethost=$DEVICE\*(C'\fR. |
| 145 |
.PP |
| 146 |
However, before calling Configure, you need to check if using adb is a |
| 147 |
viable choice in the first place. Because Android doesn't have a \fI/tmp\fR, |
| 148 |
nor does it allow executables in the sdcard, we need to find somewhere in |
| 149 |
the device for Configure to put some files in, as well as for the tests |
| 150 |
to run in. If your device is rooted, then you're good. Try running these: |
| 151 |
.PP |
| 152 |
.Vb 2 |
| 153 |
\& $ export TARGETDIR=/mnt/asec/perl |
| 154 |
\& $ adb \-s $DEVICE shell "echo sh \-c \*(Aq\e"mkdir $TARGETDIR\e"\*(Aq | su \-\-" |
| 155 |
.Ve |
| 156 |
.PP |
| 157 |
Which will create the directory we need, and you can move on to the next |
| 158 |
step. \fI/mnt/asec\fR is mounted as a tmpfs in Android, but it's only |
| 159 |
accessible to root. |
| 160 |
.PP |
| 161 |
If your device is not rooted, you may still be in luck. Try running this: |
| 162 |
.PP |
| 163 |
.Vb 2 |
| 164 |
\& $ export TARGETDIR=/data/local/tmp/perl |
| 165 |
\& $ adb \-s $DEVICE shell "mkdir $TARGETDIR" |
| 166 |
.Ve |
| 167 |
.PP |
| 168 |
If the command works, you can move to the next step, but beware: |
| 169 |
\&\fBYou'll have to remove the directory from the device once you are done! |
| 170 |
Unlike \fR\f(BI/mnt/asec\fR\fB, \fR\f(BI/data/local/tmp\fR\fB may not get automatically garbage |
| 171 |
collected once you shut off the phone\fR. |
| 172 |
.PP |
| 173 |
If neither of those work, then you can't use adb to cross-compile to your |
| 174 |
device. Either try rooting it, or go for the ssh route. |
| 175 |
.PP |
| 176 |
\fIssh\fR |
| 177 |
.IX Subsection "ssh" |
| 178 |
.PP |
| 179 |
To use ssh, you'll need to install and run a sshd app and set it up |
| 180 |
properly. There are several paid and free apps that do this rather |
| 181 |
easily, so you should be able to spot one on the store. |
| 182 |
Remember that Perl requires a passwordless connection, so set up a |
| 183 |
public key. |
| 184 |
.PP |
| 185 |
Note that several apps spew crap to stderr every time you |
| 186 |
connect, which can throw off Configure. You may need to monkeypatch |
| 187 |
the part of Configure that creates \f(CW\*(C`run\-ssh\*(C'\fR to have it discard stderr. |
| 188 |
.PP |
| 189 |
Since you're using ssh, you'll have to pass some extra arguments to |
| 190 |
Configure: |
| 191 |
.PP |
| 192 |
.Vb 1 |
| 193 |
\& \-Dtargetrun=ssh \-Dtargethost=$TARGETHOST \-Dtargetuser=$TARGETUSER \-Dtargetport=$TARGETPORT |
| 194 |
.Ve |
| 195 |
.SS "Configure and beyond" |
| 196 |
.IX Subsection "Configure and beyond" |
| 197 |
With all of the previous done, you're now ready to call Configure. |
| 198 |
.PP |
| 199 |
If using adb, a "basic" Configure line will look like this: |
| 200 |
.PP |
| 201 |
.Vb 5 |
| 202 |
\& $ ./Configure \-des \-Dusedevel \-Dusecrosscompile \-Dtargetrun=adb \e |
| 203 |
\& \-Dcc=$TARGETARCH\-gcc \e |
| 204 |
\& \-Dsysroot=$SYSROOT \e |
| 205 |
\& \-Dtargetdir=$TARGETDIR \e |
| 206 |
\& \-Dtargethost=$DEVICE |
| 207 |
.Ve |
| 208 |
.PP |
| 209 |
If using ssh, it's not too different \-\- we just change targetrun to ssh, |
| 210 |
and pass in targetuser and targetport. It ends up looking like this: |
| 211 |
.PP |
| 212 |
.Vb 7 |
| 213 |
\& $ ./Configure \-des \-Dusedevel \-Dusecrosscompile \-Dtargetrun=ssh \e |
| 214 |
\& \-Dcc=$TARGETARCH\-gcc \e |
| 215 |
\& \-Dsysroot=$SYSROOT \e |
| 216 |
\& \-Dtargetdir=$TARGETDIR \e |
| 217 |
\& \-Dtargethost="$TARGETHOST" \e |
| 218 |
\& \-Dtargetuser=$TARGETUSER \e |
| 219 |
\& \-Dtargetport=$TARGETPORT |
| 220 |
.Ve |
| 221 |
.PP |
| 222 |
Now you're ready to run \f(CW\*(C`make\*(C'\fR and \f(CW\*(C`make test\*(C'\fR! |
| 223 |
.PP |
| 224 |
As a final word of warning, if you're using adb, \f(CW\*(C`make test\*(C'\fR may appear to |
| 225 |
hang; this is because it doesn't output anything until it finishes |
| 226 |
running all tests. You can check its progress by logging into the |
| 227 |
device, moving to \fR\f(CI$TARGETDIR\fR\fI\fR, and looking at the file \fIoutput.stdout\fR. |
| 228 |
.PP |
| 229 |
\fINotes\fR |
| 230 |
.IX Subsection "Notes" |
| 231 |
.IP \(bu 4 |
| 232 |
If you are targetting x86 Android, you will have to change \f(CW\*(C`$TARGETARCH\-gcc\*(C'\fR |
| 233 |
to \f(CW\*(C`i686\-linux\-android\-gcc\*(C'\fR. |
| 234 |
.IP \(bu 4 |
| 235 |
On some older low-end devices \-\- think early 2.2 era \-\- some tests, |
| 236 |
particularly \fIt/re/uniprops.t\fR, may crash the phone, causing it to turn |
| 237 |
itself off once, and then back on again. |
| 238 |
.SH "Native Builds" |
| 239 |
.IX Header "Native Builds" |
| 240 |
While Google doesn't provide a native toolchain for Android, |
| 241 |
you can still get one from the Play Store. |
| 242 |
.SS CCTools |
| 243 |
.IX Subsection "CCTools" |
| 244 |
You may be able to get the CCTools app, which is free. |
| 245 |
Keep in mind that you want a full toolchain; |
| 246 |
some apps tend to default to installing only a barebones |
| 247 |
version without some important utilities, like ar or nm. |
| 248 |
.PP |
| 249 |
Once you have the toolchain set up properly, the only |
| 250 |
remaining hurdle is actually locating where in the device it was installed |
| 251 |
in. For example, CCTools installs its toolchain in |
| 252 |
\&\fI/data/data/com.pdaxrom.cctools/root/cctools\fR. With the path in hand, |
| 253 |
compiling perl is little more than: |
| 254 |
.PP |
| 255 |
.Vb 3 |
| 256 |
\& export SYSROOT=<location of the native toolchain> |
| 257 |
\& export LD_LIBRARY_PATH="$SYSROOT/lib:\`pwd\`:\`pwd\`/lib:\`pwd\`/lib/auto:$LD_LIBRARY_PATH" |
| 258 |
\& sh Configure \-des \-Dsysroot=$SYSROOT \-Alibpth="/system/lib /vendor/lib" |
| 259 |
.Ve |
| 260 |
.SS Termux |
| 261 |
.IX Subsection "Termux" |
| 262 |
Termux <https://termux.com/> provides an Android terminal emulator and Linux environment. |
| 263 |
It comes with a cross-compiled perl already installed. |
| 264 |
.PP |
| 265 |
Natively compiling perl 5.30 or later should be as straightforward as: |
| 266 |
.PP |
| 267 |
.Vb 1 |
| 268 |
\& sh Configure \-des \-Alibpth="/system/lib /vendor/lib" |
| 269 |
.Ve |
| 270 |
.PP |
| 271 |
This certainly works on Android 8.1 (Oreo) at least... |
| 272 |
.SH AUTHOR |
| 273 |
.IX Header "AUTHOR" |
| 274 |
Brian Fraser <[email protected]> |