diff options
Diffstat (limited to 'upstream/debian-unstable/man1/perlandroid.1')
| -rw-r--r-- | upstream/debian-unstable/man1/perlandroid.1 | 274 |
1 files changed, 274 insertions, 0 deletions
diff --git a/upstream/debian-unstable/man1/perlandroid.1 b/upstream/debian-unstable/man1/perlandroid.1 new file mode 100644 index 00000000..93e6a090 --- /dev/null +++ b/upstream/debian-unstable/man1/perlandroid.1 @@ -0,0 +1,274 @@ +.\" -*- mode: troff; coding: utf-8 -*- +.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. +.ie n \{\ +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" ======================================================================== +.\" +.IX Title "PERLANDROID 1" +.TH PERLANDROID 1 2024-01-12 "perl v5.38.2" "Perl Programmers Reference Guide" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH NAME +perlandroid \- Perl under Android +.SH SYNOPSIS +.IX Header "SYNOPSIS" +The first portions of this document contains instructions +to cross-compile Perl for Android 2.0 and later, using the +binaries provided by Google. The latter portions describe how to build +perl native using one of the toolchains available on the Play Store. +.SH DESCRIPTION +.IX Header "DESCRIPTION" +This document describes how to set up your host environment when +attempting to build Perl for Android. +.SH Cross-compilation +.IX Header "Cross-compilation" +These instructions assume an Unixish build environment on your host system; +they've been tested on Linux and OS X, and may work on Cygwin and MSYS. +While Google also provides an NDK for Windows, these steps won't work +native there, although it may be possible to cross-compile through different +means. +.PP +If your host system's architecture is 32 bits, remember to change the +\&\f(CW\*(C`x86_64\*(C'\fR's below to \f(CW\*(C`x86\*(C'\fR's. On a similar vein, the examples below +use the 4.8 toolchain; if you want to use something older or newer (for +example, the 4.4.3 toolchain included in the 8th revision of the NDK), just +change those to the relevant version. +.SS "Get the Android Native Development Kit (NDK)" +.IX Subsection "Get the Android Native Development Kit (NDK)" +You can download the NDK from <https://developer.android.com/tools/sdk/ndk/index.html>. +You'll want the normal, non-legacy version. +.SS "Determine the architecture you'll be cross-compiling for" +.IX Subsection "Determine the architecture you'll be cross-compiling for" +There's three possible options: arm-linux-androideabi for ARM, +mipsel-linux-android for MIPS, and simply x86 for x86. +As of 2014, most Android devices run on ARM, so that is generally a safe bet. +.PP +With those two in hand, you should add +.PP +.Vb 1 +\& $ANDROID_NDK/toolchains/$TARGETARCH\-4.8/prebuilt/\`uname | tr \*(Aq[A\-Z]\*(Aq \*(Aq[a\-z]\*(Aq\`\-x86_64/bin +.Ve +.PP +to your \f(CW\*(C`PATH\*(C'\fR, where \f(CW$ANDROID_NDK\fR is the location where you unpacked the +NDK, and \f(CW$TARGETARCH\fR is your target's architecture. +.SS "Set up a standalone toolchain" +.IX Subsection "Set up a standalone toolchain" +This creates a working sysroot that we can feed to Configure later. +.PP +.Vb 7 +\& $ export ANDROID_TOOLCHAIN=/tmp/my\-toolchain\-$TARGETARCH +\& $ export SYSROOT=$ANDROID_TOOLCHAIN/sysroot +\& $ $ANDROID_NDK/build/tools/make\-standalone\-toolchain.sh \e +\& \-\-platform=android\-9 \e +\& \-\-install\-dir=$ANDROID_TOOLCHAIN \e +\& \-\-system=\`uname | tr \*(Aq[A\-Z]\*(Aq \*(Aq[a\-z]\*(Aq\`\-x86_64 \e +\& \-\-toolchain=$TARGETARCH\-4.8 +.Ve +.SS "adb or ssh?" +.IX Subsection "adb or ssh?" +adb is the Android Debug Bridge. For our purposes, it's basically a way +of establishing an ssh connection to an Android device without having to +install anything on the device itself, as long as the device is either on +the same local network as the host, or it is connected to the host through +USB. +.PP +Perl can be cross-compiled using either adb or a normal ssh connection; +in general, if you can connect your device to the host using a USB port, +or if you don't feel like installing an sshd app on your device, +you may want to use adb, although you may be forced to switch to ssh if +your device is not rooted and you're unlucky \-\- more on that later. +Alternatively, if you're cross-compiling to an emulator, you'll have to +use adb. +.PP +\fIadb\fR +.IX Subsection "adb" +.PP +To use adb, download the Android SDK from <https://developer.android.com/sdk/index.html>. +The "SDK Tools Only" version should suffice \-\- if you downloaded the ADT +Bundle, you can find the sdk under \fR\f(CI$ADT_BUNDLE\fR\fI/sdk/\fR. +.PP +Add \fR\f(CI$ANDROID_SDK\fR\fI/platform\-tools\fR to your \f(CW\*(C`PATH\*(C'\fR, which should give you access +to adb. You'll now have to find your device's name using \f(CW\*(C`adb devices\*(C'\fR, +and later pass that to Configure through \f(CW\*(C`\-Dtargethost=$DEVICE\*(C'\fR. +.PP +However, before calling Configure, you need to check if using adb is a +viable choice in the first place. Because Android doesn't have a \fI/tmp\fR, +nor does it allow executables in the sdcard, we need to find somewhere in +the device for Configure to put some files in, as well as for the tests +to run in. If your device is rooted, then you're good. Try running these: +.PP +.Vb 2 +\& $ export TARGETDIR=/mnt/asec/perl +\& $ adb \-s $DEVICE shell "echo sh \-c \*(Aq\e"mkdir $TARGETDIR\e"\*(Aq | su \-\-" +.Ve +.PP +Which will create the directory we need, and you can move on to the next +step. \fI/mnt/asec\fR is mounted as a tmpfs in Android, but it's only +accessible to root. +.PP +If your device is not rooted, you may still be in luck. Try running this: +.PP +.Vb 2 +\& $ export TARGETDIR=/data/local/tmp/perl +\& $ adb \-s $DEVICE shell "mkdir $TARGETDIR" +.Ve +.PP +If the command works, you can move to the next step, but beware: +\&\fBYou'll have to remove the directory from the device once you are done! +Unlike \fR\f(BI/mnt/asec\fR\fB, \fR\f(BI/data/local/tmp\fR\fB may not get automatically garbage +collected once you shut off the phone\fR. +.PP +If neither of those work, then you can't use adb to cross-compile to your +device. Either try rooting it, or go for the ssh route. +.PP +\fIssh\fR +.IX Subsection "ssh" +.PP +To use ssh, you'll need to install and run a sshd app and set it up +properly. There are several paid and free apps that do this rather +easily, so you should be able to spot one on the store. +Remember that Perl requires a passwordless connection, so set up a +public key. +.PP +Note that several apps spew crap to stderr every time you +connect, which can throw off Configure. You may need to monkeypatch +the part of Configure that creates \f(CW\*(C`run\-ssh\*(C'\fR to have it discard stderr. +.PP +Since you're using ssh, you'll have to pass some extra arguments to +Configure: +.PP +.Vb 1 +\& \-Dtargetrun=ssh \-Dtargethost=$TARGETHOST \-Dtargetuser=$TARGETUSER \-Dtargetport=$TARGETPORT +.Ve +.SS "Configure and beyond" +.IX Subsection "Configure and beyond" +With all of the previous done, you're now ready to call Configure. +.PP +If using adb, a "basic" Configure line will look like this: +.PP +.Vb 5 +\& $ ./Configure \-des \-Dusedevel \-Dusecrosscompile \-Dtargetrun=adb \e +\& \-Dcc=$TARGETARCH\-gcc \e +\& \-Dsysroot=$SYSROOT \e +\& \-Dtargetdir=$TARGETDIR \e +\& \-Dtargethost=$DEVICE +.Ve +.PP +If using ssh, it's not too different \-\- we just change targetrun to ssh, +and pass in targetuser and targetport. It ends up looking like this: +.PP +.Vb 7 +\& $ ./Configure \-des \-Dusedevel \-Dusecrosscompile \-Dtargetrun=ssh \e +\& \-Dcc=$TARGETARCH\-gcc \e +\& \-Dsysroot=$SYSROOT \e +\& \-Dtargetdir=$TARGETDIR \e +\& \-Dtargethost="$TARGETHOST" \e +\& \-Dtargetuser=$TARGETUSER \e +\& \-Dtargetport=$TARGETPORT +.Ve +.PP +Now you're ready to run \f(CW\*(C`make\*(C'\fR and \f(CW\*(C`make test\*(C'\fR! +.PP +As a final word of warning, if you're using adb, \f(CW\*(C`make test\*(C'\fR may appear to +hang; this is because it doesn't output anything until it finishes +running all tests. You can check its progress by logging into the +device, moving to \fR\f(CI$TARGETDIR\fR\fI\fR, and looking at the file \fIoutput.stdout\fR. +.PP +\fINotes\fR +.IX Subsection "Notes" +.IP \(bu 4 +If you are targetting x86 Android, you will have to change \f(CW\*(C`$TARGETARCH\-gcc\*(C'\fR +to \f(CW\*(C`i686\-linux\-android\-gcc\*(C'\fR. +.IP \(bu 4 +On some older low-end devices \-\- think early 2.2 era \-\- some tests, +particularly \fIt/re/uniprops.t\fR, may crash the phone, causing it to turn +itself off once, and then back on again. +.SH "Native Builds" +.IX Header "Native Builds" +While Google doesn't provide a native toolchain for Android, +you can still get one from the Play Store. +.SS CCTools +.IX Subsection "CCTools" +You may be able to get the CCTools app, which is free. +Keep in mind that you want a full toolchain; +some apps tend to default to installing only a barebones +version without some important utilities, like ar or nm. +.PP +Once you have the toolchain set up properly, the only +remaining hurdle is actually locating where in the device it was installed +in. For example, CCTools installs its toolchain in +\&\fI/data/data/com.pdaxrom.cctools/root/cctools\fR. With the path in hand, +compiling perl is little more than: +.PP +.Vb 3 +\& export SYSROOT=<location of the native toolchain> +\& export LD_LIBRARY_PATH="$SYSROOT/lib:\`pwd\`:\`pwd\`/lib:\`pwd\`/lib/auto:$LD_LIBRARY_PATH" +\& sh Configure \-des \-Dsysroot=$SYSROOT \-Alibpth="/system/lib /vendor/lib" +.Ve +.SS Termux +.IX Subsection "Termux" +Termux <https://termux.com/> provides an Android terminal emulator and Linux environment. +It comes with a cross-compiled perl already installed. +.PP +Natively compiling perl 5.30 or later should be as straightforward as: +.PP +.Vb 1 +\& sh Configure \-des \-Alibpth="/system/lib /vendor/lib" +.Ve +.PP +This certainly works on Android 8.1 (Oreo) at least... +.SH AUTHOR +.IX Header "AUTHOR" +Brian Fraser <fraserbn@gmail.com> |