Debian Codegraph @

upstream/fedora-44/man1/perlandroid.1

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