Debian Codegraph @

upstream/debian-unstable/man1/perlandroid.1

raw
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]>