I Love My PinePhone

The PinePhone's initial presentation engenders confidence. Despite the cost, the box it comes in feels nice and gives me the sense that I have a quality product in my hands. The phone comes in a protective sleeve, with a USB-C cable and a leaflet with some information. It isn't a manual, but it does link to the Pine64 wiki, which is close enough to one.

I care about the longevity of my gadgets, so I went on Thingiverse and found a hard case design for the PinePhone. I could've spent more time sanding it down and making it look nice, but it was good enough for me at the time. I'm still inexperienced with making "good" 3D-printed parts. The roughness led to a few minor scratches on the back cover, but it's saved my PinePhone from worse damage on several occasions.

The PinePhone shuts itself off upon impact. I think that's a bug, rather than a feature, but I'm usually careful enough that it doesn't happen often. (In fact, it's usually when others are handling my phone that it falls.)

Per this Reddit comment, I purchased a pack of cheap tempered glass screen protectors designed for the iPhone Max XS. I haven't dropped the phone enough to put it to its limits, but thus far it's done well to keep the front of the phone free from scratches.

The PinePhone arrives flashed with a "factory test image" which is suitable for verifying that the hardware on the PinePhone is functional before you proceed with it configuring it. The test for the modem was finicky, and the motor test did not work. The device, at this point, was well past the limited warranty, so I decided to press regardless.

These issues were non-existent when I did install a proper operating system to the phone, so I suspect there were actually some bugs in factorytest. Experiencing bugs seems to be consistent with other users' experiences.

Now that we've got the phone powered up, we have some decisions to make. What Linux distribution do we want to install on the phone? Furthermore, what desktop environment do we want use?

The PINE64 wiki has a page listing most of the distributions that are known to work on the PinePhone, and the choices are surprisingly diverse. On one end of the spectrum, there's GloDroid, which is a port of Android to the PinePhone. That might seem like it defeats the purpose of using the PinePhone, but I'm sure it can be used for a use-case similar to dual-booting Windows and Linux. Moving further from Android, we have distributions like Ubuntu Touch which actually use parts of Android to interact with the underlying phone, but implement a full Linux userland and display server on top of that. Personally, I think this is a really cool approach for making ordinary Android phones more useful, and you can read more about the approach here. Finally, we've got regular mainline Linux, with both desktop-oriented and mobile-oriented distributions. You can run Gentoo, Fedora, Arch Linux ARM, etc. on the Pinephone, or you can opt for PostmarketOS (Alpine-derivative) or Mobian (Debian-derivative).

There are some options that might not fit into my arbitrary "spectrum" idea, like Sailfish OS. I don't know enough about it to say where it falls. Regardless, I hope you're taking away that with an open design, you have lots of options.

One last choice I want to mention is the SqueakPhone, which appears to be based on PostmarketOS, but the userland is almost entirely written in Smalltalk.

It's a good time to be hacking on mobile devices. We might not be in the golden age, but we're certainly marching toward it.

As much as I like running Gentoo on most of my machines, I figured that would be a bit much for me. It also doesn't seem like a good idea to constantly be compiling things from source on my phone, which probably doesn't have great thermals (and I assume it would take a few days to compile e.g. Firefox unless I took the time to properly set up distcc.)

So I went with PostmarketOS. I admire the design of Alpine Linux, and I think that PostmarketOS is the project making the most progress in the mobile Linux space. Now, PostmarketOS comes with several options for a desktop environment. The three I consider to be the "main" options are Sxmo, Plasma Mobile, and Phosh. Sxmo is basically a mobile-oriented dwm fork. I'm a former dwm user and current AwesomeWM user, but running a tiling window manager on my phone seems a bit much, even for me. And in the Gnome versus KDE footballing⁵, I like Gnome better, and I prefer GTK+ over Qt, so I went with Phosh.

Once you know what you want to install on your PinePhone, the process is straightforward. Flash a distribution image to an SD card, pop it into the phone, and power it on. From there, you can install it to EMMC.

The internal EMMC on the PinePhone I have is 16GB (later models have a 32GB EMMC). My music folder far exceeds 16GB, so I bought an SD card to use as extra storage. Unlike Android, a regular Linux distribution gives you some flexibility with how you split storage up across the various storage devices. I set up a LUKS-encrypted ext4 filesystem on the SD card and threw a script into local.d to decrypt it and mount it on top of /home. I haven't had a single issue with it, so we're already doing much better than Android. I can store basically whatever the hell I want on my phone without worrying about space constraints.

Mobile data worked surprisingly well, with minimal tinkering. At the time, PostmarketOS wasn't able to automatically detect the APN for my carrier, but the PINE64 wiki has a list of APN settings for common carriers. Once I set it up to communicate with NXTGENPHONE, I was able to kill the Wi-Fi connection and hit icanhazip.com. I knew it worked because I was given an IPv6 address in response. First time that's happened to me.

I was also able to pull out my PinePhone and pull up a picture of Fred Durst at the Thanksgiving dinner table⁶, far away from my house, so I was able to test out mobile data "in practice" fairly early into my PinePhone usage.

While we can run Android applications on GNU/Linux, it would defeat the purpose of using this phone to run Android applications for everything. So, soon after I'd verified all was working, I put together a list of the packages that I had installed on my old phone, and figured out what the analogs were on PostmarketOS.

Excluded from this list are two banking applications which are effectively irreplaceable, as they employ some additional anti-tampering and security measures. I still keep a burner phone around for this – even though I'm able to do a lot from the website, there are a few things like digital check deposit and paying rent through Zelle that I can't do without the mobile app.

I keep the burner phone in a Faraday bag at home, but I did carry my old Android phone around on me while I was starting to use the PinePhone – always in airplane mode, occasionally connected to a Wi-Fi hotspot. I took the approach of weening myself off one and onto the other.

I still occasionally carry around the old phone because mepo is nowhere near OsmAnd~ in terms of maturity, so the PinePhone isn't very useful for land navigation. The camera's also a little better on the Honor 5X.

There are also a few odd things that aren't in the table because in Android, they're built into the system. In particular, I've been using grim to take screenshots and wlsunset to set the screen color temperature.¹¹

I'll get into the specifics of using some of these applications (like GNU Emacs) later in the article.

The modem has been the single most frustrating part about using the PinePhone. For background: the PinePhone uses a Quectel EG25-G modem, which is effectively a SOC of its own, running a little embedded Linux distribution distinct from the rest of the PinePhone. So if the firmware is dogshit (which it is, if you're using the firmware from Quectel), it can run hot or draw a stupid amount of power while the main SOC is in standby and drain the battery.

Fortunately, Biktorgj maintains a free firmware implementation for the EG25-G which is much better. Battery life on standby went from a couple of hours to a whole day when I made the switch.

Regardless of firmware, I was having an issue where the modem would disconnect from the phone every couple of minutes, which was very frustrating. This is resolved by using udev to set ATTR{power/control} to on instead of auto, at a cost in power consumption, but the usability is worth the hit in battery life.

Having a distinct modem daughter card seems to be a design feature, at least in the eyes of Purism, because it means that "those network components are fully isolated from the main board and cannot freely access the rest of the system," indicating that it's "an important privacy feature." It comes with it's costs, though.

Biktorgj's project only addresses parts of the firmware, and not the baseband implementation. You still need to install ADSP firmware blobs for that. And, humorously, Quectel doesn't seem to officially publish them, so the PINE64 community just maintains a collection of four different versions with varying levels of stability depending on the cellular carrier being used.

One issue that I have yet to solve is that, if the phone is sitting in standby for a while (say, overnight), I can't receive or make calls. But it's inconsistent. For example, at the time of writing this, I'd had my phone in standby without restarting for several nights, but I could make a call just now. It's hard to gleam what's going on from the logs, too.

Jul 30 02:02:34 theta daemon.info [2179]: <info>  [modem0/bearer1] verbose call end reason (3,1056): [cm] lrrc-connection-establishment-failure-timer-expired
Jul 30 02:02:34 theta daemon.info [2179]: <info>  [modem0] state changed (connected -> registered)
Jul 30 02:02:34 theta daemon.info [2179]: <info>  [modem0/bearer1] connection #1 finished: duration 22362s, tx: 285780 bytes, rx: 1471594 bytes
...
Jul 30 06:02:43 theta daemon.info [2179]: <info>  [modem0/bearer1] verbose call end reason (3,1034): [cm] esm-sync-up-with-nw
Jul 30 06:02:43 theta daemon.info [2179]: <info>  [modem0] state changed (connected -> registered)
Jul 30 06:02:43 theta daemon.info [2179]: <info>  [modem0/bearer1] connection #2 finished: duration 14407s, tx: 172 bytes, rx: 555 bytes

For me, this isn't a huge problem. 90% of the time I'm getting a phone call, it's a robot asking me about my car's warranty. If it's someone actually trying to get a hold of me, they're likely to leave a voicemail, which I am alerted to even if the phone's in this unusual state of being unable to receive calls.

So running custom firmware on the modem is currently the best way to have a moderately-usable modem. With the news that Quectel could potentially be locking down their hardware and preventing users from flashing their own firmware, I'm worried the usability of the PinePhone will be kneecapped in the somewhat near-future.

The sad thing is, this modem seems to be the best supported piece of hardware in ModemManager now, and I don't think we'll see this much work on other modems for a long while. This Quectel piece of shit will probably be the only usable option in e.g. PostmarketOS for the foreseeable future.

My phone will occasionally refuse to wake up from standby. That is, when the phone goes to sleep because the screen's been off for 2 minutes, it suspends. But the power button doesn't wake it, nor does the phone respond to the TTYEscape key sequence.

I configured syslogd to write to disk instead of shared memory to get some indication of what might be going on, but since doing the issue hasn't presented itself. I suspected that gnome-power-manager was failing to register ACPI wake-up events in some cases, but I don't see any messages about ACPI in my dmesg output. Seems like PSCI is what's being used, which tracks since the first version of the standard to acknowledge ARM was only released a decade ago. I don't know enough about PSCI to hypothesize about what might have been going on. What matters is that it's been a difficult problem to track down.

Rarely a problem for me since I plug my phone in at night and don't have it configured to suspend when on AC power, but if the phone is suspended, there's nothing to wake the phone up to check for alarms you've set in gnome-clocks. The effect is that your alarm isn't going to go off.

Fortunately, the modem is almost always running and is able to wake the phone, so if you're using Biktorgj's firmware, you can send the modem a text message to schedule a wake-up call. It's a nice solution to a pretty unfortunate problem.

There are some papers on how power management is done in Android-land, which makes me think that user space alarms could work in the presence of an automatic suspend framework. In fact, the RTC available on the PinePhone is sufficient to trigger a wake event, but configuring it seems to be quite user-unfriendly. I hope that we see more libraries and software development kits for Linux that take advantage of mobile hardware capabilities.

As stated above, battery life out-of-the-box is awful. It's made much better by installing Biktorgj's modem firmware, but is still somewhat underwhelming. I've seen this attributed to the phone's design consisting of four separate chips.

The PinePhone Keyboard comes with a 6000mAh internal battery to effectively extend the battery capacity of the PinePhone. I haven't purchased one yet.

What I have done is spend about $40 on a 40000mAh power bank from Anker. That was a good investment, since I can charge my PineBook and other devices as well. I just keep that and a spare USB-C cable in my bag (which I bring with me practically everywhere), and I haven't had any issues.

I'm hopeful that PINE64 eventually releases a back cover that supports a higher-capacity battery (maybe 5000mAh). My hesitancy with the keyboard is that I'm worried it would be too chunky. I wouldn't expect a slightly fatter battery to make it difficult to fit the phone in my pocket, but a phone with a keyboard attached might be a tight fit.

Non-issue as of PostmarketOS 21.12. The hotspot works fine, and I use it extensively to connect my PineBook to the internet while on the go.

Even in 21.06, it wasn't a terrible issue to have to work around. The issue was that I couldn't connect to the internet directly, but I could still connect to the PinePhone, so SSH tunneling and a SOCKS5 client were all I needed to browse the web or check my email. It was apparently a kernel issue.

This is a difficult issue to put into words, and as such I've had a hard time looking around for mention of it on the bug tracker or elsewhere.

Sometimes, when typing with Squeekboard (the on-screen keyboard that comes with Phosh), I'll press a key once and two characters will be inserted – as if the phone registered it as two taps in quick succession.

A solution I'd like to try is to patch Squeekboard and have it keep a timer for determining how much time there elapses between key press events. If the pause is too short, then we'd drop the second key press. Squeekboard seems to be mostly written in Rust, so I find that to be an enticing quality-of-life improvement project, but I think I've done enough technical work in this post already, so I'll do it another time.

Bluetooth audio remains a pain point, and an elusive one at that. It works well when attempting to troubleshoot, but seems to bug out when I actually use it. The Arch Linux Wiki has a page on troubleshooting my situation, which is that "[c]onnecting works, but there are sound glitches all the time." In my case, I have no issues connecting to my car's stereo system, for example, but 90% of the time I will have audio buffer overruns that cause the audio to pause every second or so. It is infuriating to have to listen to. I mostly notice this behavior with mpd, and I have a procedure for "fixing it."

1. nice -11 mpd
2. mpc play
3. pkill mpd
4. nice -11 mpd
5. Music starts playing without hiccups.

I'm not sure why it works, or if this indicates that the issue is in mpd rather than the Bluetooth stack. Regardless, it's behavior I would expect to "just work."

CyberSeb on the PINE64 forum has a post for configuring the Bluetooth stack to work better, and I have some recollection of the second step working well, but as of late the script I have to run those commands (included below) no longer works. It tends to fail at pactl set-port-latency-offset, either because BLUEZCARD isn't defined, or something else. The error messages aren't especially descriptive.

I was only doing the second step because, for some time, I was convinced that my phone wasn't running Pulse. I really thought it was on Pipewire, but it seems my memory failed me.

theta:~$ sudo apk add pipewire-pulse
ERROR: unable to select packages:
  pipewire-pulse-0.3.51-r1:
    breaks: postmarketos-ui-phosh-18-r3[!pipewire-pulse]
    satisfies: world[pipewire-pulse] gnome-settings-daemon-42.1-r0[pulseaudio] postmarketos-base-ui-gnome-1-r3[pulseaudio] gnome-session-42.0-r1[pulseaudio-alsa]

Even if Pulse is installed, I'm hesitant to screw with its niceness because it does not have a reputation of being resourceful. I'm wondering if these issues would go away if I did switch over to using Pipewire, but the error from apk above makes me think that it would be a hard nut to crack. I've tried setting a default fragment size in Pulse as a more reasonable workaround while I wait for Pulse to eventually die a slow and painful death. So far, it hasn't fixed the mpd problem, and I'm not especially inclined to troubleshoot further.

PostmarketOS maintains a tool for cross-compiling packages (among other things) called pmbootstrap, which I find to be quite nice. pmbootstrap init will set you up with a chroot pinned at a specific version of PostmarketOS (or edge) for a specific device and architecture, and from there you can use pmbootstrap build to cross-compile packages for installation on the PinePhone. Cross-compiling can be a bit slow (it literally took a day to compile Emacs PGTK) because, in most cases, the toolchain will be running under QEMU's user space emulator, but it's probably better than melting your phone trying to compile things on the device.

I've had a few sour experiences with cross-compiling, but the issue always came down to poor quality control in Alpine's community repository rather than the cross compiling workflow not being good. Before learning about numberstation, I was trying to use gnome-authenticator, and the version available in apk was completely unusable. I tried to build a newer version, which ended up being incompatible with the libraries installed in my version of PostmarketOS, and I tried to build a really old version (before the application was rewritten in Rust), which didn't work either. I ended up cross-compiling otpclient with little friction.

A lot of what I want to do is well-supported by existing Linux packages, but there are a couple of blind spots like Signal. In theory, I can use Pidgin and signald, but I haven't been bothered to try it.

In these cases, the solution is to write your own software.

Being able to do this without the complexity (and Java requirement) of the Android SDK is the biggest appeal of running a Linux phone to me. So much so that I've got an entire section dedicated to it later in this article.

This is the "killer feature" for me.

You might expect Emacs on mobile to be little more than a novelty, but the only application I think I use more than it is Firefox. I've now got a friction-less org-capture device in my pocket. If an idea pops into my head, or if someone tells me to do something, I just pull out the PinePhone, M-<RET> TODO and type it in. That note then makes its way to my other machines by the magic of Syncthing. Another use for mobile Emacs is that, sometimes, I'll cuddle up to my partner, and they'll fall asleep on me, but I really want to work on a blog post. If this happens, I can use TRAMP to edit the draft over SSH. In fact, I've literally edited this blog post from my bed while Oli was asleep on me, using mobile Emacs.

The other uses are honestly pretty mundane. I like being able to use dired to browse the local filesystem; I can use Malyon to play Zork & friends on the go; and if I'm really bored, I can just start hacking on Scheme or Elisp code while I'm sitting on the train.

I was anticipating wanting to pick up evil-mode, thinking it would be better for use with an on-screen keyboard, but the Squeekboard terminal layout is actually quite good for Emacs-ing. I can whip around a buffer at about a fifth my speed on my workstation, which is pretty good for only using a fifth of my God-given fingers. Icons (I don't disable tool-bar-mode in my mobile configuration) make for a slightly nicer touch input experience, too.

It was a little difficult to get things running. Emacs is in the PostmarketOS repos.. except the package sucks because it's the old X11 Emacs, and Phosh is Wayland, so it has to run through Xwayland and fractional scaling makes it a blurry mess. To resolve that, I ripped a ton of code out of the APKBUILD and pointed it at a tarball for Emacs master (which has had the PGTK branch merged).

# Maintainer: Natanael Copa <[REDACTED]>
# Contributor: Timo Teräs <[REDACTED]>
pkgname=emacs
pkgver=29.0
pkgrel=7
pkgdesc="The extensible, customizable, self-documenting real-time display editor"
arch="all"
depends="emacs-nox"
url="https://www.gnu.org/software/emacs/emacs.html"
license="GPL-3.0-or-later"
makedepends="
    autoconf
    automake
    gawk
    gmp-dev
    gnutls-dev
    harfbuzz-dev
    jansson-dev
    linux-headers
    ncurses-dev
    ncurses-libs
    texinfo
    "
subpackages="$pkgname-doc $pkgname-nox"
source="emacs-$pkgver.tar.xz"

case $CARCH in
    riscv64|s390x)
        # limited by librsvg (rust)
        _docdir="nox"
        ;;
    *)
        makedepends="
            $makedepends
            alsa-lib-dev
            fontconfig-dev
            giflib-dev
            glib-dev
            gtk+3.0-dev
            libgccjit-dev
            libjpeg-turbo-dev
            libpng-dev
            librsvg-dev
            libxaw-dev
            libxml2-dev
            libxpm-dev
            pango-dev
            tiff-dev
            "
        subpackages="
            $subpackages
            $pkgname-gtk3
            "
        _docdir="gtk3"
        ;;
esac

prepare() {
    default_prepare
    ./autogen.sh
}

_build_variant() {
    cd "$builddir/$1"
    shift
    CFLAGS=-fno-pie \
    LDFLAGS=-no-pie \
    ./configure \
        --build=$CBUILD \
        --host=$CHOST \
        --prefix=/usr \
        --sysconfdir=/etc \
        --libexecdir=/usr/lib \
        --localstatedir=/var \
        --with-gameuser=:games \
        --with-gpm \
        --with-harfbuzz \
        --with-json \
        "${@}"

    make $_extra
}

_build_gtk3() {
     _build_variant gtk3 \
        --with-pgtk \
        --with-xft \
        --with-jpeg=yes \
        --with-tiff=no \
        --with-gif=ifavailable \
        --with-xpm=ifavailable
}

        # --with-x-toolkit=gtk3 \

_build_nox() {
    _build_variant nox \
        --without-sound \
        --without-x \
        --without-file-notification
}

build() {
    mkdir -p nox
    mv ./* nox || true

    case "$CARCH" in
    riscv64|s390x)
        # limited by librsvg (rust)
        _build_nox
        ;;
    *)
        cp -a nox gtk3
        _build_nox
        _build_gtk3
        ;;
    esac
}

package() {
    mkdir -p "$pkgdir"
}

doc() {
    depends=""
    mkdir -p "$subpkgdir"
    cd "$builddir"/"$_docdir"
    make DESTDIR="$subpkgdir" install
    # remove conflict with ctags package
    mv "$subpkgdir"/usr/share/man/man1/ctags.1.gz "$subpkgdir"/usr/share/man/man1/ctags.emacs.1.gz
    # only keep info and man directories, all other is in the specific package
    rm -rf "${subpkgdir:?}"/usr/bin \
        "$subpkgdir"/usr/lib \
        "$subpkgdir"/usr/share/appdata \
        "$subpkgdir"/usr/share/applications \
        "$subpkgdir"/usr/share/emacs \
        "$subpkgdir"/usr/share/icons \
        "${subpkgdir:?}"/var \
        "$subpkgdir"/usr/lib/systemd
}

_subpackage() {
    cd "$builddir/$1"
    make DESTDIR="$subpkgdir" install

    # remove conflict with ctags package
    mv "$subpkgdir"/usr/bin/ctags "$subpkgdir"/usr/bin/ctags.emacs
    rm -rf "$subpkgdir"/usr/share/info \
        "$subpkgdir"/usr/share/man

    # fix user/root permissions on usr/share files
    find "$subpkgdir"/usr/share/emacs/ -exec chown root:root {} \;
    find "$subpkgdir"/usr/lib -perm -g+s,g+x ! -type d -exec chmod g-s {} \;
    # fix perms on /var/games
    chmod 775 "$subpkgdir"/var/games
    chmod 775 "$subpkgdir"/var/games/emacs
    chmod 664 "$subpkgdir"/var/games/emacs/*
    chown -R root:games "$subpkgdir"/var/games

    # remove useless systemd user file
    rm -rf "$subpkgdir"/usr/lib/systemd
}

nox() {
    pkgdesc="$pkgdesc - without X11"
    depends="
        !emacs-gtk3
        !emacs-gtk3-nativecomp
        !emacs-x11
        !emacs-x11-nativecomp
        "
    _subpackage nox
}

gtk3() {
    pkgdesc="$pkgdesc - with GTK3"
    depends="
        !emacs-gtk3-nativecomp
        !emacs-nox
        !emacs-x11
        !emacs-x11-nativecomp
        desktop-file-utils
        hicolor-icon-theme
        "
    _subpackage gtk3
}

sha512sums="
20c96e4485b9acbc5c9049bca9b4d9675cd5f4062cd04a9abde4fb7088c7dc55e3bf473acce8f447825c0c1fd9a5def23623d0219bc0353b31892a0cc23f7884  emacs-29.0.tar.xz
"

There is no Emacs 29.0 (yet, at the time of writing this), that's just so apk knows that this is newer than what's in the repositories.

And if you find the code snippet incomprehensible, don't worry, because I've got a gentler introduction to Alpine packaging later in this article.

I was a NewPipe user when I was using Android. I'd frequently find it unusable, and the times it was usable, I'd still get annoying toasts warning me of errors, just about every time I watched a video. The F-Droid package didn't keep up with YouTube cat-and-mouse game as quickly as youtube-dl did. I always thought about how nice it would be to use mpv and yt-dlp just like I do on desktop, and that's now a reality.

I get the video URLs from RSS and invoke mpv from the terminal. I find it convenient. The only issue I had is that the screen blanks automatically even when a video is playing, but this is easily remedied by prefixing mpv with gnome-session-inhibit --inhibit idle.

LineageOS included the old Cyanogenmod Music app Eleven, and that's what I used when I was on Android. I didn't see a purpose in using any other music player since they all seem to use the same Android APIs and, hence, all suck as much as Eleven does. Among other things, it cuts out frequently (presumably the process getting killed due to memory pressure), and it can't even load a damned jpeg.

So I was quite happy to be able to use mpd to listen to music on the PinePhone. My entire library's managed with Syncthing.

Another "killer feature" is just being able to automate things with bash and cron the way I would on desktop. One pain point I remember particularly when I was using Android was manually adjusting the screen color temperature in settings. Now I can just use cron to run wlsunset at a particular hour.

I suppose that's the only example that's worth mentioning. I haven't leveraged it as much as I could have (but I expect to in the future.)

A selling point of the PinePhone is convergence, enabling you to plug your phone into a monitor and keyboard (over USB-C), and use it as if it were a desktop computer. I haven't taken advantage of this yet, but I can SSH into my phone. That's already far better than what I can do on Android, and it's enough for me to be happy – just being able to pull/push files over rsync, run shell commands over SSH using an actual keyboard…

The only thing I wish I could do is send SMS over SSH and get notifications from my phone on my workstation. SMS messages can (theoretically) be sent using mmcli, and I'm not sure about notifications. Perhaps I've made a programming project for myself.

Nearly all of the above points boil down to the PinePhone enabling me to run Linux desktop applications on mobile. Consistency is nice. Who would have known!

If you're at least mildly familiar with Android, you know that the Java ecosystem is nearly unavoidable if you're doing application development for the platform.¹² The NDK enables application developers to write code in other languages (provided they "compile down" to machine code) but it isn't practical to write an entire application this way, as NDK code is limited in the ways it can interact with Android's APIs. Furthermore, the Android SDK is a pain in the ass to use if you're not using Google's IDE. It's doable, and I have done it in the past, but I got frustrated before I could set up an emulator for improving the feedback loop. I was literally pushing to my device via adb on every build if I wanted to experiment with something. That said, it is easy to understand why it is this way. Google (and Apple) want to have uniformity across their platforms' third-party applications, so they impose strong opinions (you must use our UI framework, you must use our Java APIs). Comparatively, the applications that run on my PinePhone are literally the same applications that run on my workstation. I can use any language or libraries I want, provided they support AArch64. I can develop and test on my workstation, and then push it to the PinePhone with high confidence that it will work as intended.

I've been writing my applications in Rust with gtk-rs and libhandy. There's been a (somewhat recent) distinction between "application programming languages" and "systems programming languages." Rust falls into the latter. The distinction is somewhat arbitrary as you can write an application in assembly, but the reason it's come up in recent years is because people want a way to describe languages that (1) aren't interpreted or VM languages and (2) don't have a convenient garbage collector. These sorts of language seem to work quite well for a resource-constrained environment like the PinePhone, even if it is somewhat more difficult than using something like Python or Ruby.

Using Rust is perhaps a bit overkill. I'm sure Vala would have been a good choice, too, since it compiles to C, but I went with Rust because I'm more comfortable with it and it has a ecosystem of libraries for the sorts of things I want to do.

So that's all I have to say about the language decision, but there's the decision of UI toolkit too. I went with GTK3 and libhandy: the classic GNOME UI toolkit and Purism's supporting library for adaptive, mobile-friendly layouts and widgets. But that isn't the only option available. Still in GNOME land, there is GTK4 and libadwaita, which I'll probably be using in the near future. I'm just a little slow to start using cool new things. There are many more choices on the Plasma Mobile side of the house: Kirigami, MauiKit (built on top of Kirigami), plain QtQuick, or Sailfish OS's Silica. While GTK and QT are the leading frameworks, I was keeping a close eye on pods, a PinePhone-oriented application using Rust's iced, which is neither GTK nor QT. Unfortunately, it looks to have since stagnated. But mepo, a maps application, is a surprisingly pleasant mobile experience and is written just in SDL.

As an aside, I'd like to experiment with some immediate-mode UI frameworks on the PinePhone. GTK is relatively performant, but I'm curious about whether something like egui would be "snappier". Hell, maybe it would be interesting to try and write my own UI framework.

What one might expect to follow from "it's easy to develop for the PinePhone because you're writing applications as if you were writing them for your workstation" is that it should be relatively easy to port existing applications as well. And this is indeed the case. The compile times can be painful, but I was successful in cross-compiling diamondburned's gtkcord4 – which has no existing Alpine package to my knowledge – to run on the PinePhone.

# Contributor: Jakob L. Kreuze <[REDACTED]>
# Maintainer: Jakob L. Kreuze <[REDACTED]>
pkgname=gtkcord4
pkgver=0.0.2
pkgrel=0
pkgdesc="GTK4 Discord client in Go"
url="https://github.com/diamondburned/gtkcord4"
arch="all"
license="GPL-3.0"
makedepends="gtk4.0-dev gobject-introspection-dev libcanberra-dev go"
source="$pkgname-$pkgver.tar.gz::https://github.com/diamondburned/gtkcord4/archive/refs/tags/v${pkgver}.tar.gz"

build() {
    go build
}

package() {
    install -D -m755 $pkgname "$pkgdir"/usr/bin/$pkgname
}

sha512sums="
1c0465f4c2d54794551811c0a536b610a51d3f795c403af3cf10954a46770b42d1aadef4709818f935aa54e2b413052546bdde5214f44e89d5ad2e2d7cbdf514  gtkcord4-0.0.2.tar.gz
"

The above is all it took. I initialized pmbootstrap, made a directory named gtkcord4 under cache_git/pmaports/main, ran pmbootstrap build --arch,=aarch64 gktcord4, and a couple hours later and I had a gtkcord4-0.0.2-r0.apk sitting under packages/v21.12/aarch64.

I'm not sure diamondburned ever anticipated that gtkcord4 would be running on a mobile device, but thanks to their choice to use GTK4, I didn't have to make any changes to the code and it still runs great on my device.

Some applications might need to be modified to work well on a touchscreen. I haven't had to do that yet, and even if I did, I would expect it to be a difficult topic to cover in this (already quite long) article. The part that I will elaborate on is how we got to that magic code block above. The gtkcord4 example is a little boring because of how little it takes to invoke the Go build system,¹⁵ so let's port OpenXCOM instead. I'll start from scratch and document my process as I go.

Speaking of process, this is basically what I follow:

1. Determine if the software in question is already packaged in another source-based distribution (basically Gentoo or the Arch AUR).
   1. If so, translate the recipe to APKBUILD. In the case of Gentoo, figure out what set of USE flags "make sense" as a default.
   2. Use pkgs.alpinelinux.org to map each dependency in the original package spec to an Alpine dependency.
2. If it isn't…
   1. Find a skeleton APKBUILD (like the "hello world" example in the "Building and Installing the Application on PostmarketOS" section).
   2. Fill it in with the instructions to compile from upstream. I find you need to specify build and package as the bare minimum if you explicitly disable check.
   3. Guess-and-check for dependencies. Sometimes upstream will be good about enumerating them, sometimes not so much.

I know that openxcom is packaged in Gentoo, so we'll start there.

# Copyright 1999-2021 Gentoo Authors
# Distributed under the terms of the GNU General Public License v2

EAPI=7

inherit cmake xdg-utils

DESCRIPTION="Open-source reimplementation of the popular UFO: Enemy Unknown"
HOMEPAGE="https://openxcom.org/"

if [[ ${PV} == *9999 ]]; then
    inherit git-r3
    EGIT_REPO_URI="https://github.com/SupSuper/OpenXcom.git"
else
    COMMIT="ea9ac466221f8b4f8974d2db1c42dc4ad6126564"
    SRC_URI="https://github.com/SupSuper/OpenXcom/archive/${COMMIT}.tar.gz -> ${P}.tar.gz"
    KEYWORDS="~amd64 ~arm64 ~x86"
    S="${WORKDIR}/OpenXcom-${COMMIT}"
fi

LICENSE="GPL-3+ CC-BY-SA-4.0"
SLOT="0"
IUSE="doc"

RDEPEND="
    >=dev-cpp/yaml-cpp-0.5.1
    media-libs/libsdl[opengl,video]
    media-libs/sdl-gfx
    media-libs/sdl-image[png]
    media-libs/sdl-mixer[flac,mikmod,vorbis]"
DEPEND="${RDEPEND}"
BDEPEND="doc? ( app-doc/doxygen )"

DOCS=( README.md )

src_compile() {
    cmake_src_compile
    use doc && cmake_build doxygen
}

src_install() {
    use doc && local HTML_DOCS=( "${BUILD_DIR}"/docs/html/. )
    cmake_src_install
}

pkg_postinst() {
    xdg_icon_cache_update

    elog "In order to play you need copy GEODATA, GEOGRAPH, MAPS, ROUTES, SOUND,"
    elog "TERRAIN, UFOGRAPH, UFOINTRO, UNITS folders from original X-COM game to"
    elog "/usr/share/${PN}/UFO"
    elog
    elog "If you want to play the TFTD mod, you need to copy ANIMS, FLOP_INT,"
    elog "GEODATA, GEOGRAPH, MAPS, ROUTES, SOUND, TERRAIN, UFOGRAPH, UNITS folders"
    elog "from the original Terror from the Deep game to"
    elog "/usr/share/${PN}/TFTD"
    elog
    elog "If you need or want text in some language other than english, download:"
    elog "https://openxcom.org/translations/latest.zip and uncompress it in"
    elog "/usr/share/${PN}/common/Language"
}

pkg_postrm() {
    xdg_icon_cache_update
}

Although I probably should, I'm not going to bother with postinst or postrm right now. I'm also not going to build the docs. What we can tell immediately is that this is a CMake project (so we should find an APKBUILD for something else that uses CMake – I used gzdoom) and the dependencies are the following:

• yaml-cpp
• sdl
• sdl_gfx
• sdl_image
• sdl_mixer

All of these are packaged in Alpine except sdl_mixer, so we'll need to port that ourselves. I was able to take the APKBUILD for sdl_mixer and use that as a skeleton. The packages are packaged very similarly, so I was able to fill in the blanks with some of the info from the Gentoo package.

# Contributor: Jakob L. Kreuze <[REDACTED]>
# Maintainer: Jakob L. Kreuze <[REDACTED]>
pkgname=sdl_gfx
pkgver=2.0.26
pkgrel=3
pkgdesc="Graphics drawing primitives library for SDL"
url="https://www.ferzkopp.net/wordpress/2016/01/02/sdl_gfx-sdl2_gfx/"
arch="all"
license="zlib"
makedepends="sdl-dev"
subpackages="$pkgname-dev"
source="http://www.ferzkopp.net/Software/SDL_gfx-2.0/SDL_gfx-$pkgver.tar.gz"
builddir="$srcdir"/SDL_gfx-$pkgver

prepare() {
    default_prepare
    update_config_sub
    update_config_guess
}

build() {
    ./configure \
        --build=$CBUILD \
        --host=$CHOST \
        --prefix=/usr \
        --sysconfdir=/etc \
        --mandir=/usr/share/man \
        --infodir=/usr/share/info
    make
}

package() {
    make DESTDIR="$pkgdir" install
}

sha512sums="e571caa0d7575683efd4cf8f0a41ab10f4acf913f9ece216ac823af11da22c8734fc2c0ea049009a3e1a53715e49622f5bfcfdbdafb95e5151990d0a4eb69c01  SDL_gfx-2.0.26.tar.gz"

It took a little bit of trial and error to arrive at the APKBUILD above. I first ran into an issue with autotools not recognizing the target platform.

>>> sdl_gfx: Building pmos/sdl_gfx 2.0.26-r3 (using abuild 3.9.0-r0) started Tue, 23 Aug 2022 01:28:27 +0000
>>> sdl_gfx: Checking sanity of /home/pmos/build/APKBUILD...
>>> sdl_gfx: Cleaning up srcdir
>>> sdl_gfx: Cleaning up pkgdir
>>> sdl_gfx: Fetching http://www.ferzkopp.net/Software/SDL_gfx-2.0/SDL_gfx-2.0.26.tar.gz
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100   251  100   251    0     0   1764      0 --:--:-- --:--:-- --:--:--  2127
100 1729k  100 1729k    0     0  2103k      0 --:--:-- --:--:-- --:--:-- 2103k
>>> sdl_gfx: Fetching http://www.ferzkopp.net/Software/SDL_gfx-2.0/SDL_gfx-2.0.26.tar.gz
>>> sdl_gfx: Checking sha512sums...
SDL_gfx-2.0.26.tar.gz: OK
>>> sdl_gfx: Unpacking /var/cache/distfiles/SDL_gfx-2.0.26.tar.gz...
checking build system type... Invalid configuration `aarch64-alpine-linux-musl': machine `aarch64-alpine-linux' not recognized
configure: error: /bin/sh ./config.sub aarch64-alpine-linux-musl failed
>>> ERROR: sdl_gfx: build failed
(011680) [21:28:30] ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
(011680) [21:28:30] NOTE: The failed command's output is above the ^^^ line in the log file: /home/jakob/Containers/pmbootstrap/pmbootstrap/log.txt
(011680) [21:28:30] ERROR: Command failed (exit code 1): (buildroot_aarch64) % cd /home/pmos/build; busybox su pmos -c CARCH=aarch64 SUDO_APK='abuild-apk --no-progress' PATH=/native/usr/lib/crossdirect/aarch64:/usr/lib/ccache/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin HOME=/home/pmos abuild -D postmarketOS -d
(011680) [21:28:30] See also: <https://postmarketos.org/troubleshooting>
(011680) [21:28:30] Traceback (most recent call last):
  File "/home/jakob/Containers/pmbootstrap/.venv/lib/python3.10/site-packages/pmb/__init__.py", line 49, in main
    getattr(frontend, args.action)(args)
  File "/home/jakob/Containers/pmbootstrap/.venv/lib/python3.10/site-packages/pmb/helpers/frontend.py", line 114, in build
    if not pmb.build.package(args, package, arch_package, force,
  File "/home/jakob/Containers/pmbootstrap/.venv/lib/python3.10/site-packages/pmb/build/_package.py", line 520, in package
    (output, cmd, env) = run_abuild(args, apkbuild, arch, strict, force, cross,
  File "/home/jakob/Containers/pmbootstrap/.venv/lib/python3.10/site-packages/pmb/build/_package.py", line 447, in run_abuild
    pmb.chroot.user(args, cmd, suffix, "/home/pmos/build", env=env)
  File "/home/jakob/Containers/pmbootstrap/.venv/lib/python3.10/site-packages/pmb/chroot/user.py", line 26, in user
    return pmb.chroot.root(args, cmd, suffix, working_dir, output,
  File "/home/jakob/Containers/pmbootstrap/.venv/lib/python3.10/site-packages/pmb/chroot/root.py", line 76, in root
    return pmb.helpers.run_core.core(args, msg, cmd_sudo, None, output,
  File "/home/jakob/Containers/pmbootstrap/.venv/lib/python3.10/site-packages/pmb/helpers/run_core.py", line 347, in core
    check_return_code(args, code, log_message)
  File "/home/jakob/Containers/pmbootstrap/.venv/lib/python3.10/site-packages/pmb/helpers/run_core.py", line 219, in check_return_code
    raise RuntimeError(f"Command failed (exit code {str(code)}): " +
RuntimeError: Command failed (exit code 1): (buildroot_aarch64) % cd /home/pmos/build; busybox su pmos -c CARCH=aarch64 SUDO_APK='abuild-apk --no-progress' PATH=/native/usr/lib/crossdirect/aarch64:/usr/lib/ccache/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin HOME=/home/pmos abuild -D postmarketOS -d

Fortunately, it wasn't too difficult to find the issue online. Someone had tried (unsuccessfully) to add sdl_ttf to aports and ran into the same issue. The recommendation in the MR comments was to include the prepare block above.

When that was sorted, I had a sdl_gfx package that I could use as a dependency for openxcom.

# Contributor: Jakob L. Kreuze <[REDACTED]>
# Maintainer: Jakob L. Kreuze <[REDACTED]>
_commit="ea9ac466221f8b4f8974d2db1c42dc4ad6126564"
pkgname=openxcom
pkgver=1.0.0
pkgrel=1
pkgdesc="Open-source reimplementation of the popular UFO: Enemy Unknown"
url="https://openxcom.org/"
arch="all"
license="GPL-3.0-or-later"
makedepends="cmake ninja yaml-cpp-dev sdl-dev sdl_gfx-dev sdl_image-dev sdl_mixer-dev glu-dev libexecinfo-dev"
depends="libexecinfo"
source="openxcom-$pkgver.tar.gz::https://github.com/OpenXcom/OpenXcom/archive/$_commit.tar.gz
0001-Link-execinfo-unconditionally.patch"
builddir="$srcdir"/OpenXcom-$_commit

build() {
    if [ "$CBUILD" != "$CHOST" ]; then
        CMAKE_CROSSOPTS="-DCMAKE_SYSTEM_NAME=Linux -DCMAKE_HOST_SYSTEM_NAME=Linux"
    fi
    cmake -B build -G Ninja \
        -DCMAKE_BUILD_TYPE=Release \
        -DCMAKE_INSTALL_PREFIX=/usr \
        -DBUILD_SHARED_LIBS=True \
        $CMAKE_CROSSOPTS
    cmake --build build
}

package() {
    DESTDIR="$pkgdir" cmake --install build
}

sha512sums="57ff9a9cbbbf48b8c4f792458edf0590d7d0df9a5805eab13a4c984713311e98587afca00778e82bd66fb2f330b354ca80703b87922a92f9ae48e5bdecf68442  openxcom-1.0.0.tar.gz
de4cc52530200992fef0e723acd59fef1b214f5b12baabec4dcca03820fbbc38c30033c0707f918fccc29e7d0d67ddef0c2a7be56d21b2bba7221899c759c282  0001-Link-execinfo-unconditionally.patch"

where 0001-Link-execinfo-unconditionally.patch is the following:

From 2fe3e39c90086c7e3953d83ce75b0686ee4f5813 Mon Sep 17 00:00:00 2001
From: "Jakob L. Kreuze" <[REDACTED]>
Date: Tue, 23 Aug 2022 20:11:16 -0400
Subject: [PATCH] Link execinfo unconditionally

---
 src/CMakeLists.txt | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt
index d484380ba..b7d3020bd 100644
--- a/src/CMakeLists.txt
+++ b/src/CMakeLists.txt
@@ -485,9 +485,7 @@ if ( WIN32 )
 endif ()

 # backtrace(3) requires libexecinfo on some *BSD systems
-if (${CMAKE_SYSTEM_NAME} MATCHES FreeBSD OR ${CMAKE_SYSTEM_NAME} MATCHES NetBSD OR ${CMAKE_SYSTEM_NAME} MATCHES OpenBSD)
-  set ( system_libs -lexecinfo )
-endif ()
+set ( system_libs -lexecinfo )

 target_link_libraries ( openxcom ${system_libs} ${SDLIMAGE_LIBRARY} ${SDLMIXER_LIBRARY} ${SDLGFX_LIBRARY} ${SDL_LIBRARY} ${OPENGL_LIBRARIES} debug ${YAMLCPP_LIBRARY_DEBUG} optimized ${YAMLCPP_LIBRARY} )

-- 
2.37.2

The first error I got was about a missing mmintrin.h. I opened up the source code and found that was under an IFDEF for MMX support, so I did a ./configure --help to figure out how to disable that. After that, I was getting a message about a missing glu.h.

[63/313] Building CXX object src/CMakeFiles/openxcom.dir/Mod/RuleVideo.cpp.o
ninja: job failed: /native/usr/lib/crossdirect/aarch64/g++ -DDATADIR=\"/usr/share/openxcom/\" -DGIT_BUILD=1 -I/usr/include/SDL -I/usr/include/yaml-cpp -I/home/pmos/build/src/OpenXcom-ea9ac466221f8b4f8974d2db1c42dc4ad6126564/build -Os -fomit-frame-pointer -O3 -DNDEBUG -std=gnu++11 -MD -MT src/CMakeFiles/openxcom.dir/Mod/RuleVideo.cpp.o -MF src/CMakeFiles/openxcom.dir/Mod/RuleVideo.cpp.o.d -o src/CMakeFiles/openxcom.dir/Mod/RuleVideo.cpp.o -c /home/pmos/build/src/OpenXcom-ea9ac466221f8b4f8974d2db1c42dc4ad6126564/src/Mod/RuleVideo.cpp
In file included from /home/pmos/build/src/OpenXcom-ea9ac466221f8b4f8974d2db1c42dc4ad6126564/src/Mod/../Engine/OpenGL.h:15,
                 from /home/pmos/build/src/OpenXcom-ea9ac466221f8b4f8974d2db1c42dc4ad6126564/src/Mod/../Engine/Screen.h:22,
                 from /home/pmos/build/src/OpenXcom-ea9ac466221f8b4f8974d2db1c42dc4ad6126564/src/Mod/RuleVideo.cpp:21:
/usr/include/SDL/SDL_opengl.h:47:10: fatal error: GL/glu.h: No such file or directory
   47 | #include <GL/glu.h> /* Header File For The GLU Library */
      |          ^~~~~~~~~~
compilation terminated.
ninja: subcommand failed
>>> ERROR: openxcom: build failed

I went ahead and added the glu-dev dependency, after which point I was getting some warnings about redefinitions. So I have a feeling this might have been another thing that was behind an IFDEF, but that's a problem for later.

[218/313] Building CXX object src/CMakeFiles/openxcom.dir/Engine/AdlibMusic.cpp.o
ninja: job failed: /native/usr/lib/crossdirect/aarch64/g++ -DDATADIR=\"/usr/share/openxcom/\" -DGIT_BUILD=1 -I/usr/include/SDL -I/usr/include/yaml-cpp -I/home/pmos/build/src/OpenXcom-ea9ac466221f8b4f8974d2db1c42dc4ad6126564/build -Os -fomit-frame-pointer -O3 -DNDEBUG -std=gnu++11 -MD -MT src/CMakeFiles/openxcom.dir/Engine/CrossPlatform.cpp.o -MF src/CMakeFiles/openxcom.dir/Engine/CrossPlatform.cpp.o.d -o src/CMakeFiles/openxcom.dir/Engine/CrossPlatform.cpp.o -c /home/pmos/build/src/OpenXcom-ea9ac466221f8b4f8974d2db1c42dc4ad6126564/src/Engine/CrossPlatform.cpp
/home/pmos/build/src/OpenXcom-ea9ac466221f8b4f8974d2db1c42dc4ad6126564/src/Engine/CrossPlatform.cpp:68:10: fatal error: execinfo.h: No such file or directory
   68 | #include <execinfo.h>
      |          ^~~~~~~~~~~~
compilation terminated.
ninja: subcommand failed
>>> ERROR: openxcom: build failed

The last errors I got were related to execinfo. This is, to my knowledge, a glibc thing. Fortunately, Alpine being a popular base image in Docker land means the workarounds are easy to find on the 'net. The missing header file was one, thing, but then I was getting some linker errors about a missing symbol for backtrace. Searching came up with an issue in PyTorch which gave me some insight, and then I found a pull request upstream related to it. My patch above just makes the fix in that pull request unconditional (in master, it's only applied on BSD); we get all the backtrace symbols from execinfo, but we need to make sure it's actually linked into the binary.

Then.. shit. It built correctly, but my pmbootstrap setup was a version behind the PostmarketOS on my phone (v21.12 vs v22.06), so I was getting some dependency resolution errors. I re-initialized pmbootstrap and then learned that sdl-dev is no longer supported, so I had to backport it from edge/testing. It was at least smooth sailing after that.

So porting software to the PinePhone is relatively easy.

You don't even have to go through half of the mess that I did if you don't care about cross-compiling or having things tracked by the package manager. You could probably just install the gcc toolchain and do a make && sudo make install on your phone; Alpine/PostmarketOS have glibc compatibility. Or, hell, use a Flatpak/AppImage/Snap if you want to.

However you do it, the end result is the same. You get to use the same Linux applications on your phone that you would on your desktop, and I think that's great.