Florian’s Blog

I like treating my phone like the general purpose computer that it is, so I’m a big fan of Termux, which lets you have a full blown Linux environment on your Android device.

Since my work involves writing and editing specs, one tool I use a lot is Bikeshed, a spec-generating tool that takes in lightly-decorated Markdown and spits out a full spec, with cross-spec auto-linking, automatic generation of indexes/ToC/etc, and many other features.

Put the two together, and you can build specifications right on your phone, which I find a lot of fun.

Here’s how to get it to work.

Installing Dependencies

# get yourself a compiler
pkg install clang
# dependencies of later stages
pkg install libxml2 libxslt libjpeg-turbo
# bikeshed is a python program
pkg install python

Installing Bikeshed

pip install bikeshed

If that works, you’re done. Go bikeshed away to your heart’s delight.

Troubleshooting

Unfortunately, it might not work. lxml is a dependency which will get pulled in by pip when trying to install Bikeshed. However, it is very demanding to compile, and many android devices will run out of memory and crash when trying. This is a known issue, and Termux normally lets you work around that by providing a precompiled version. Unfortunately, that doesn’t help us because Termux’s pkg tool only keeps track of a single version of each package, and the one it has for python-lxml isn’t the one Bikeshed wants.

Instead, do this:

CFLAGS="-O0" pip install lxml==5.1.0

Compiling with optimizations turned off significantly reduces how much memory it takes to successfully compile lxml, making it work on many more devices. I presume that makes it slower too, but I haven’t found that to make an obvious difference when using Bikeshed.

Once that goes through, have another shot at installing Bikeshed:

pip install bikeshed

Now you should be good.

Accessing your built specs

One small annoyance is that your home folder in termux is not readable by other applications on the phone/tablet, so you need to put your specs under ~/storage/shared/<whatever-you-like> if you want to be able to reach them via file://sdcard/<whatever-you-like> in the browser. Not a blocker, but annoying. Conveniently, Bikeshed can build your specification and serve it from a local web server:

bikeshed serve

You can then point your browser to http://localhost:8000 and view the specification you just built. Bikeshed will also rebuild and serve an updated copy everytime the source changes.