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