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