Fixing my Old OS Assignment with Machine Code Hacks

Stephen Sherratt — Sun, 24 Aug 2025 00:00:00 +0000

Back in 2012 I took an Operating Systems course, the main assessment of which was a 12 week pair assignment implementing a user-level OS personality for the seL4 microkernel</a>. I recently got the urge to boot up our little OS. I saved the contents of my university computer system home directory before I graduated so I still have a copy of the code, and fortunately I didn’t make clean</code> the last time I worked on it so the bootable (at least in theory!) disk image is still in the project directory.

Also fortunately my project partner somehow forgot to return the hardware loaned to them by the university and over the following years it ended up in one of my (ahem) several boxes of junk that I’ll definitely do something with someday.

And for this Storage Link for USB 2.0 Disk Drives</a>, a.k.a NSLU2, affectionately referred to as the Slug, today was that day.

Powering it On</a></h2>
Plugging it into power and switching it on illuminated the power indicator LED.
There’s no screen or input devices, so all interaction will be via an
aftermarket USB serial port. In the image below the USB serial port is the
left-most port which was clearly made by a power tool.</p>
</p>
Plugging it into my computer with a USB cable causes the serial device to show up in the
output of dmesg</code>:</p>
[138157.363235] usb 1-5: new full-speed USB device number 18 using xhci_hcd
</span>[138157.511474] usb 1-5: New USB device found, idVendor=0403, idProduct=6001, bcdDevice= 6.00
</span>[138157.511481] usb 1-5: New USB device strings: Mfr=1, Product=2, SerialNumber=3
</span>[138157.511483] usb 1-5: Product: USB <-> UNSW-AOS
</span>[138157.511485] usb 1-5: Manufacturer: FTDI
</span>[138157.511487] usb 1-5: SerialNumber: 12345678
</span>[138157.516506] ftdi_sio 1-5:1.0: FTDI USB Serial Device converter detected
</span>[138157.516539] usb 1-5: Detected FT232R
</span>[138157.521742] usb 1-5: FTDI USB Serial Device converter now attached to ttyUSB0
</span></code></pre>
Running picocom</code> to open a terminal on /dev/ttyUSB0</code>:</p>
$ picocom /dev/ttyUSB0
</span>picocom v2024-07
</span>
</span>port is        : /dev/ttyUSB0
</span>flowcontrol    : none
</span>baudrate is    : 9600
</span>parity is      : none
</span>databits are   : 8
</span>stopbits are   : 1
</span>txdelay is     : 0 ns
</span>escape is      : C-a
</span>local echo is  : no
</span>noinit is      : no
</span>noreset is     : no
</span>hangup is      : no
</span>nolock is      : no
</span>send_cmd is    : /nix/store/cmpvp7nx52dmbjaqkiscgkdzqzaikmaz-lrzsz-0.12.20/bin/sz -vv
</span>receive_cmd is : /nix/store/cmpvp7nx52dmbjaqkiscgkdzqzaikmaz-lrzsz-0.12.20/bin/rz -vv -E
</span>imap is        :
</span>omap is        :
</span>emap is        : crcrlf,delbs,
</span>logfile is     : none
</span>initstring     : none
</span>exit_after is  : not set
</span>exit is        : no
</span>minimal cmds is: no
</span>
</span>Type [C-a] [C-h] to see available commands
</span>Terminal ready
</span></code></pre>
…but there was no output.</p>
I couldn’t remember the process we used to load our OS project onto the slug. I
was hoping that it would already be loaded on there, and powering it on would
print something to the terminal, but no luck there.</p>
On a whim I searched my entire old uni home directory for “ttyUSB0” since
I assumed the project would be transferred over the serial port and thus I would
have some script that referenced the name of the serial device. This assumption
would later turn out to be false but I did find something helpful in my search:</p>
$ grep -rni 'ttyUSB0'
</span>nslu2-util/nslu2.c:67:  char defport[] = "/dev/ttyUSB0";
</span></code></pre>
The nslu2-util</code> program is a command-line utility for starting, stopping,
and resetting the slug. Students in the OS course were given a copy of the tool.
It’s a tiny C project with a Makefile</code> and running make</code> built an nslu2</code>
executable:</p>
$ ./nslu2 -h
</span>Usage: nslu2 <-p port> up|down|reset
</span></code></pre>
So I ran ./nslu2 reset</code> and this caused something to appear on my picocom</code>
serial terminal:</p>
Terminal ready
</span>>R+;#23/#766'2"*""3+":
</span></code></pre>
Getting garbage text over a serial port usually means the baudrate is wrong.
The default baudrate was 9600. After trying 115200 instead and resetting the slug
I could read the output:</p>
$ picocom -b 115200 /dev/ttyUSB0
</span>...
</span>Terminal ready
</span>++
</span>Ethernet eth0: MAC address 00:14:bf:68:99:03
</span>IP: 192.168.168.2/255.255.255.0, Gateway: 192.168.168.1
</span>Default server: 0.0.0.0, DNS server IP: 0.0.0.0
</span>
</span>RedBoot(tm) bootstrap and debug environment [ROMRAM]
</span>Red Hat certified release, version 1.92 - built 22:30:50, Jul 22 2008
</span>
</span>Platform: IXDP425 Development Platform (XScale)
</span>Copyright (C) 2000, 2001, 2002, Red Hat, Inc.
</span>
</span>RAM: 0x00000000-0x02000000, 0x000724b0-0x01ff3000 available
</span>FLASH: 0x50000000 - 0x50800000, 64 blocks of 0x00020000 bytes each.
</span>== Executing boot script in 2.000 seconds - enter ^C to abort
</span>RedBoot> load -r -v -b 0x00100000 -h 192.168.168.1 bootimg.bin;go
</span>Unable to reach host 192.168.168.1 (192.168.168.1)
</span>
</span></code></pre>
RedBoot</a></h2>
The printout indicates that the slug is running a default boot script:</p>
load -r -v -b 0x00100000 -h 192.168.168.1 bootimg.bin;go
</span></code></pre>
I don’t remember interacting with RedBoot as a student, this command must have
once caused our OS project to start running. That script would have been set up by the
people running the OS course; it would be different or absent on a brand new
slug.</p>
The line above is also interesting:</p>
== Executing boot script in 2.000 seconds - enter ^C to abort
</span></code></pre>
Resetting the slug and hitting ctrl+c within 2 seconds of seeing that starts an
interactive shell. Luckily this shell accepts a help</code> command. I’ll paste the
entire output here in case it’s helpful to someone in the future:</p>
RedBoot> help
</span>go to assign mode
</span>   assign
</span>Set/Query the system console baud rate
</span>   baudrate [-b <rate>]
</span>sercomm boot flow
</span>   boot
</span>Manage machine caches
</span>   cache [ON | OFF]
</span>Display/switch console channel
</span>   channel [-1|<channel number>]
</span>Compute a 32bit checksum [POSIX algorithm] for a range of memory
</span>   cksum -b <location> -l <length>
</span>Display (hex dump) a range of memory
</span>   dump -b <location> [-l <length>] [-s] [-1|2|4]
</span>Execute an image - with MMU off
</span>   exec [-w timeout] [-b <load addr> [-l <length>]]
</span>        [-r <ramdisk addr> [-s <ramdisk length>]]
</span>        [-c "kernel command line"] [<entry_point>]
</span>Manage FLASH images
</span>   fis {cmds}
</span>Execute code at a location
</span>   go [-w <timeout>] [entry]
</span>Help about help?
</span>   help [<topic>]
</span>Set/change IP addresses
</span>   ip_address [-l <local_ip_address>] [-h <server_address>]
</span>Load a file
</span>   load [-r] [-v] [-d] [-h <host>] [-m <varies>] [-c <channel_number>]
</span>        [-b <base_address>] <file_name>
</span>Compare two blocks of memory
</span>   mcmp -s <location> -d <location> -l <length> [-1|-2|-4]
</span>Fill a block of memory with a pattern
</span>   mfill -b <location> -l <length> -p <pattern> [-1|-2|-4]
</span>move kernel&ramdisk to ram
</span>   move
</span>Network connectivity test
</span>   ping [-v] [-n <count>] [-l <length>] [-t <timeout>] [-r <rate>]
</span>        [-i <IP_addr>] -h <IP_addr>
</span>Reset the system
</span>   reset
</span>Set/Read MAC address for NPE ethernet ports
</span>   set_npe_mac [-p <portnum>] [xx:xx:xx:xx:xx:xx]
</span>go to upgrade mode
</span>   upgrade
</span>Display RedBoot version information
</span>   version
</span>Display (hex dump) a range of memory
</span>   x -b <location> [-l <length>] [-s] [-1|2|4]
</span></code></pre>
This tells us that the default boot script is running the load</code> command to download the OS
image over the network and then the go</code> command to boot it. This unlocked a memory of
running some software (I forget exactly what) on my laptop to serve the OS image
over the network and plugging the slug directly into my laptop with an Ethernet
cable. Based on the load -r -v -b 0x00100000 -h 192.168.168.1 bootimg.bin</code>
command, in this setup my laptop would have had the IP address 192.168.168.1</code>,
and the bootable OS image was in a file named bootimg.bin</code>.</p>
Searching my old home directory for a bootimg.bin</code> and fortunately I still have one:</p>
$  find . -name bootimg.bin
</span>./aos/aoshg/images/bootimg.bin
</span></code></pre>
But the 192.168.168.1</code> address isn’t going to work. My home network uses
addresses in the 192.168.1.*</code> range, so unless I set up a computer with a spare
Ethernet port as a router and plug the slug directly into it, I’m going to have
to change the network configuration of the slug. Fortunately there’s a command
for that:</p>
Set/change IP addresses
</span>   ip_address [-l <local_ip_address>] [-h <server_address>]
</span></code></pre>
Running ip_address</code> with no arguments prints the current configuration:</p>
RedBoot> ip_addr
</span>IP: 192.168.168.2/255.255.255.0, Gateway: 192.168.168.1
</span>Default server: 0.0.0.0, DNS server IP: 0.0.0.0
</span></code></pre>
And I can change the address with:</p>
RedBoot> ip_addr -l 192.168.1.22
</span>IP: 192.168.1.22/255.255.255.0, Gateway: 192.168.168.1
</span>Default server: 0.0.0.0, DNS server IP: 0.0.0.0
</span></code></pre>
I chose 192.168.1.22</code> arbitrarily among the unused IP addresses on my home
network. After this change I could ping</code> that address from my computer, and
also use RedBoot’s own ping</code> command to ping my computer (whose address is
192.168.1.7</code>):</p>
RedBoot> ping -h 192.168.1.7
</span>Network PING - from 192.168.1.22 to 192.168.1.7
</span>PING - received 10 of 10 expected
</span></code></pre>
So the slug is on my home network now and it can see my development machine
where bootimg.bin</code> is located. Now I just need a way to send bootimg.bin</code> over
the network to the slug. The documentation printed by help</code> about the load</code>
command doesn’t go into much detail about what network protocol RedBoot will use
to transfer a file:</p>
Load a file
</span>   load [-r] [-v] [-d] [-h <host>] [-m <varies>] [-c <channel_number>]
</span>        [-b <base_address>] <file_name>
</span></code></pre>
I found some better documentation
online</a> which explained
that the -m</code> option accepts TFTP</code> or HTTP</code>. There’s no way to
specify the port number. For some reason this caused me to prefer
TFTP</a>, possibly
because I’m so used to HTTP servers running on ports besides the default (80)
when running websites locally, but not so for TFTP. I actually implemented a
simple send-only TFTP server</a> a few years
ago when I got frustrated that all the TFTP servers I could find wouldn’t let
me just serve files out of the current directory, so that’s what I’ll be using
here.</p>
To install it:</p>
$ cargo install tftp-ro
</span></code></pre>
And then I ran it from the directory containing bootimg.bin</code> like:</p>
$ sudo tftp-ro -v -d .
</span>[2025-08-24T07:46:46Z INFO  tftp_ro] Listening on 0.0.0.0:69
</span>[2025-08-24T07:46:46Z INFO  tftp_ro] Serving files out of .
</span></code></pre>
Then I tried downloading the file to the slug:</p>
RedBoot> load -r -v -b 0x00100000 -h 192.168.1.7 -m TFTP bootimg.bin
</span>Can't load 'bootimg.bin': operation timed out
</span></code></pre>
I’m not sure if this is a bug or performance issue with my TFTP server but my
quick fix was to compress the image. RedBoot’s load</code> command takes a flag -d</code>
which decompresses the image assuming it’s compressed with gzip.</p>
So I compressed the image:</p>
$ gzip -k bootimg.bin
</span></code></pre>
…and tried load</code>-ing it again:</p>
RedBoot> load -r -v -d -b 0x00100000 -h 192.168.1.7 -m TFTP bootimg.bin.gz
</span>\
</span>Raw file loaded 0x00100000-0x0017bfff, assumed entry at 0x00100000
</span></code></pre>
Success! RedBoot remembers that we loaded that image starting at address
0x00100000</code>, so we can now run the command go</code> to start executing at that address:</p>
RedBoot> go
</span>ELF-loader image started:   paddr=[0x00100000..0x0017c000]
</span>ELF-loading kernel image:   paddr=[0x01000000..0x01039154] vaddr=[0xf0000000..0xf0039154] v_entry=0xf0000000
</span>ELF-loading userland image: paddr=[0x00407000..0x005d0000] vaddr=[0x00007000..0x001d0000] v_entry=0x000080b4
</span>Enabling MMU and paging
</span>Jumping to kernel-image entry point
</span>Bootstrapping kernel
</span>
</span>SOS Starting...
</span>Info Page:  0x001d1000
</span>IPC Buffer: 0x001d0000
</span>Node ID: 0 (of 1)
</span>IOPT levels: 0
</span>Init cnode size bits: 12
</span>
</span>Cap details:
</span>Type              Start      End
</span>Empty             0x00000266 0x00001000
</span>Shared frames     0x00000000 0x00000000
</span>User image frames 0x0000000c 0x000001d5
</span>User image PTs    0x000001d5 0x000001d7
</span>Untypeds          0x000001d7 0x000001f7
</span>
</span>Untyped details:
</span>Untyped Slot       Paddr      Bits
</span>  0     0x000001d7 0x01000000 12
</span>  1     0x000001d8 0x01001000 12
</span>  2     0x000001d9 0x01002000 12
</span>  3     0x000001da 0x01003000 12
</span>  4     0x000001db 0x01004000 12
</span>  5     0x000001dc 0x01005000 12
</span>  6     0x000001dd 0x01006000 12
</span>  7     0x000001de 0x01007000 12
</span>  8     0x000001df 0x01008000 12
</span>  9     0x000001e0 0x01009000 12
</span> 10     0x000001e1 0x0100a000 12
</span> 11     0x000001e2 0x0100b000 12
</span> 12     0x000001e3 0x0100c000 12
</span> 13     0x000001e4 0x0100d000 12
</span> 14     0x000001e5 0x0100e000 12
</span> 15     0x000001e6 0x0100f000 12
</span> 16     0x000001e7 0x01ff0000 13
</span> 17     0x000001e8 0x01064000 14
</span> 18     0x000001e9 0x01068000 15
</span> 19     0x000001ea 0x01070000 16
</span> 20     0x000001eb 0x01fe0000 16
</span> 21     0x000001ec 0x01fc0000 17
</span> 22     0x000001ed 0x01f80000 18
</span> 23     0x000001ee 0x01080000 19
</span> 24     0x000001ef 0x01f00000 19
</span> 25     0x000001f0 0x01100000 20
</span> 26     0x000001f1 0x01e00000 20
</span> 27     0x000001f2 0x01200000 21
</span> 28     0x000001f3 0x01c00000 21
</span> 29     0x000001f4 0x01400000 22
</span> 30     0x000001f5 0x01800000 22
</span> 31     0x000001f6 0x0103a000 13
</span>
</span>Num device regions: 13
</span>Device Addr     Size Start      End
</span> 0 0xc8001000 12 0x000001f7 0x000001f8
</span> 1 0xc8002000 12 0x000001f8 0x000001f9
</span> 2 0xc8004000 12 0x000001f9 0x000001fa
</span> 3 0xc8005000 12 0x000001fa 0x000001fb
</span> 4 0xc8006000 12 0x000001fb 0x000001fc
</span> 5 0xc8007000 12 0x000001fc 0x000001fd
</span> 6 0xc8008000 12 0x000001fd 0x000001fe
</span> 7 0xc8009000 12 0x000001fe 0x000001ff
</span> 8 0xc800a000 12 0x000001ff 0x00000200
</span> 9 0xc800b000 12 0x00000200 0x00000201
</span>10 0x50000000 12 0x00000201 0x00000261
</span>11 0x60000000 12 0x00000261 0x00000265
</span>12 0xc4000000 12 0x00000265 0x00000266
</span>-----------------------------------------
</span>
</span>Parsing Dite data:
</span>Found section              sos at index 0 (0x00007018)
</span>        flags 0
</span>        entry 80b4
</span>        base 0x00008000
</span>        size 1838928
</span>        magic (nil)
</span>        pbase 0x00008000
</span>Found section         tty_test at index 1 (0x00007040)
</span>        flags 0
</span>        entry 0
</span>        base 0x001c9000
</span>        size 27863
</span>        magic (nil)
</span>        pbase 0x001c9000
</span>DMA memory is at 0x10000000 to 0x10400000
</span>Initialising the frame table!
</span>Made a frame, physical address 181d000, cap 1646
</span>Made a frame, physical address 181e000, cap 1647
</span>Made a frame, physical address 181f000, cap 1648
</span>...
</span>Made a frame, physical address 18e2000, cap 1843
</span>Made a frame, physical address 18e3000, cap 1844
</span>Made a frame, physical address 18e4000, cap 1845
</span>Initialising the pager!
</span>Leaking a frame.
</span>Mapping our leaked frame to the MASTER_PAGEDIR address (leaking a hardware page table, unavoidable)
</span>Leaking a frame.
</span>Mapping our leaked frame to the MASTER_PAGETABLE address (probably not but possibly also leaking a hardware page table)
</span>Creating the original 4 capdirs
</span>We are mapping in a kernel page at vaddr e3ffa000 to pd 3
</span>We are mapping in a kernel page at vaddr e4000000 to pd 3
</span>Trying to map in a hardware page table at vaddr e4000000 for pd 3
</span>We are mapping in a kernel page at vaddr e3ffb000 to pd 3
</span>We are mapping in a kernel page at vaddr e3ffc000 to pd 3
</span>We are mapping in a kernel page at vaddr e3ffd000 to pd 3
</span>Adding to capdir (cap dir 0 is 0xe3ffa000)
</span>Pager initialised!  Moving morecore across to pager-based allocation!
</span>
</span>Starting network_init
</span>
</span>        Network Mask: 225.225.225.0
</span>  Gateway IP Address: 192.168.168.1
</span>    Local IP Address: 192.168.168.2
</span>
</span>Device memory at 0xb8005000 to 0xb8006000
</span>Device memory at 0x40000000 to 0x40060000
</span>Device memory at 0x50000000 to 0x50004000
</span>Device memory at 0xb8006000 to 0xb8007000
</span>Device memory at 0xb8007000 to 0xb8008000
</span>Device memory at 0xb8008000 to 0xb8009000
</span>Undelivered IRQ: 2
</span>Device memory at 0xb4000000 to 0xb4001000
</span>Device memory at 0xb8009000 to 0xb800a000
</span>Device memory at 0xb800a000 to 0xb800b000
</span>waiting for PHY 0 to become ready...
</span>
</span>Network failed to respond to ARP query
</span>
</span>seL4 root server abortedDebug halt syscall from user thread 0xf0063e00
</span>halting...
</span></code></pre>
This is debug output from our OS project which is pretty exciting. It’s running!
It’s failing an assertion after unsuccessfully attempting to
connect to the network. It has the same IP addresses hard-coded
into it as the initial boot script, so can’t connect to my home network, and the code
is written in such a way that doesn’t let it proceed to boot without network access.</p>
We’ll get to fixing this, but first let’s talk about the goal of this endeavour.</p>
Call Me Maybe</a></h2>
I built an Easter egg</a> into
the OS. The slug has a buzzer, and there’s a particular bit in a hardware register that
can be toggled at a given frequency to buzz at that frequency. I wrote this
code in mid 2012 and so the obvious song to play according to 20 year old me
was Call Me Maybe by Carly Rae Jepsen</a>. I remember implementing a device driver
with a unix-style “everything’s a file” interface, where opening the file
/dev/maybe</code> would lock up the OS while it buzzed the hottest song of 2012.</p>
Unfortunately it appears the snapshot of the project I stored on the university
server was not its final form. I did most of the work for this project on a
netbook (remember netbooks?!) which has sadly been lost to the ages. The
implementation of /dev/maybe</code> is not in this version, but it still has the
logic to play the song and print the lyrics to the terminal:</p>
void </span>call_me_maybe</span>(</span>int </span>beat_len) {
</span>
</span>    </span>printf</span>(</span>"Hey I just met you</span>\n</span>"</span>);
</span>    udelay(beat_len);
</span>    tone(NOTE_G4, beat_len);
</span>    tone(NOTE_B3, beat_len</span>/</span>4</span>);
</span>    tone(NOTE_D4, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_G4, beat_len</span>/</span>4</span>);
</span>    tone(NOTE_G4, beat_len</span>/</span>4</span>);
</span>    tone(NOTE_D4, </span>3</span>*</span>beat_len</span>/</span>4</span>);
</span>
</span>    </span>printf</span>(</span>"And this is crazy</span>\n</span>"</span>);
</span>    udelay(beat_len);
</span>    udelay(beat_len</span>/</span>2</span>);
</span>    tone(NOTE_B3, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_B3, beat_len</span>/</span>4</span>);
</span>    tone(NOTE_D4, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_B4, beat_len</span>/</span>4</span>);
</span>    tone(NOTE_B4, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_G4, beat_len</span>/</span>2</span>);
</span>
</span>    </span>printf</span>(</span>"But here's my number</span>\n</span>"</span>);
</span>    udelay(beat_len);
</span>    udelay(beat_len</span>/</span>2</span>);
</span>    tone(NOTE_G4, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_B4, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_C5, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_B4, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_G4, beat_len</span>/</span>2</span>);
</span>
</span>    </span>printf</span>(</span>"So call me maybe</span>\n</span>"</span>);
</span>    udelay(beat_len);
</span>    udelay(beat_len</span>/</span>2</span>);
</span>    tone(NOTE_G4, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_B4, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_A4, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_A4, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_G4, beat_len</span>/</span>2</span>);
</span>}
</span></code></pre>
Rather than playing the song by reading a file, this version of the project
would play it immediately after booting if a certain compile-time flag was set:</p>
    if (I_JUST_MET_YOU) {
</span>        call_me_maybe(500000);
</span>    }
</span></code></pre>
However the flag was not set:</p>
#define </span>I_JUST_MET_YOU </span>0
</span></code></pre>
The C compiler was probably smart enough to elide the entire call to
call_me_maybe</code> since that condition is never true. Fortunately the presence of
the song’s lyrics in the bootable image tells us that the call_me_maybe</code> function did
make it into the image despite never being called:</p>
$ strings bootimg.bin | grep Hey
</span>Hey I just met you
</span></code></pre>
So once the network issue is fixed, my goal is going to be getting Call Me Maybe
to play on the buzzer of my slug.</p>
Why don’t you just call the call_me_maybe</code> function?</em></p>
Well…</p>
Fixing the Network</a></h2>
I can’t build the project. I have the source code, and luckily I have a mostly
working bootable image. I also have the object files for each source file which
were built with debug symbols. But I don’t have the software necessary to
change the source code and rebuild the image to incorporate those changes.</p>
And I refuse to do the kind of archaeology that would be required to get a
32-bit ARM compiler toolchain and seL4 build scripts circa 2012 running on a modern OS.
Getting all the tools working was hard enough back in 2012.</p>
In order to get past the failing assertion we need the OS to choose an IP
address in a valid range for my home network. Currently it tries to use
192.168.168.2:</p>
        Network Mask: 225.225.225.0
</span>  Gateway IP Address: 192.168.168.1
</span>    Local IP Address: 192.168.168.2
</span></code></pre>
The network information is a compile-time constant string which means these
strings are literally present in the binary:</p>
$ strings bootimg.bin | grep '192\.168'
</span>192.168.168.1
</span>192.168.168.2
</span></code></pre>
To change them to suitable addresses, one can simply modify the binary
directly</em>! I don’t own a magnetized needle</a> so instead
I’ll use the tool hexedit</code>.</p>
The hexedit</code> tool lets you print and modify the raw bytes in any type of file.
When you run hexedit bootimg.bin</code> it prints the hexadecimal and ASCII
representations of the binary data in the file:</p>
000000B0   E5 9F 03 24  E5 9F 13 24  E5 9F 23 24  EB 00 04 97  ...$...$..#$....
</span>000000C0   E5 9F 03 20  EB 00 00 F6  E3 50 00 00  0A 00 00 02  ... .....P......
</span>000000D0   E5 9F 03 14  EB 00 04 9F  EB 00 00 D1  E5 9F 43 04  ..............C.
</span>000000E0   E1 A0 00 04  E3 A0 10 01  E2 8D 20 40  E2 8D 30 38  .......... @..08
</span>000000F0   EB 00 01 F3  E1 A0 00 04  E3 A0 10 00  E2 8D 20 20  ..............
</span>00000100   E2 8D 30 18  EB 00 01 EE  E1 A0 00 04  EB 00 01 DB  ..0.............
</span>00000110   E1 A0 90 01  E5 9D 30 1C  E5 8D 30 00  E5 8D 10 04  ......0...0.....
</span>00000120   E5 9F 02 C8  E5 9D 10 44  E5 9D 20 3C  E5 9D 30 24  .......D.. <..0$
</span>00000130   EB 00 04 7A  E5 9F 62 A4  E5 9F A2 A4  E5 9D 00 44  ...z..b........D
</span>00000140   E5 9D 10 3C  E2 41 10 01  E1 A0 20 06  E1 A0 30 0A  ...<.A.... ...0.
</span>00000150   EB FF FF CC  E3 50 00 00  0A 00 00 02  E5 9F 02 90  .....P..........
</span>00000160   EB 00 04 7C  EB 00 00 AE  E5 9F 02 78  E3 A0 10 01  ...|.......x....
</span>00000170   EB 00 02 35  E3 50 00 00  1A 00 00 02  E5 9F 02 74  ...5.P.........t
</span>00000180   EB 00 04 74  EB 00 00 A6  E5 9F 02 6C  EB 00 00 C4  ...t.......l....
</span>00000190   E3 50 00 00  0A 00 00 02  E5 9F 02 60  EB 00 04 6D  .P.........`...m
</span>000001A0   EB 00 00 9F  E5 9F 42 50  E1 A0 00 04  E3 A0 10 01  ......BP........
</span>-**  bootimg.bin       --0x0/0x7C000--0%---------------------------------------
</span></code></pre>
To find the IP addresses, we’ll be changing, search for a sequence of hexadecimal digits representing
the ASCII encoding of part of the address.</p>
Here’s an ASCII table so you can play along at home:</p>
Dec Hex    Dec Hex    Dec Hex  Dec Hex  Dec Hex  Dec Hex   Dec Hex   Dec Hex
</span>  0 00 NUL  16 10 DLE  32 20    48 30 0  64 40 @  80 50 P   96 60 `  112 70 p
</span>  1 01 SOH  17 11 DC1  33 21 !  49 31 1  65 41 A  81 51 Q   97 61 a  113 71 q
</span>  2 02 STX  18 12 DC2  34 22 "  50 32 2  66 42 B  82 52 R   98 62 b  114 72 r
</span>  3 03 ETX  19 13 DC3  35 23 #  51 33 3  67 43 C  83 53 S   99 63 c  115 73 s
</span>  4 04 EOT  20 14 DC4  36 24 $  52 34 4  68 44 D  84 54 T  100 64 d  116 74 t
</span>  5 05 ENQ  21 15 NAK  37 25 %  53 35 5  69 45 E  85 55 U  101 65 e  117 75 u
</span>  6 06 ACK  22 16 SYN  38 26 &  54 36 6  70 46 F  86 56 V  102 66 f  118 76 v
</span>  7 07 BEL  23 17 ETB  39 27 '  55 37 7  71 47 G  87 57 W  103 67 g  119 77 w
</span>  8 08 BS   24 18 CAN  40 28 (  56 38 8  72 48 H  88 58 X  104 68 h  120 78 x
</span>  9 09 HT   25 19 EM   41 29 )  57 39 9  73 49 I  89 59 Y  105 69 i  121 79 y
</span> 10 0A LF   26 1A SUB  42 2A *  58 3A :  74 4A J  90 5A Z  106 6A j  122 7A z
</span> 11 0B VT   27 1B ESC  43 2B +  59 3B ;  75 4B K  91 5B [  107 6B k  123 7B {
</span> 12 0C FF   28 1C FS   44 2C ,  60 3C <  76 4C L  92 5C \  108 6C l  124 7C |
</span> 13 0D CR   29 1D GS   45 2D -  61 3D =  77 4D M  93 5D ]  109 6D m  125 7D }
</span> 14 0E SO   30 1E RS   46 2E .  62 3E >  78 4E N  94 5E ^  110 6E n  126 7E ~
</span> 15 0F SI   31 1F US   47 2F /  63 3F ?  79 4F O  95 5F _  111 6F o  127 7F DEL
</span></code></pre>
For example to find 192</code>, search for 0x313932</code>:</p>
0005F5E0   30 00 00 00  4E 65 74 77  6F 72 6B 20  4D 61 73 6B  0...Network Mask
</span>0005F5F0   00 00 00 00  31 39 32 2E  31 36 38 2E  31 36 38 2E</span>  ....192.168.168.</span>
</span>0005F600   31</span> 00 00 00  47 61 74 65  77 61 79 20  49 50 20 41  1</span>...Gateway IP A
</span>0005F610   64 64 72 65  73 73 00 00  00 00 00 00  31 39 32 2E</span>  ddress......192.</span>
</span>0005F620   31 36 38 2E  31 36 38 2E  32</span> 00 00 00  4C 6F 63 61  168.168.2</span>...Loca
</span>0005F630   6C 20 49 50  20 41 64 64  72 65 73 73  00 00 00 00  l IP Address....
</span>0005F640   00 00 00 00  6E 65 74 69  66 20 21 3D  20 4E 55 4C  ....netif != NUL
</span>---  bootimg.bin       --0x5F5E4/0x7C000--77%----------------------------------
</span></code></pre>
The ASCII representation of the data confirms that we’re in the right place.</p>
The game is that all the changes to the binary file must be made by updating values in-place.
It’s not possible to insert new bytes between existing bytes, nor to remove bytes.
This is because parts of the code will refer to other parts of the code and
static data (like these IP addresses) by their relative offset from one
another. If we insert or remove bytes then that will change the relative
position of all following bytes, causing references to no longer point to the
correct place.</p>
I changed the local and gateway addresses to 192.168.1.25</code> and 192.168.1.1</code>
respectively, again choosing an arbitrary unused valid address for the local
address and my router’s address as the gateway address. The new addresses are
made up of fewer characters than the original addresses so they’ll fit in the
allocated space. I overwrote the remaining characters of the original strings
with 0s as these as null-terminated C strings (so technically I just needed to
put a single 0 byte immediately after the end of each string).</p>
0005F5E0   30 00 00 00  4E 65 74 77  6F 72 6B 20  4D 61 73 6B  0...Network Mask
</span>0005F5F0   00 00 00 00  31 39 32 2E  31 36 38 2E  31 2E 31</span> 00  ....192.168.1.1</span>.
</span>0005F600   00 00 00 00  47 61 74 65  77 61 79 20  49 50 20 41  ....Gateway IP A
</span>0005F610   64 64 72 65  73 73 00 00  00 00 00 00  31 39 32 2E</span>  ddress......192.</span>
</span>0005F620   31 36 38 2E  31 2E 32 35</span>  00 00 00 00  4C 6F 63 61  168.1.25</span>....Loca
</span>0005F630   6C 20 49 50  20 41 64 64  72 65 73 73  00 00 00 00  l IP Address....
</span>0005F640   00 00 00 00  6E 65 74 69  66 20 21 3D  20 4E 55 4C  ....netif != NUL
</span>-**  bootimg.bin       --0x5F629/0x7C000--77%----------------------------------
</span></code></pre>
After re-gzip</code>-ing the image and resetting the slug, and rerunning all the
RedBoot commands as before, the OS makes it past the network initialization
successfully:</p>
Starting network_init
</span>
</span>        Network Mask: 225.225.225.0
</span>  Gateway IP Address: 192.168.1.1
</span>    Local IP Address: 192.168.1.25
</span>
</span>Device memory at 0xb8005000 to 0xb8006000
</span>Device memory at 0x40000000 to 0x40060000
</span>Device memory at 0x50000000 to 0x50004000
</span>Device memory at 0xb8006000 to 0xb8007000
</span>Device memory at 0xb8007000 to 0xb8008000
</span>Device memory at 0xb8008000 to 0xb8009000
</span>Undelivered IRQ: 2
</span>Device memory at 0xb4000000 to 0xb4001000
</span>Device memory at 0xb8009000 to 0xb800a000
</span>Device memory at 0xb800a000 to 0xb800b000
</span>waiting for PHY 0 to become ready....
</span>
</span>Mounting NFS
</span>Error receiving time using UDP time protocol
</span>Failed to initialise NFS
</span>
</span>Setting up capabilities for timer...
</span>
</span>Starting timer...
</span>Undelivered IRQ: 5
</span>[timer] starting timer!
</span>[timer] base address: c8005000
</span>[timer] frame count: 1
</span>[timer] frame size: 4096
</span>[timer] paging success
</span>Getting timestamp...
</span>[gpio] starting
</span>[gpio] found region 0x001d13a8
</span>[gpio] paging success
</span>
</span>Starting "tty_test"...
</span>Loading first process.  Trying to set up a page table!
</span>init'd some startup stuff! - only_process_page_dir is at 0x000b9cb0, only_procss_vroot (sel4_pd) is 1985
</span> * Loading segment 00008000-->0000a3c0
</span>We are mapping in a kernel page at vaddr 8000 to pd 1985
</span>Trying to map in a hardware page table at vaddr 0 for pd 1985
</span>We are mapping in a kernel page at vaddr d0008000 to pd 3
</span>Trying to map in a hardware page table at vaddr d0000000 for pd 3
</span>We are mapping in a kernel page at vaddr e4001000 to pd 3
</span>We are mapping in a kernel page at vaddr 9000 to pd 1985
</span>We are mapping in a kernel page at vaddr d0009000 to pd 3
</span>We are mapping in a kernel page at vaddr a000 to pd 1985
</span>We are mapping in a kernel page at vaddr d000a000 to pd 3
</span> * Loading segment 000123c0-->00013490
</span>We are mapping in a kernel page at vaddr 12000 to pd 1985
</span>We are mapping in a kernel page at vaddr d0012000 to pd 3
</span>We are mapping in a kernel page at vaddr 13000 to pd 1985
</span>We are mapping in a kernel page at vaddr d0013000 to pd 3
</span>Mapping in a hardware page (vaddr 8ffff000, pd 1985)
</span>We are mapping in a kernel page at vaddr 8ffff000 to pd 1985
</span>Trying to map in a hardware page table at vaddr 8ff00000 for pd 1985
</span>Paged in the stack frame.
</span>
</span>SOS entering syscall loop
</span>vm fault at 0x8ffdffd0, pc = 0x000083a0, Data fault
</span>Mapping in a hardware page (vaddr 8ffdffd0, pd 1985)
</span>We are mapping in a kernel page at vaddr 8ffdf000 to pd 1985
</span>vm fault at 0x8ffe0fe8, pc = 0x000083ac, Data fault
</span>Mapping in a hardware page (vaddr 8ffe0fe8, pd 1985)
</span>We are mapping in a kernel page at vaddr 8ffe0000 to pd 1985
</span>vm fault at 0x8ffe1fe8, pc = 0x000083ac, Data fault
</span>Mapping in a hardware page (vaddr 8ffe1fe8, pd 1985)
</span>...
</span>We are mapping in a kernel page at vaddr 8fffc000 to pd 1985
</span>vm fault at 0x8fffdfe8, pc = 0x000083ac, Data fault
</span>Mapping in a hardware page (vaddr 8fffdfe8, pd 1985)
</span>We are mapping in a kernel page at vaddr 8fffd000 to pd 1985
</span>vm fault at 0x8fffefe8, pc = 0x000083ac, Data fault
</span>Mapping in a hardware page (vaddr 8fffefe8, pd 1985)
</span>We are mapping in a kernel page at vaddr 8fffe000 to pd 1985
</span>brk syscall, tty_brk = 32498
</span>vm fault at 0x0003249c, pc = 0x000096a4, Data fault
</span>PANIC /home/steve/src/aos/aoshg/apps/sos/src/main.c-handle_page_fault:161 segmentation fault
</span>
</span>Debug halt syscall from user thread 0xf0063e00
</span>halting...
</span></code></pre>
It still crashes eventually but that’s ok. Remember this is a snapshot of the project when
it was half finished. What matters is that it prints the line:</p>
SOS entering syscall loop
</span></code></pre>
Looking at the main</code> function:</p>
    </span>...
</span>    gpio_init(_boot_info);
</span>    buzzer_init();
</span>    </span>if</span>(I_JUST_MET_YOU) {
</span>        call_me_maybe(</span>500000</span>);
</span>    }
</span>
</span>    </span>/* Start the user application */
</span>    start_first_process(TTY_NAME, _sos_ipc_ep_cap);
</span>
</span>    </span>/* Initialise the serial connection for tty_test */
</span>    console_init();
</span>
</span>    </span>/* Wait on synchronous endpoint for IPC */
</span>    dprintf(</span>0</span>, </span>"</span>\n</span>SOS entering syscall loop</span>\n</span>"</span>);
</span>    </span>...
</span></code></pre>
The printout happens after the buzzer has been initialized. This means that
all the necessary hardware initialization has taken place to play the song.
So now we just need to call the call_me_maybe</code> function.</p>
Just calling the call_me_maybe</code> function</a></h2>
To call a function we need to know its address. Specifically its virtual</em>
address. This is determined at runtime by how memory is mapped by the page
table. The logic for setting up the page table up exists somewhere in the project, but trying
to determine which virtual address maps to a particular offset into the bootable
image without the ability to instrument the code or any debugging tooling sounds
unpleasant.</p>
No matter what approach I eventually take, I want to know where in the
binary image call_me_maybe</code> is located. To do this we’ll benefit from some
slightly more sophisticated tools. It will be helpful to be able to use the
debug symbols in object files to learn which sequences of instructions in the
binary correspond to which functions in the source code. Short of setting up an
ARM toolchain, I found that the objdump</code> implementation that comes with LLVM
(specifically the llvm</code> derivation from nixpkgs) can disassemble the object
files in the project well enough, despite them having been compiled for a
foreign architecture (I’m using the x86_64 llvm package and these files were
compiled for 32-bit ARM).</p>
Since call_me_maybe</code> is defined in buzzer.c</code>, I ran llvm-objdump -d build/arm/nslu2/sos/src/buzzer.o</code>. The relevant part of the output is:</p>
00000054 <buzzer_init>:
</span>      54: e3 a0 23 3a   blo     #9339788 <$d+0x8e815c>
</span>      58: e5 9f 30 04   ldrteq  r9, [r0], #-4069
</span>      5c: e5 83 20 00   eoreq   r8, r0, r5, ror #7
</span>      60: e1 2f ff 1e   cdpne   p15, #15, c2, c15, c1, #7
</span>
</span>00000064 <$d>:
</span>      64:       00 00 00 00     .word   0x00000000
</span>
</span>00000068 <tone>:
</span>      68: e9 2d 40 f8   <unknown>
</span>      6c: e1 a0 40 01   smlaltteq       r10, r0, r1, r0
</span>      70: e1 a0 10 80   andshi  r10, r0, r1, ror #1
</span>      74: e3 a0 09 3d   stclo   p0, c10, [r9, #-908]
</span>      78: e2 80 0d 09   stmdbeq sp, {r1, r5, r6, r7, pc}
</span>      7c: eb ff ff fe   cdp2    p15, #15, c15, c15, c11, #7
</span>      80: e1 a0 60 00   rsbeq   r10, r0, r1, ror #1
</span>      84: e1 a0 00 04   streq   r10, [r0], #-225
</span>      88: e1 a0 10 86   ldrhi   r10, [r0], -r1, ror #1
</span>      8c: eb ff ff fe   cdp2    p15, #15, c15, c15, c11, #7
</span>      90: e2 50 70 00   rsbseq  r5, r0, r2, ror #1
</span>      94: da 00 00 10   ldrdne  r0, r1, [r0], -r10
</span>      98: e3 a0 40 00   subeq   r10, r0, r3, ror #1
</span>      9c: e5 9f 50 3c   mrrclo  p15, #14, r9, r0, c5
</span>      a0: e5 95 30 00   eorseq  r9, r0, r5, ror #11
</span>      a4: e5 93 20 00   eoreq   r9, r0, r5, ror #7
</span>      a8: e3 82 20 10   eorne   r8, r0, r3, ror #5
</span>      ac: e5 83 20 00   eoreq   r8, r0, r5, ror #7
</span>      b0: e1 a0 00 06   streq   r10, [r0], -r1, ror #1
</span>      b4: eb ff ff d1   mvnsle  pc, r11, ror #31
</span>      b8: e5 95 30 00   eorseq  r9, r0, r5, ror #11
</span>      bc: e5 93 20 00   eoreq   r9, r0, r5, ror #7
</span>      c0: e3 c2 20 10   eorne   r12, r0, r3, ror #5
</span>      c4: e5 83 20 00   eoreq   r8, r0, r5, ror #7
</span>      c8: e1 a0 00 06   streq   r10, [r0], -r1, ror #1
</span>      cc: eb ff ff cb   blgt    #-84 <tone+0x18>
</span>      d0: e2 84 40 01   smlaltteq       r8, r0, r2, r4
</span>      d4: e1 57 00 04   streq   r5, [r0], #-2017
</span>      d8: ca ff ff f0   <unknown>
</span>      dc: e8 bd 80 f8   <unknown>
</span>
</span>000000e0 <$d>:
</span>      e0:       00 00 00 00     .word   0x00000000
</span>
</span>000000e4 <call_me_maybe>:
</span>      e4: e9 2d 40 f8   <unknown>
</span>      e8: e1 a0 60 00   rsbeq   r10, r0, r1, ror #1
</span>      ec: e5 9f 01 98   stmdals r1, {r0, r2, r5, r6, r7, r8, r9, r10, r11, r12, pc}
</span>      f0: eb ff ff fe   cdp2    p15, #15, c15, c15, c11, #7
</span>      f4: e1 a0 00 06   streq   r10, [r0], -r1, ror #1
</span>      f8: eb ff ff c0   rscsgt  pc, pc, r11, ror #31
</span>      fc: e3 a0 0f 62   andvs   r10, pc, #227
</span>     100: e1 a0 10 06   ldreq   r10, [r0], -r1, ror #1
</span>     104: eb ff ff fe   cdp2    p15, #15, c15, c15, c11, #7
</span>     108: e2 86 70 03   cmneq   r0, #236978176
</span></code></pre>
This shows function names (buzzer_init</code>, tone</code>, call_me_maybe</code>), the offset
and encoding of each instruction, and the more human readable assembly
code corresponding to that instruction. The human readable instructions produced
by this tool look highly suspect to me and I quickly learnt to ignore them and just
focus on the machine code (e.g. the first instruction of buzzer_init</code> is e3 a0 23 3a</code>).</p>
I ended up relying heavily on an online ARM
(dis)assembler</a>
for decoding and eventually encoding instructions.</p>
As a sanity check, I disassembled the buzzer_init</code> function since it’s short.
The concatenation of the machine code of its 4 instructions (copied from the
output of llvm-objdump</code> above) is:</p>
e3 a0 23 3a e5 9f 30 04 e5 83 20 00 e1 2f ff 1e
</span></code></pre>
Disassembling this gives:</p>
0x0000000000000000:  E3 A0 23 3A    mov r2, #0xe8000000
</span>0x0000000000000004:  E5 9F 30 04    ldr r3, [pc, #4]
</span>0x0000000000000008:  E5 83 20 00    str r2, [r3]
</span>0x000000000000000c:  E1 2F FF 1E    bx  lr
</span></code></pre>
The implementation of this function in C is:</p>
void </span>buzzer_init</span>() {
</span>    VM_BASE_INIT(GPIO_VSTART);
</span>}
</span></code></pre>
Expanding the macro and constant:</p>
void </span>buzzer_init</span>() {
</span>    _global_base </span>= </span>0xE8000000</span>;
</span>}
</span></code></pre>
The presence of the constant 0xE8000000</code> in the C and assembly gave me some
degree of confidence that objdump</code> was correctly locating functions in the
object file and the online assembler could disassemble machine code into
instructions for the slug’s processor architecture.</p>
Observing the instruction offsets in the object file as analyzed by
llvm-objdump</code>, all the functions are consecutive. This invites the question as
to whether they are also consecutive with the same relative offset in the binary
image.</p>
Choosing a prefix of a function’s machine code (taken from the output of
llvm-objdump</code>) which is long enough to be unique
in the binary image, and searching for it with hexedit</code>, I could locate that
function in the binary image. I’ve highlighted the machine code for
buzzer_init</code>, tone</code>, and the beginning of call_me_maybe</code> in red, green, and
blue respectively in the following output from hexedit</code>:</p>
00032920   E0 D0 30 04  BA FF FF FB  E8 BD 80 F8  E3 A0 23 3A</span>  ..0...........#:
</span>00032930   E5 9F 30 04  E5 83 20 00  E1 2F FF 1E</span>  00 04 C2 50  ..0... ../.....P
</span>00032940   E9 2D 40 F8  E1 A0 40 01  E1 A0 10 80  E3 A0 09 3D</span>  .-@...@........=
</span>00032950   E2 80 0D 09  EB 00 AA 17  E1 A0 60 00  E1 A0 00 04</span>  ..........`.....
</span>00032960   E1 A0 10 86  EB 00 AA 13  E2 50 70 00  DA 00 00 10</span>  .........Pp.....
</span>00032970   E3 A0 40 00  E5 9F 50 3C  E5 95 30 00  E5 93 20 00</span>  ..@...P<..0... .
</span>00032980   E3 82 20 10  E5 83 20 00  E1 A0 00 06  EB FF FF D1</span>  .. ... .........
</span>00032990   E5 95 30 00  E5 93 20 00  E3 C2 20 10  E5 83 20 00</span>  ..0... ... ... .
</span>000329A0   E1 A0 00 06  EB FF FF CB  E2 84 40 01  E1 57 00 04</span>  ..........@..W..
</span>000329B0   CA FF FF F0  E8 BD 80 F8</span>  00 04 C2 50  E9 2D 40 F8</span>  ...........P.-@.
</span>000329C0   E1 A0 60 00  E5 9F 01 98  EB 00 16 16  E1 A0 00 06</span>  ..`.............
</span>000329D0   EB FF FF C0  E3 A0 0F 62  E1 A0 10 06  EB FF FF D7</span>  .......b........
</span>000329E0   E2 86 70 03  E3 56 00 00  A1 A0 70 06  E1 A0 71 47</span>  ..p..V....p...qG
</span>000329F0   E3 A0 00 F6  E1 A0 10 07  EB FF FF D0  E0 86 4F A6</span>  ..............O.
</span>00032A00   E1 A0 40 C4  E3 A0 5F 49  E2 85 50 01  E1 A0 00 05</span>  ..@..._I..P.....
</span>00032A10   E1 A0 10 04  EB FF FF C9  E3 A0 0F 62  E1 A0 10 07</span>  ...........b....
</span>---  bootimg.bin       --0x32A1C/0x7C000--41%----------------------------------
</span>
</span></code></pre>
Cross referencing this with the objdump</code> output it becomes clear that the
layout of this part of bootable image is the same as the object file
buzzer.o</code>. The location in memory of the buzzer functions relative to each
other will be the same as in the object file.</p>
Staring at this for a while I had the idea of rather than working out how to
call call_me_maybe</code> as a function, I could modify the buzzer_init</code> function to jump directly to the
beginning of call_me_maybe</code> instead of returning. When the main</code> function
calls buzzer_init</code>, that would then cause the song to play immediately rather
than requiring a separate call to call_me_maybe</code>.</p>
ARM assembly has a b</code>
instruction which jumps to a nearby address specified by a relative offset. So
if we’re replacing the final instruction of buzzer_init</code> to jump to the
beginning of call_me_maybe</code>, that’s a relative offset of 0xE4 - 0x60 = 0x84</code>.
The instruction b #0x84</code> encodes to the machine code EA 00 00 1F</code>, so I used
hexedit</code> to replace the final instruction of buzzer_init</code> (in red above)
with EA 00 00 1F</code>.</p>
This shows the same section of the binary as above, with the updated 4 bytes in
yellow:</p>
00032920   E0 D0 30 04  BA FF FF FB  E8 BD 80 F8  E3 A0 23 3A</span>  ..0...........#:
</span>00032930   E5 9F 30 04  E5 83 20 00  EA 00 00 1F</span></span>  00 04 C2 50  ..0... ../.....P
</span>00032940   E9 2D 40 F8  E1 A0 40 01  E1 A0 10 80  E3 A0 09 3D</span>  .-@...@........=
</span>00032950   E2 80 0D 09  EB 00 AA 17  E1 A0 60 00  E1 A0 00 04</span>  ..........`.....
</span>00032960   E1 A0 10 86  EB 00 AA 13  E2 50 70 00  DA 00 00 10</span>  .........Pp.....
</span>00032970   E3 A0 40 00  E5 9F 50 3C  E5 95 30 00  E5 93 20 00</span>  ..@...P<..0... .
</span>00032980   E3 82 20 10  E5 83 20 00  E1 A0 00 06  EB FF FF D1</span>  .. ... .........
</span>00032990   E5 95 30 00  E5 93 20 00  E3 C2 20 10  E5 83 20 00</span>  ..0... ... ... .
</span>000329A0   E1 A0 00 06  EB FF FF CB  E2 84 40 01  E1 57 00 04</span>  ..........@..W..
</span>000329B0   CA FF FF F0  E8 BD 80 F8</span>  00 04 C2 50  E9 2D 40 F8</span>  ...........P.-@.
</span>000329C0   E1 A0 60 00  E5 9F 01 98  EB 00 16 16  E1 A0 00 06</span>  ..`.............
</span>000329D0   EB FF FF C0  E3 A0 0F 62  E1 A0 10 06  EB FF FF D7</span>  .......b........
</span>000329E0   E2 86 70 03  E3 56 00 00  A1 A0 70 06  E1 A0 71 47</span>  ..p..V....p...qG
</span>000329F0   E3 A0 00 F6  E1 A0 10 07  EB FF FF D0  E0 86 4F A6</span>  ..............O.
</span>00032A00   E1 A0 40 C4  E3 A0 5F 49  E2 85 50 01  E1 A0 00 05</span>  ..@..._I..P.....
</span>00032A10   E1 A0 10 04  EB FF FF C9  E3 A0 0F 62  E1 A0 10 07</span>  ...........b....
</span>---  bootimg.bin       --0x32A1C/0x7C000--41%----------------------------------
</span>
</span></code></pre>
And running the result:</p>
...
</span>[gpio] starting
</span>[gpio] found region 0x001d13a8
</span>[gpio] paging success
</span>Hey I just met you
</span>And this is crazy
</span>But here's my number
</span>So call me maybe
</span>
</span>Starting "tty_test"...
</span>Loading first process.  Trying to set up a page table!
</span>...
</span></code></pre>
Hacker voice: I’m in.</em></p>
We’re successfully jumping into the call_me_maybe</code> function as evidence by the
printouts, but it’s not playing any sound yet. Here’s the C code again for
convenience:</p>
void </span>call_me_maybe</span>(</span>int </span>beat_len) {
</span>
</span>    </span>printf</span>(</span>"Hey I just met you</span>\n</span>"</span>);
</span>    udelay(beat_len);
</span>    tone(NOTE_G4, beat_len);
</span>    tone(NOTE_B3, beat_len</span>/</span>4</span>);
</span>    tone(NOTE_D4, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_G4, beat_len</span>/</span>4</span>);
</span>    tone(NOTE_G4, beat_len</span>/</span>4</span>);
</span>    tone(NOTE_D4, </span>3</span>*</span>beat_len</span>/</span>4</span>);
</span>
</span>    </span>printf</span>(</span>"And this is crazy</span>\n</span>"</span>);
</span>    udelay(beat_len);
</span>    udelay(beat_len</span>/</span>2</span>);
</span>    tone(NOTE_B3, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_B3, beat_len</span>/</span>4</span>);
</span>    tone(NOTE_D4, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_B4, beat_len</span>/</span>4</span>);
</span>    tone(NOTE_B4, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_G4, beat_len</span>/</span>2</span>);
</span>
</span>    </span>printf</span>(</span>"But here's my number</span>\n</span>"</span>);
</span>    udelay(beat_len);
</span>    udelay(beat_len</span>/</span>2</span>);
</span>    tone(NOTE_G4, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_B4, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_C5, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_B4, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_G4, beat_len</span>/</span>2</span>);
</span>
</span>    </span>printf</span>(</span>"So call me maybe</span>\n</span>"</span>);
</span>    udelay(beat_len);
</span>    udelay(beat_len</span>/</span>2</span>);
</span>    tone(NOTE_G4, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_B4, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_A4, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_A4, beat_len</span>/</span>2</span>);
</span>    tone(NOTE_G4, beat_len</span>/</span>2</span>);
</span>}
</span></code></pre>
Normally this function gets passed a beat_len</code> argument specifying the duration of each
beat in microseconds. But now that this function isn’t being called but rather jumped into</em>,
whatever processor register stores the beat length isn’t being initialized to anything in
particular. Its value will be whatever it was before jumping into this function.
Probably this values is very low, possibly 0, so the buzzes are too short to be
heard, hence the silence. More evidence for this theory is that all the song
lyrics are printed immediately, rather than with a noticeable delay in between.</p>
Let’s take a look at the disassembly of the beginning of call_me_maybe</code> which I’ve manually annotated:</p>
0x0000000000000000:  E9 2D 40 F8    push  {r3, r4, r5, r6, r7, lr}
</span>0x0000000000000004:  E1 A0 60 00    mov   r6, r0      }- save the beat_len arg in r6
</span>0x0000000000000008:  E5 9F 01 98    ldr   r0, [pc, #0x198]
</span>0x000000000000000c:  EB 00 16 16    bl    #0x586c     }- call printf
</span>0x0000000000000010:  E1 A0 00 06    mov   r0, r6      }- arg for udelay
</span>0x0000000000000014:  EB FF FF C0    bl    #0xffffff1c }- call udelay
</span>0x0000000000000018:  E3 A0 0F 62    mov   r0, #0x188  }- first arg for tone (note G4)
</span>0x000000000000001c:  E1 A0 10 06    mov   r1, r6      }- second arg for tone (beat_len)
</span>0x0000000000000020:  EB FF FF D7    bl    #0xffffff84 }- call tone
</span>0x0000000000000024:  E2 86 70 03    add   r7, r6, #3
</span>0x0000000000000028:  E3 56 00 00    cmp   r6, #0
</span>0x000000000000002c:  A1 A0 70 06    movge r7, r6
</span>0x0000000000000030:  E1 A0 71 47    asr   r7, r7, #2
</span>0x0000000000000034:  E3 A0 00 F6    mov   r0, #0xf6   }- first arg for tone (note B3)
</span>0x0000000000000038:  E1 A0 10 07    mov   r1, r7
</span>0x000000000000003c:  EB FF FF D0    bl    #0xffffff84 }- call tone
</span>0x0000000000000040:  E0 86 4F A6    add   r4, r6, r6, lsr #31
</span>0x0000000000000044:  E1 A0 40 C4    asr   r4, r4, #1
</span>0x0000000000000048:  E3 A0 5F 49    mov   r5, #0x124  }
</span>0x000000000000004c:  E2 85 50 01    add   r5, r5, #1  }- first arg for tone (note D4)
</span>0x0000000000000050:  E1 A0 00 05    mov   r0, r5      }
</span>0x0000000000000054:  E1 A0 10 04    mov   r1, r4
</span>0x0000000000000058:  EB FF FF C9    bl    #0xffffff84 }- call tone
</span>0x000000000000005c:  E3 A0 0F 62    mov   r0, #0x188  }- first arg for tone (note G4)
</span>0x0000000000000060:  E1 A0 10 07    mov   r1, r7
</span></code></pre>
It appears r0</code> is being used to pass the first
argument to functions (and r1</code> is used to pass the second argument).</p>
To build some confidence in this hypothesis, look at the signature for the tone</code> function:</p>
void </span>tone</span>(</span>int </span>frequency, </span>int </span>time);
</span></code></pre>
Throughout the assembly of call_me_maybe</code> we see r0</code> being set to a
representation of the note frequency and r1</code> being passed the note duration right before each bl #0xffffff84</code>
instruction, which looks like calls to the tone</code> function.</p>
The second line mov   r6, r0</code> is saving the beat
length (call_me_maybe</code>’s first and only argument) to r6</code> before using r0</code> for some other
purpose (to pass the argument to printf</code>). To increase the beat length we need to replace this second instruction
with an instruction that stores a higher value in r6</code>. This has to be done with
a single instruction, since the first instruction of this function is important
in maintaining the function calling convention (otherwise the OS would crash
when call_me_maybe</code> returned), and the third instruction is necessary for
printing “Hey I just met you”. And remember we can’t insert or remove bytes -
only update them in place.</p>
I found that the original value of r6</code> (before the second instruction set it to
the contents of r0</code>) was non-zero, as replacing the mov r6, r0</code> with an instruction that does nothing
(such as mov r0, r0</code>) caused the song to play, albeit too fast. But that
indicates this approach will definitely work!</p>
Rather than doing nothing, I need the second instruction to increase the
existing value of r6</code> by some amount. There are several approaches I could have
taken, but I found that simply doubling its value by shifting it by one bit to
the left gives a suitable beat length. I replaced the second instruction
with lsl r6, r6, #1</code> which assembles to E1 A0 60 86</code>.</p>
Here’s the result:</p>
</iframe>
What strikes me about this project is that I worked on it in a time before I
started compulsively uploading all the code I wrote to a code forge like github.
This was for a university assignment so perhaps there was a policy against
that sort of thing. At this time github was still relatively new and I wasn’t
very familiar with version control, so it sometimes seemed too complex to be
worth using it for every project.</p>
Nowadays I can’t imagine a workflow that doesn’t involve regular
commits to a version control system and it’s so easy to push all my code to
github that I doubt I’ll ever lose access to code I wrote since 2015 or so.
I horde everything in the off chance that it will be useful or at least
interesting to someone in the future.</p>
Since this assignment was group work we did use version control to manage
changes. My copy of the source still contains version control metadata and I can
see we used my assignment partner’s user account on the university server as our
centralized repository, and I doubt that’s archived anywhere.
The last commit in my copy of the project is from midway through the semester.
Fortunately the copy I made on my account was taken after I added the Easter
egg.</p>
changeset:   41:1329df276e9a
</span>parent:      35:29e1993e26ba
</span>user:        Stephen Sherratt <ssteve@cse.unsw.edu.au>
</span>date:        Sun Jul 29 16:25:22 2012 +1000
</span>summary:     wrote function that plays Call Me Maybe
</span></code></pre>

Sound on OCaml on Windows

Stephen Sherratt — Mon, 02 Jun 2025 00:00:00 +0000

I got my OCaml music synthesizer working on Windows. Here’s all the things that went wrong in the process.

This post will chronicle my attempt to use OCaml to play generated audio samples on a Windows PC. This is part of my work on the llama synthesizer library</a>, where I’ve been rewriting the low-level audio logic formerly written in Rust (with cpal</a>) into OCaml to simplify the build process and development experience. I’ve written down some of my complaints about the developer experience working on llama</code> in a previous post</a> and some of those difficulties came from complications working with Rust/OCaml interop, so removing all Rust from the project will help reduce friction developing it further.

I have a proof-of-concept version of llama</code> based on OCaml’s libao bindings</a> which works on Linux and MacOS. Libao claims to support Windows but I haven’t figured out how to install it on Windows so I might experiment with some easier-to-install alternatives in this post.

The intention of this post is to serve as a guide to anyone getting started with OCaml on Windows, to highlight some of the remaining problems with the OCaml ecosystem on Windows, and to demonstrate some usability issues with Opam in general. My summary is that OCaml on Windows is easier than I expected it to be, but there are still some rough edges that newcomers should be aware of to properly set expectations. I wrote down everything I tried as I tried it, so all the mistakes, blind alleys and failed debugging experiments will be documented here as well as the paths that eventually led to solutions.

Install Opam</a></h2> For the purposes of this post I’ll set up an entire OCaml environment on Windows from scratch. I’ll be using PowerShell 7.5.1 for all shell commands in this post. For the purposes of translating commands and paths to other machines, I’ll state explicitly that my username is “s”. We’ll install Opam with WinGet. I’ve had some difficulty setting up WinGet in the past and written about setting it up properly in a previous post</a> but today it worked as expected. PS C:\Users\s> winget install Git.Git OCaml.opam ... PS C:\Users\s> opam init ... How should opam obtain Unix tools? > 1. Automatically create an internal Cygwin installation that will be managed by opam (recommended) 2. Use an existing Cygwin/MSYS2 installation 3. Abort initialisation [1/2/3] 1 <-- here I selected option 1 ... </code></pre> Allowing Opam to manage its own Cygwin installation is the recommended way of using Opam on Windows, so that’s what I’ll try first. This results in Cygwin being installed to C:\Users\s\AppData\Local\opam\.cygwin</code>. This might come in handy to know if we ever need to manually install a Cygwin package, though hopefully Opam can take care of installing any such packages via Opam’s depexts</code> system which knows how to install system-specific packages needed by Opam packages by directly invoking the package manager to install the appropriately-named package. Bear in mind that Opam’s initialization can take 15 minutes or so on Windows with most of the time spent building the OCaml compiler. Compiling OCaml code on Windows tends to be much slower than on MacOS and Linux. I don’t understand why. Install a sound library</a></h2> We need to choose a library in the Opam repository that can give us access to the sound card. Ideally we would use a library with a depext</code> tailored to Windows with Cygwin, as that way Opam can take care of installing any system dependencies via Cygwin. Since my experimental version of llama</code> is already implemented with libao that would be the most convenient choice, however its depexts</code> don’t look promising: PS C:\Users\s> opam show conf-ao ... depexts ["libao-devel"] {os-distribution = "centos" | os-family = "fedora" | os-family = "suse" | os-family = "opensuse"} ["libao"] {os = "freebsd" | os = "macos" & os-distribution = "homebrew" | os-distribution = "nixos" | os-family = "arch"} ["libao-dev"] {os-family = "debian" | os-family = "ubuntu" | os-distribution = "alpine"} </code></pre> There are no entries in that list for Windows, so using libao would require setting it up manually which I’d prefer to avoid. Another candidate library is portaudio</a>. PS C:\Users\s> opam show conf-portaudio ... depexts ["portaudio-dev"] {os-distribution = "alpine"} ["portaudio-devel"] {os-distribution = "centos" | os-distribution = "fedora" | os-family = "suse" | os-family = "opensuse"} ["portaudio"] {os = "macos" & os-distribution = "homebrew"} ["portaudio"] {os = "freebsd" | os-family = "arch" | os-distribution = "nixos" | os-distribution = "ol"} ["portaudio"] {os = "win32" & os-distribution = "cygwinports"} ["portaudio19-dev"] {os-family = "debian" | os-family = "ubuntu"} </code></pre> That’s more promising as there’s a depext</code> that gets chosen on {os = "win32" & os-distribution = "cygwinports"}</code>. It’s a little concerning that the name of the os-distribution</code> is “cygwinports” and not just “cygwin”. I’ve never come across cygwinports before, but maybe it won’t matter. The next step is to see if installing conf-portaudio</code> with Opam causes the right depext</code> to be installed with Cygwin: PS C:\Users\s> opam install conf-portaudio The following actions will be performed: === recompile 1 package ↻ mingw-w64-shims 0.2.0 [uses conf-pkg-config] === install 2 packages ∗ conf-pkg-config 4 [required by conf-portaudio] ∗ conf-portaudio 1 Proceed with ↻ 1 recompilation and ∗ 2 installations? [y/n] y The following system packages will first need to be installed: pkgconf <><> Handling external dependencies <><><><><><><><><><><><><><><><><><><><> 🐫 + C:\Users\s\AppData\Local\opam\.cygwin\setup-x86_64.exe "--root" "C:\\Users\\s\\AppData\\Local\\opam\\.cygwin\\root" "--quiet-mode" "noinput" "--no-shortcuts" "--no-startmenu" "--no-desktop" "--no-admin" "--no-version-check" "--no-write-registry" "--packages" "pkgconf" "--upgrade-also" "--only-site" "--site" "https://cygwin.mirror.constant.com/" "--local-package-dir" "C:\\Users\\s\\AppData\\Local\\opam\\.cygwin\\cache" - Starting cygwin install, version 2.934 - User has NO backup/restore rights - User has NO symlink creation right - io_stream_cygfile: fopen(/etc/setup/setup.rc) failed 2 No such file or directory - Current Directory: C:\Users\s\AppData\Local\opam\.cygwin\cache - root: C:\Users\s\AppData\Local\opam\.cygwin\root user - Changing gid back to original - Selected local directory: C:\Users\s\AppData\Local\opam\.cygwin\cache - net: Preconfig - site: https://cygwin.mirror.constant.com/ - solving: 1 tasks, update: yes, use test packages: no - solving: 2 tasks, update: no, use test packages: no - Augmented Transaction List: - 0 install libpkgconf6 2.4.3-1 - 1 install pkgconf 2.4.3-1 - Downloaded C:\Users\s\AppData\Local\opam\.cygwin\cache/https%3a%2f%2fcygwin.mirror.constant.com%2f/x86_64/release/pkgconf/libpkgconf6/libpkgconf6-2.4.3-1.tar.zst - Downloaded C:\Users\s\AppData\Local\opam\.cygwin\cache/https%3a%2f%2fcygwin.mirror.constant.com%2f/x86_64/release/pkgconf/pkgconf-2.4.3-1.tar.zst - Extracting from file://C:\Users\s\AppData\Local\opam\.cygwin\cache/https%3a%2f%2fcygwin.mirror.constant.com%2f/x86_64/release/pkgconf/libpkgconf6/libpkgconf6-2.4.3-1.tar.zst - Extracting from file://C:\Users\s\AppData\Local\opam\.cygwin\cache/https%3a%2f%2fcygwin.mirror.constant.com%2f/x86_64/release/pkgconf/pkgconf-2.4.3-1.tar.zst - running: C:\Users\s\AppData\Local\opam\.cygwin\root\bin\dash.exe "/etc/postinstall/0p_000_autorebase.dash" - running: C:\Users\s\AppData\Local\opam\.cygwin\root\bin\dash.exe "/etc/postinstall/0p_update-info-dir.dash" - running: C:\Users\s\AppData\Local\opam\.cygwin\root\bin\dash.exe "/etc/postinstall/zp_man-db-update-index.dash" - Ending cygwin install <><> Processing actions <><><><><><><><><><><><><><><><><><><><><><><><><><> 🐫 ⬇ retrieved mingw-w64-shims.0.2.0 (cached) ⊘ removed mingw-w64-shims.0.2.0 ∗ installed conf-pkg-config.4 #=== ERROR while compiling conf-portaudio.1 ===================================# "pkg-config": command not found. <><> Error report <><><><><><><><><><><><><><><><><><><><><><><><><><><><><> 🐫 ┌─ The following actions failed │ λ build conf-portaudio 1 └─ ┌─ The following changes have been performed (the rest was aborted) │ ⊘ remove mingw-w64-shims 0.2.0 │ ∗ install conf-pkg-config 4 └─ </code></pre> A few things have gone wrong here. Firstly, from: The following system packages will first need to be installed: pkgconf </code></pre> …we can see that Opam has detected that some depexts</code> need to be installed, but only pkgconf</code> and not portaudio</code> are on the list. To help understand why, look at the depexts</code> of the conf-pkg-config</code> package: PS C:\Users\s> opam show conf-pkg-config ... depexts ["pkg-config"] {os-family = "debian" | os-family = "ubuntu"} ... ["system:pkgconf"] {os = "win32" & os-distribution = "cygwinports"} ["pkgconf"] {os-distribution = "cygwin"} </code></pre> This package makes an explicit distinction between “cygwinports” and “cygwin” so it stands to reason that my initial concerns about os-distribution = "cygwinports"</code> were merited. The second issue is that even though Opam installed pkgconf</code> with Cygwin, the pkg-config</code> executable couldn’t be found while installing the conf-portaudio</code> package. Remember earlier we located the Cygwin installation that Opam will be managing? Looking in C:\Users\s\AppData\Local\opam\.cygwin\root\bin</code>, there is a program pkgconf.exe</code>, but not a pkg-config.exe</code>. At some point in the past few years pkg-config</code> was renamed to pkgconf</code> and this change is slowly trickling into different package managers at different rates. The first thing to try here is modifying the package metadata for conf-portaudio</code> to use the correct name for pkgconf</code>. Start by saving the existing metadata to a local file which we can then modify: PS C:\Users\s> opam show conf-portaudio --raw > conf-portaudio.opam </code></pre> We should now be able to install the conf-portaudio</code> package from this file rather than using the metadata stored in the Opam repo by running: PS C:\Users\s> opam install .\conf-portaudio.opam </code></pre> This command hung with Processing 1/1: [conf-portaudio.1: rsync]</code> so I left it running while I went to run some errands and when I got back over an hour later it was still hung. I cancelled the hung operation. Despite not completing it did have the side effect of creating an Opam “pin” for the conf-portaudio</code> package. An Opam pin is a configuration to override the source of a package, usually to allow for local development of said package. We can see all the current Opam pins with: PS C:\Users\s> opam pin list conf-portaudio.1 (uninstalled) rsync file://C:/Users/s </code></pre> Before proceeding I wanted to remove the pin since something has clearly gone wrong: PS C:\Users\s> opam pin remove conf-portaudio Cannot remove C:\Users\s\AppData\Local\opam\default\.opam-switch\sources\conf-portaudio\ AppData\Local\Application Data\Application Data\Application Data\Application Data\ Application Data\Application Data\Application Data\Application Data\Application Data\ Temporary Internet Files (C:\Users\s\AppData\Local\Microsoft\WinGet\Packages\ OCaml.opam_Microsoft.Winget.Source_8wekyb3d8bbwe\opam.exe: "unlink" failed on C:\Users\s\AppData\Local\opam\default\.opam-switch\sources\conf-portaudio\AppData\ Local\Application Data\Application Data\Application Data\Application Data\ Application Data\Application Data\Application Data\Application Data\Application Data\ Temporary Internet Files: No such file or directory). </code></pre> Hmm. The Application Data\Application Data\Application Data</code> component of the path looks suspicious. Opam creates a copy of pinned packages so let’s take a look at conf-portaudio</code>’s copy in C:\Users\s\AppData\Local\opam\default\.opam-switch\sources\conf-portaudio</code>: PS C:\Users\s> ls .\AppData\Local\opam\default\.opam-switch\sources\conf-portaudio\ Directory: C:\Users\s\AppData\Local\opam\default\.opam-switch\sources\conf-portaudio Mode LastWriteTime Length Name ---- ------------- ------ ---- d---- 04/11/2024 21:49 .bin d---- 04/11/2024 22:26 .cargo d---- 04/11/2024 21:49 .completions d---- 04/11/2024 21:49 .config d---- 22/11/2024 14:34 .dotfiles d---- 04/11/2024 21:49 .emacs.d d---- 25/11/2024 15:12 .local d---- 04/11/2024 21:59 .ms-ad d---- 04/11/2024 22:25 .rustup d---- 04/11/2024 21:29 .ssh d---- 18/11/2024 14:35 .vscode d---- 29/05/2025 16:03 AppData -a--- 28/03/2025 17:00 3654 .bash_history -a--- 25/11/2024 18:07 9168 .bashrc ... </code></pre> Hey, that looks like my home directory! It appears I unwittingly pinned the conf-portaudio</code> package to my entire home directory, and since Opam installs packages inside my home directory it was recurring forever, continuously copying my home directory inside itself. No wonder it hung. Manually fixing the problem: PS C:\Users\s> rm .\AppData\Local\opam\default\.opam-switch\sources\conf-portaudio Confirm The item at C:\Users\s\AppData\Local\opam\default\.opam-switch\sources\conf-portaudio has children and the Recurse parameter was not specified. If you continue, all children will be removed with the item. Are you sure you want to continue? [Y] Yes [A] Yes to All [N] No [L] No to All [S] Suspend [?] Help (default is "Y"): A Removed 32536 of 134845 files [1.197 GB of 15.926 GB (48.6 MB/s) </code></pre> That’s almost 16GB</code> of recursive copies of my home directory! This command ended up failing due to permission problems so I had to delete it from the explorer UI instead as I’m not very familiar with file management within PowerShell. Now that I manually deleted that folder, removing the pin works: PS C:\Users\s> opam pin remove conf-portaudio Ok, conf-portaudio is no longer pinned to file://C:/Users/s (version 1) </code></pre> What I’ve learnt here is that Opam doesn’t pin individual files but rather entire directories. A pin is a mapping from package to directory, and when you run opam pin .\foo.opam</code> Opam learns the package name is foo</code> from the name of the file (I think), but assumes the directory is the directory containing foo.opam</code>. Most Opam package source directories contain an opam file and the source code for the package. What’s unusual in this case is that the conf-portaudio</code> package does not have source code. We say it’s a “metapackage” as installing it just installs its dependencies (including external dependencies) and runs a command to verify their installation, but it has no source code of its own. So in order to pin conf-portaudio</code> we need to first create a new directory and move the opam file there. Pinning the directory is sufficient as Opam will scan the directory for any opam files and create pins for each corresponding package using the current directory as the source. I’ve also modified the opam file to run pkgconf</code> rather than pkg-config</code>. PS C:\Users\s\conf-portaudio> opam pin . [NOTE] Package conf-portaudio is already pinned to file://C:/Users/s/conf-portaudio (version 1). conf-portaudio is now pinned to file://C:/Users/s/conf-portaudio (version 1) The following actions will be performed: === install 1 package ∗ conf-portaudio 1 (pinned) Proceed with ∗ 1 installation? [y/n] n (don't want to install it just yet) [NOTE] Pinning command successful, but your installed packages may be out of sync. </code></pre> By default opam pin</code> will prompt to install the pinned package in addition to just storing the package → directory mapping, but I just want to create the mapping for now so I chose n</code> at the prompt. Before installing the package I want to make sure that pinning it had the desired effect. Ask Opam what it thinks should be the package metadata for conf-portaudio</code> now: PS C:\Users\s\conf-portaudio> opam show conf-portaudio --raw opam-version: "2.0" name: "conf-portaudio" version: "1" synopsis: "Virtual package relying on portaudio" description: "This package can only install if the portaudio library is installed on the system." maintainer: "https://github.com/ocaml/opam-repository/issues" authors: "portaudio dev team" license: "BSD-1-Clause" homepage: "http://www.portaudio.com/" bug-reports: "https://github.com/ocaml/opam-repository/issues" depends: [ "conf-pkg-config" {build} ] flags: conf build: ["pkgconf" "--exists" "portaudio-2.0"] depexts: [ ["portaudio-dev"] {os-distribution = "alpine"} ["portaudio-devel"] {os-distribution = "centos" | os-family = "fedora" | os-family = "suse" | os-family = "opensuse"} ["portaudio"] {os = "macos" & os-distribution = "homebrew"} ["portaudio"] {os = "freebsd" | os-family = "arch" | os-distribution = "nixos" | os-distribution = "ol"} ["portaudio"] {os = "win32" & os-distribution = "cygwinports"} ["portaudio19-dev"] {os-family = "debian" | os-family = "ubuntu"} ] url { src: "file://C:/Users/s/conf-portaudio" } </code></pre> Note that the build</code> command calls pkgconf</code> rather than pkg-config</code> as it did previously, indicating that my custom version of conf-portaudio</code> is being used. Now we can try installing it again. PS C:\Users\s\conf-portaudio> opam install conf-portaudio <><> Synchronising pinned packages ><><><><><><><><><><><><><><><><><><><><> 🐫 [conf-portaudio.1] synchronised (no changes) The following actions will be performed: === install 1 package ∗ conf-portaudio 1 (pinned) <><> Processing actions <><><><><><><><><><><><><><><><><><><><><><><><><><> 🐫 [ERROR] The compilation of conf-portaudio.1 failed at "pkgconf --exists portaudio-2.0". #=== ERROR while compiling conf-portaudio.1 ===================================# # context 2.3.0 | win32/x86_64 | ocaml.5.3.0 | pinned(file://C:/Users/s/conf-portaudio) # path ~\AppData\Local\opam\default\.opam-switch\build\conf-portaudio.1 # command ~\AppData\Local\opam\.cygwin\root\bin\pkgconf.exe --exists portaudio-2.0 # exit-code 1 # env-file ~\AppData\Local\opam\log\conf-portaudio-12212-533065.env # output-file ~\AppData\Local\opam\log\conf-portaudio-12212-533065.out <><> Error report <><><><><><><><><><><><><><><><><><><><><><><><><><><><><> 🐫 ┌─ The following actions failed │ λ build conf-portaudio 1 └─ ╶─ No changes have been performed </code></pre> That’s progress! There’s now an error message indicating that pkgconf --exists portaudio-2.0</code> failed, which is expected because the conf-portaudio</code> package’s depexts</code> don’t contain a case for os-distribution = "cygwin"</code> (only os-distribution = "cygwinports"</code>). Next step is to fix the conf-portaudio</code> depexts</code> so they install the appropriate package on Cygwin. I added this line to the depexts</code> section in conf-portaudio.opam</code>: ["portaudio"] {os = "win32" & os-distribution = "cygwin"} </code></pre> I needed to run opam pin .</code> again to get Opam to update its copy of the custom version of this package’s metadata. Every time you change the opam file of a pinned package you have to re-pin the package for the change to be come visible to Opam. Then I tried installing conf-portaudio</code> again: PS C:\Users\s\conf-portaudio> opam install conf-portaudio <><> Synchronising pinned packages ><><><><><><><><><><><><><><><><><><><><> 🐫 [conf-portaudio.1] synchronised (no changes) The following actions will be performed: === install 1 package ∗ conf-portaudio 1 (pinned) The following system packages will first need to be installed: portaudio <><> Handling external dependencies <><><><><><><><><><><><><><><><><><><><> 🐫 + C:\Users\s\AppData\Local\opam\.cygwin\setup-x86_64.exe "--root" "C:\\Users\\s\\AppData\\Local\\opam\\.cygwin\\root" "--quiet-mode" "noinput" "--no-shortcuts" "--no-startmenu" "--no-desktop" "--no-admin" "--no-version-check" "--no-write-registry" "--packages" "portaudio" "--upgrade-also" "--only-site" "--site" "https://cygwin.mirror.constant.com/" "--local-package-dir" "C:\\Users\\s\\AppData\\Local\\opam\\.cygwin\\cache" - Starting cygwin install, version 2.934 - User has NO backup/restore rights - User has NO symlink creation right - io_stream_cygfile: fopen(/etc/setup/setup.rc) failed 2 No such file or directory - Current Directory: C:\Users\s\AppData\Local\opam\.cygwin\cache - root: C:\Users\s\AppData\Local\opam\.cygwin\root user - Changing gid back to original - Selected local directory: C:\Users\s\AppData\Local\opam\.cygwin\cache - net: Preconfig - site: https://cygwin.mirror.constant.com/ - Package 'portaudio' not found. - solving: 0 tasks, update: yes, use test packages: no - solving: 0 tasks, update: no, use test packages: no - Augmented Transaction List: is empty - running: C:\Users\s\AppData\Local\opam\.cygwin\root\bin\dash.exe "/etc/postinstall/0p_000_autorebase.dash" - running: C:\Users\s\AppData\Local\opam\.cygwin\root\bin\dash.exe "/etc/postinstall/0p_update-info-dir.dash" - running: C:\Users\s\AppData\Local\opam\.cygwin\root\bin\dash.exe "/etc/postinstall/zp_man-db-update-index.dash" - Ending cygwin install <><> Processing actions <><><><><><><><><><><><><><><><><><><><><><><><><><> 🐫 [ERROR] The compilation of conf-portaudio.1 failed at "pkgconf --exists portaudio-2.0". #=== ERROR while compiling conf-portaudio.1 ===================================# # context 2.3.0 | win32/x86_64 | ocaml.5.3.0 | pinned(file://C:/Users/s/conf-portaudio) # path ~\AppData\Local\opam\default\.opam-switch\build\conf-portaudio.1 # command ~\AppData\Local\opam\.cygwin\root\bin\pkgconf.exe --exists portaudio-2.0 # exit-code 1 # env-file ~\AppData\Local\opam\log\conf-portaudio-9396-6b5019.env # output-file ~\AppData\Local\opam\log\conf-portaudio-9396-6b5019.out <><> Error report <><><><><><><><><><><><><><><><><><><><><><><><><><><><><> 🐫 ┌─ The following actions failed │ λ build conf-portaudio 1 └─ ╶─ No changes have been performed </code></pre> This time Opam tried to install the portaudio</code> Cygwin package, however Package 'portaudio' not found.</code> tells us that there is no such Cygwin package. However digging around in the Cygwin package repo I did come across a package named mingw64-x86_64-portaudio</code>, though it’s unmaintained and hasn’t been updated since 2018. I also happened to find the package mingw64-x86_64-libao</code>, also unmaintained and not updated since 2013, however if this package works then I might be able to use llama</code> on Windows unmodified, since it’s currently based on libao. Repeating the steps above to create a custom version of the conf-ao</code> package - Opam’s meta package for installing the system-appropriate libao package: PS C:\Users\s\conf-ao> opam show conf-ao --raw > conf-ao.opam PS C:\Users\s\conf-ao> opam pin . conf-ao is now pinned to file://C:/Users/s/conf-ao (version 1) The following actions will be performed: === install 1 package ∗ conf-ao 1 (pinned) Proceed with ∗ 1 installation? [y/n] n [NOTE] Pinning command successful, but your installed packages may be out of sync. </code></pre> Then I modified conf-ao.opam</code>, adding the following to its depexts</code>: ["mingw64-x86_64-libao"] {os = "win32" & os-distribution = "cygwin"} </code></pre> …and changed its build command to test for the system libao package using pkgconf</code> instead of pkg-config</code>, the same as what I did for conf-portaudio</code>. Moment of truth: PS C:\Users\s\conf-ao> opam install conf-ao <><> Synchronising pinned packages ><><><><><><><><><><><><><><><><><><><><> 🐫 [conf-ao.1] synchronised (no changes) The following actions will be performed: === install 1 package ∗ conf-ao 1 (pinned) The following system packages will first need to be installed: mingw64-x86_64-libao <><> Handling external dependencies <><><><><><><><><><><><><><><><><><><><> 🐫 + C:\Users\s\AppData\Local\opam\.cygwin\setup-x86_64.exe "--root" "C:\\Users\\s\\AppData\\Local\\opam\\.cygwin\\root" "--quiet-mode" "noinput" "--no-shortcuts" "--no-startmenu" "--no-desktop" "--no-admin" "--no-version-check" "--no-write-registry" "--packages" "mingw64-x86_64-libao" "--upgrade-also" "--only-site" "--site" "https://cygwin.mirror.constant.com/" "--local-package-dir" "C:\\Users\\s\\AppData\\Local\\opam\\.cygwin\\cache" - Starting cygwin install, version 2.934 - User has NO backup/restore rights - User has NO symlink creation right - Current Directory: C:\Users\s\AppData\Local\opam\.cygwin\cache - root: C:\Users\s\AppData\Local\opam\.cygwin\root user - Changing gid back to original - Selected local directory: C:\Users\s\AppData\Local\opam\.cygwin\cache - net: Preconfig - site: https://cygwin.mirror.constant.com/ - solving: 1 tasks, update: yes, use test packages: no - solving: 1 tasks, update: no, use test packages: no - Augmented Transaction List: - 0 install mingw64-x86_64-libao 1.1.0-1 - Downloaded C:\Users\s\AppData\Local\opam\.cygwin\cache/https%3a%2f%2fcygwin.mirror.constant.com%2f/noarch/release/mingw64-x86_64-libao/mingw64-x86_64-libao-1.1.0-1.tar.xz - Extracting from file://C:\Users\s\AppData\Local\opam\.cygwin\cache/https%3a%2f%2fcygwin.mirror.constant.com%2f/noarch/release/mingw64-x86_64-libao/mingw64-x86_64-libao-1.1.0-1.tar.xz - running: C:\Users\s\AppData\Local\opam\.cygwin\root\bin\dash.exe "/etc/postinstall/0p_000_autorebase.dash" - running: C:\Users\s\AppData\Local\opam\.cygwin\root\bin\dash.exe "/etc/postinstall/0p_update-info-dir.dash" - running: C:\Users\s\AppData\Local\opam\.cygwin\root\bin\dash.exe "/etc/postinstall/zp_man-db-update-index.dash" - Ending cygwin install <><> Processing actions <><><><><><><><><><><><><><><><><><><><><><><><><><> 🐫 [ERROR] The compilation of conf-ao.1 failed at "pkgconf --exists ao". #=== ERROR while compiling conf-ao.1 ==========================================# # context 2.3.0 | win32/x86_64 | ocaml.5.3.0 | pinned(file://C:/Users/s/conf-ao) # path ~\AppData\Local\opam\default\.opam-switch\build\conf-ao.1 # command ~\AppData\Local\opam\.cygwin\root\bin\pkgconf.exe --exists ao # exit-code 1 # env-file ~\AppData\Local\opam\log\conf-ao-8080-676a1b.env # output-file ~\AppData\Local\opam\log\conf-ao-8080-676a1b.out <><> Error report <><><><><><><><><><><><><><><><><><><><><><><><><><><><><> 🐫 ┌─ The following actions failed │ λ build conf-ao 1 └─ ╶─ No changes have been performed </code></pre> Ok so it found the mingw64-x86_64-libao</code> package in the Cygwin repo but it looks like pkgconf</code> can’t see it. Manually inspecting the Cygwin directory, and I do see that libao has been installed: PS C:\Users\s\conf-ao> ls C:\Users\s\AppData\Local\opam\.cygwin\root\usr\x86_64-w64-mingw32\sys-root\mingw\lib\libao.* Directory: C:\Users\s\AppData\Local\opam\.cygwin\root\usr\x86_64-w64-mingw32\sys-root\mingw\lib Mode LastWriteTime Length Name ---- ------------- ------ ---- -a--- 02/12/2013 15:27 50102 libao.a -a--- 02/12/2013 15:27 9386 libao.dll.a </code></pre> But that’s doesn’t look like a standard path for libraries. Reading more about the mingw64-x86_64-*</code> packages in the Cygwin repo and it doesn’t look like I’ll easily be able to mix them with other Cygwin packages, which could make it tricky to proceed with Opam in its current configuration where it manages a Cygwin environment for us. An alternative package manager for Windows is “Msys2”. During opam init</code> you can select Msys2 as an alternative to Cygwin, though there’s no option for Opam to install the Msys2 environment for us. There appears to be a libao</code> package in the Msys2 repository, so the next step will be to try setting up an Msys2 environment and a new Opam installation which uses it and then install the conf-ao</code> package along with its depexts</code> within that environment. Trying again with Msys2</a></h2> Firstly I deleted C:\Users\s\AppData\Local\opam</code> to get a fresh start. I installed Msys2 from the installer at its website</a>, which created a directory C:\msys64</code> which will be the root directory of our Msys2 environment. Then I reran opam init</code> to create a new Opam environment, this time selecting the second option for obtaining Unix tools: Use an existing Cygwin/MSYS2 installation</code>. I’ll post the entire output of the interactive session with opam init</code> in case it helps someone set up Opam on their machine: PS C:\Users\s> opam init No configuration file found, using built-in defaults. <><> Windows Developer Mode <><><><><><><><><><><><><><><><><><><><><><><><> 🐫 opam does not require Developer Mode to be enabled on Windows, but it is recommended, in particular because it enables support for symlinks without requiring opam to be run elevated (which we do not recommend doing). More information on enabling Developer Mode may be obtained from https://learn.microsoft.com/en-gb/windows/apps/get-started/enable-your-device-for-development <><> Unix support infrastructure ><><><><><><><><><><><><><><><><><><><><><> 🐫 opam and the OCaml ecosystem in general require various Unix tools in order to operate correctly. At present, this requires the installation of Cygwin to provide these tools. How should opam obtain Unix tools? > 1. Automatically create an internal Cygwin installation that will be managed by opam (recommended) 2. Use an existing Cygwin/MSYS2 installation 3. Abort initialisation [1/2/3] 2 Enter the prefix of an existing Cygwin installation (e.g. C:\cygwin64) C:\msys64 The following system packages will first need to be installed: diffutils make patch rsync unzip <><> Handling external dependencies <><><><><><><><><><><><><><><><><><><><> 🐫 opam believes some required external dependencies are missing. opam can: > 1. Run C:\msys64\usr\bin\pacman.exe to install them (may need root/sudo access) 2. Display the recommended C:\msys64\usr\bin\pacman.exe command and wait while you run it manually (e.g. in another terminal) 3. Continue anyway, and, upon success, permanently register that this external dependency is present, but not detectable 4. Abort the installation [1/2/3/4] 1 + C:\msys64\usr\bin\pacman.exe "-Su" "--noconfirm" "diffutils" "make" "patch" "rsync" "unzip" - :: Starting core system upgrade... - there is nothing to do - :: Starting full system upgrade... - resolving dependencies... - looking for conflicting packages... - - Packages (6) libxxhash-0.8.3-1 diffutils-3.10-1 make-4.4.1-2 patch-2.7.6-3 rsync-3.4.1-1 unzip-6.0-3 - - Total Download Size: 1.43 MiB - Total Installed Size: 4.51 MiB - - :: Proceed with installation? [Y/n] - :: Retrieving packages... - make-4.4.1-2-x86_64 downloading... - diffutils-3.10-1-x86_64 downloading... - rsync-3.4.1-1-x86_64 downloading... - unzip-6.0-3-x86_64 downloading... - patch-2.7.6-3-x86_64 downloading... - libxxhash-0.8.3-1-x86_64 downloading... - checking keyring... - checking package integrity... - loading package files... - checking for file conflicts... - checking available disk space... - :: Processing package changes... - installing diffutils... - installing make... - installing patch... - Optional dependencies for patch - ed: for patch -e functionality - installing libxxhash... - installing rsync... - installing unzip... - :: Running post-transaction hooks... - (1/1) Updating the info directory file... Checking for available remotes: rsync and local, git. - you won't be able to use mercurial repositories unless you install the hg command on your system. - you won't be able to use darcs repositories unless you install the darcs command on your system. <><> Fetching repository information ><><><><><><><><><><><><><><><><><><><> 🐫 [default] Initialised <><> Required setup - please read <><><><><><><><><><><><><><><><><><><><><> 🐫 In normal operation, opam only alters files within ~\AppData\Local\opam. However, to best integrate with your system, some environment variables should be set. When you want to access your opam installation, you will need to run: (& opam env) -split '\r?\n' | ForEach-Object { Invoke-Expression $_ } You can always re-run this setup with 'opam init' later. opam doesn't have any configuration options for pwsh; you will have to run (& opam env) -split '\r?\n' | ForEach-Object { Invoke-Expression $_ } whenever you change you current 'opam switch' or start a new terminal session. Alternatively, would you like to select a different shell? [y/n] n <><> Creating initial switch 'default' (invariant ["ocaml" {>= "4.05.0"}] - initially with ocaml-base-compiler) <><> Installing new switch packages <><><><><><><><><><><><><><><><><><><><> 🐫 Switch invariant: ["ocaml" {>= "4.05.0"}] The following system packages will first need to be installed: mingw-w64-x86_64-gcc <><> Handling external dependencies <><><><><><><><><><><><><><><><><><><><> 🐫 opam believes some required external dependencies are missing. opam can: > 1. Run C:\msys64\usr\bin\pacman.exe to install them (may need root/sudo access) 2. Display the recommended C:\msys64\usr\bin\pacman.exe command and wait while you run it manually (e.g. in another terminal) 3. Continue anyway, and, upon success, permanently register that this external dependency is present, but not detectable 4. Abort the installation [1/2/3/4] 1 + C:\msys64\usr\bin\pacman.exe "-Su" "--noconfirm" "mingw-w64-x86_64-gcc" - :: Starting core system upgrade... - there is nothing to do - :: Starting full system upgrade... - resolving dependencies... - looking for conflicting packages... - - Packages (16) mingw-w64-x86_64-binutils-2.44-1 mingw-w64-x86_64-crt-git-12.0.0.r509.g079e6092b-1 mingw-w64-x86_64-gcc-libs-14.2.0-2 mingw-w64-x86_64-gettext-runtime-0.23.1-1 mingw-w64-x86_64-gmp-6.3.0-2 mingw-w64-x86_64-headers-git-12.0.0.r509.g079e6092b-1 mingw-w64-x86_64-isl-0.27-1 mingw-w64-x86_64-libiconv-1.18-1 mingw-w64-x86_64-libwinpthread-git-12.0.0.r509.g079e6092b-1 mingw-w64-x86_64-mpc-1.3.1-2 mingw-w64-x86_64-mpfr-4.2.1-2 mingw-w64-x86_64-windows-default-manifest-6.4-4 mingw-w64-x86_64-winpthreads-git-12.0.0.r509.g079e6092b-1 mingw-w64-x86_64-zlib-1.3.1-1 mingw-w64-x86_64-zstd-1.5.7-1 mingw-w64-x86_64-gcc-14.2.0-2 - - Total Download Size: 65.78 MiB - Total Installed Size: 518.69 MiB - - :: Proceed with installation? [Y/n] - :: Retrieving packages... - mingw-w64-x86_64-gcc-14.2.0-2-any downloading... - mingw-w64-x86_64-headers-git-12.0.0.r509.g079e6092b-1-any downloading... - mingw-w64-x86_64-binutils-2.44-1-any downloading... - mingw-w64-x86_64-crt-git-12.0.0.r509.g079e6092b-1-any downloading... - mingw-w64-x86_64-isl-0.27-1-any downloading... - mingw-w64-x86_64-gcc-libs-14.2.0-2-any downloading... - mingw-w64-x86_64-libiconv-1.18-1-any downloading... - mingw-w64-x86_64-zstd-1.5.7-1-any downloading... - mingw-w64-x86_64-gmp-6.3.0-2-any downloading... - mingw-w64-x86_64-mpfr-4.2.1-2-any downloading... - mingw-w64-x86_64-gettext-runtime-0.23.1-1-any downloading... - mingw-w64-x86_64-mpc-1.3.1-2-any downloading... - mingw-w64-x86_64-zlib-1.3.1-1-any downloading... - mingw-w64-x86_64-winpthreads-git-12.0.0.r509.g079e6092b-1-any downloading... - mingw-w64-x86_64-libwinpthread-git-12.0.0.r509.g079e6092b-1-any downloading... - mingw-w64-x86_64-windows-default-manifest-6.4-4-any downloading... - checking keyring... - checking package integrity... - loading package files... - checking for file conflicts... - checking available disk space... - :: Processing package changes... - installing mingw-w64-x86_64-libwinpthread-git... - installing mingw-w64-x86_64-gcc-libs... - installing mingw-w64-x86_64-libiconv... - installing mingw-w64-x86_64-gettext-runtime... - installing mingw-w64-x86_64-zlib... - installing mingw-w64-x86_64-zstd... - installing mingw-w64-x86_64-binutils... - installing mingw-w64-x86_64-headers-git... - installing mingw-w64-x86_64-crt-git... - installing mingw-w64-x86_64-gmp... - installing mingw-w64-x86_64-isl... - installing mingw-w64-x86_64-mpfr... - installing mingw-w64-x86_64-mpc... - installing mingw-w64-x86_64-windows-default-manifest... - installing mingw-w64-x86_64-winpthreads-git... - installing mingw-w64-x86_64-gcc... <><> Processing actions <><><><><><><><><><><><><><><><><><><><><><><><><><> 🐫 ∗ installed arch-x86_64.1 ∗ installed base-bigarray.base ∗ installed base-threads.base ∗ installed base-unix.base ∗ installed host-arch-x86_64.1 ∗ installed host-system-mingw.1 ∗ installed msys2-mingw64.1 ⬇ retrieved msys2.0.1.0 (https://opam.ocaml.org/cache) ∗ installed msys2.0.1.0 ∗ installed conf-mingw-w64-gcc-x86_64.1 ⬇ retrieved flexdll.0.44 (https://opam.ocaml.org/cache) ∗ installed flexdll.0.44 ∗ installed ocaml-env-mingw64.1 ∗ installed ocaml-options-vanilla.1 ∗ installed system-mingw.1 ⬇ retrieved ocaml-config.3 (2 extra sources) ⬇ retrieved ocaml-config.3 (2 extra sources) ⬇ retrieved ocaml-compiler.5.3.0 (https://opam.ocaml.org/cache) ∗ installed ocaml-compiler.5.3.0 ∗ installed ocaml-base-compiler.5.3.0 ∗ installed ocaml-config.3 ∗ installed ocaml.5.3.0 ∗ installed base-domains.base ∗ installed base-effects.base ∗ installed base-nnp.base Done. # To update the current shell environment, run: (& opam env --switch=default) -split '\r?\n' | ForEach-Object { Invoke-Expression $_ } </code></pre> During initialization, Opam took care of installing a C compiler and various other essential tools into the Msys2 environment at C:\msys64</code>. My next goal is to get Opam to install libao with Msys2. I’m not sure what the correct depexts</code> entry should be for this, so I’ll start with ["libao"] {os = "win32" & os-distribution = "cygwin"}</code>. I updated my custom copy of the conf-ao</code> package and pinned the package with Opam: PS C:\Users\s\conf-ao> opam pin .\conf-ao.opam Fatal error: "rsync": command not found. </code></pre> I guess I need to manually install rsync</code> into my Msys2 environment? To do this, launch an Msys2 terminal by running the msys2.exe</code> program from the Msys2 installation (C:\msys64\msys2.exe</code>). Msys2 uses pacman</code> as its package manager, borrowed from Archlinux: $ pacman -S rsync warning: rsync-3.4.1-1 is up to date -- reinstalling resolving dependencies... looking for conflicting packages... Packages (1) rsync-3.4.1-1 Total Installed Size: 0.67 MiB Net Upgrade Size: 0.00 MiB :: Proceed with installation? [Y/n] n </code></pre> Ok looks like rsync</code> was already installed. Maybe when Opam isn’t managing Cygwin for us we need to to manually update the shell environment to bring various commands into PATH? PS C:\Users\s\conf-ao> (& opam env --switch=default) -split '\r?\n' | ForEach-Object { Invoke-Expression $_ } PS C:\Users\s\conf-ao> opam pin .\conf-ao.opam Fatal error: "rsync": command not found. </code></pre> No such luck. Checking that rsync</code> works as expected: PS C:\Users\s\conf-ao> C:\msys64\usr\bin\rsync --help rsync version 3.4.1 protocol version 32 Copyright (C) 1996-2025 by Andrew Tridgell, Wayne Davison, and others. Web site: https://rsync.samba.org/ ... </code></pre> Maybe I just need to manually add C:\msys64\usr\bin</code> to my PATH. PS C:\Users\s\conf-ao> $env:PATH += ";C:\msys64\usr\bin" PS C:\Users\s\conf-ao> rsync --version rsync version 3.4.1 protocol version 32 Copyright (C) 1996-2025 by Andrew Tridgell, Wayne Davison, and others. Web site: https://rsync.samba.org/ ... </code></pre> And now pinning conf-ao</code> again: PS C:\Users\s\conf-ao> opam pin .\conf-ao.opam [ERROR] Could not retrieve Could not extract archive: Unknown archive type: C:\Users\s\AppData\Local\Temp\opam-4184-d29c4e\conf-ao.opam </code></pre> Which reminds me that I’m not supposed to pin</code> the opam file directly but instead the entire folder which contains it. PS C:\Users\s\conf-ao> opam pin . conf-ao is now pinned to file://C:/Users/s/conf-ao (version 1) The following actions will be performed: === install 3 packages ∗ conf-ao 1 (pinned) ∗ conf-mingw-w64-pkgconf-x86_64 1 [required by conf-pkg-config] ∗ conf-pkg-config 4 [required by conf-ao] Proceed with ∗ 3 installations? [y/n] n [NOTE] Pinning command successful, but your installed packages may be out of sync. </code></pre> That’s good. I’m curious about the conf-mingw-w64-pkgconf-x86_64</code> package. It wasn’t needed when installing depexts</code> with Cygwin, so it’s probably specific to Msys2, which means it can probably give us a hint as to the proper way to specify Msys2-specific depexts</code>, which we’ll need to do for our pinned conf-ao</code> package (I was only guessing how to add its new depexts</code> initially). conf-mingw-w64-pkgconf-x86_64</code> is probably a dependency of conf-pkg-config</code> on Msys2, so I’ll start by looking at conf-pkg-config</code>’s metadata and then look at the metadata for conf-mingw-w64-pkgconf-x86_64</code>. PS C:\Users\s\conf-ao> opam show --raw conf-pkg-config ... depends: [ ("host-arch-x86_64" {os = "win32" & os-distribution = "msys2"} & "conf-mingw-w64-pkgconf-x86_64" {os = "win32" & os-distribution = "msys2"} | "host-arch-x86_32" {os = "win32" & os-distribution = "msys2"} & "conf-mingw-w64-pkgconf-i686" {os = "win32" & os-distribution = "msys2"}) ] ... PS C:\Users\s\conf-ao> opam show --raw conf-mingw-w64-pkgconf-x86_64 ... depexts: ["mingw-w64-x86_64-pkgconf"] {os = "win32" & os-distribution = "msys2"} </code></pre> From this we can learn that when using Msys2 to install depexts</code>, the os-distribution</code> variable evaluates to “msys2” instead of “cygwin”. Also on Msys2 Opam will install the system package mingw-w64-x86_64-pkgconf</code> to install pkg-config</code>/pkgconf</code>. This suggests that the correct depext</code> entry for conf-ao</code> is in fact: ["mingw-w64-x86_64-libao"] {os = "win32" & os-distribution = "msys2"} </code></pre> After updating the local copy of conf-ao</code> with the above depext</code> and re-pinning it I tried installing conf-ao</code> again: PS C:\Users\s\conf-ao> opam install conf-ao <><> Synchronising pinned packages ><><><><><><><><><><><><><><><><><><><><> 🐫 [conf-ao.1] synchronised (no changes) The following actions will be performed: === install 3 packages ∗ conf-ao 1 (pinned) ∗ conf-mingw-w64-pkgconf-x86_64 1 [required by conf-pkg-config] ∗ conf-pkg-config 4 [required by conf-ao] Proceed with ∗ 3 installations? [y/n] y The following system packages will first need to be installed: mingw-w64-x86_64-libao mingw-w64-x86_64-pkgconf <><> Handling external dependencies <><><><><><><><><><><><><><><><><><><><> 🐫 opam believes some required external dependencies are missing. opam can: > 1. Run C:\msys64\usr\bin\pacman.exe to install them (may need root/sudo access) 2. Display the recommended C:\msys64\usr\bin\pacman.exe command and wait while you run it manually (e.g. in another terminal) 3. Continue anyway, and, upon success, permanently register that this external dependency is present, but not detectable 4. Abort the installation [1/2/3/4] 1 + C:\msys64\usr\bin\pacman.exe "-Su" "--noconfirm" "mingw-w64-x86_64-libao" "mingw-w64-x86_64-pkgconf" - :: Starting core system upgrade... - there is nothing to do - :: Starting full system upgrade... - resolving dependencies... - looking for conflicting packages... - - Packages (2) mingw-w64-x86_64-libao-1.2.2-2 mingw-w64-x86_64-pkgconf-1~2.3.0-1 - - Total Download Size: 0.16 MiB - Total Installed Size: 0.77 MiB - - :: Proceed with installation? [Y/n] - :: Retrieving packages... - mingw-w64-x86_64-pkgconf-1~2.3.0-1-any downloading... - mingw-w64-x86_64-libao-1.2.2-2-any downloading... - checking keyring... - checking package integrity... - loading package files... - checking for file conflicts... - checking available disk space... - :: Processing package changes... - installing mingw-w64-x86_64-libao... - installing mingw-w64-x86_64-pkgconf... <><> Processing actions <><><><><><><><><><><><><><><><><><><><><><><><><><> 🐫 ∗ installed conf-mingw-w64-pkgconf-x86_64.1 ∗ installed conf-pkg-config.4 ∗ installed conf-ao.1 Done. </code></pre> Success! And the fact that conf-ao</code> installed successfully meant that conf-ao</code>’s build command which uses pkgconf</code> to check whether the ao</code> library is visible also ran successfully, so we’re hopefully in a good place to link against ao</code> when building llama</code>, which will be the next step. Making Noise</a></h2> Let’s try building and running an example from the llama</code> synthesizer library. Get the code: PS C:\Users\s> git clone git@github.com:gridbugs/llama Cloning into 'llama'... ... Resolving deltas: 100% (961/961), done. PS C:\Users\s> cd .\llama\ </code></pre> Since an old version of the packages in this repo are already published to Opam, we need to pin them with Opam so the local versions are used and not the released versions. PS C:\Users\s\llama> opam pin . This will pin the following packages: llama, llama_core, llama_interactive, llama_midi, llama_tests. Continue? [y/n] y llama is now pinned to git+file://C:/Users/s/llama#main (version 0.1.0) llama_core is now pinned to git+file://C:/Users/s/llama#main (version 0.1.0) llama_interactive is now pinned to git+file://C:/Users/s/llama#main (version 0.1.0) llama_midi is now pinned to git+file://C:/Users/s/llama#main (version 0.1.0) Package llama_tests does not exist, create as a NEW package? [y/n] y llama_tests is now pinned to git+file://C:/Users/s/llama#main (version dev) [ERROR] Package conflict! * Missing dependency: - llama_tests → llama_midi >= dev no matching version [NOTE] Pinning command successful, but your installed packages may be out of sync. </code></pre> That error is because the llama_tests</code> library is unreleased while all the other packages are released. Opam phones home while pinning packages to work out which versions to pin (it uses the latest released version of each released package and “dev” for unreleased packages from the look of things). That’s not ideal here though because the unreleased llama_tests</code> package is looking for a version of llama_midi</code> of its same version and failing to find it because the unreleased llama_tests</code> is version “dev” while llama_midi</code> is version “0.1.0”. I think we can work around this by forcing Opam to pin all the packages at version “dev”: PS C:\Users\s\llama> opam pin . --with-version=dev This will pin the following packages: llama, llama_core, llama_interactive, llama_midi, llama_tests. Continue? [y/n] y [NOTE] Package llama is currently pinned to git+file://C:/Users/s/llama#main (version 0.1.0). llama is now pinned to git+file://C:/Users/s/llama#main (version dev) [NOTE] Package llama_core is currently pinned to git+file://C:/Users/s/llama#main (version 0.1.0). llama_core is now pinned to git+file://C:/Users/s/llama#main (version dev) [NOTE] Package llama_interactive is currently pinned to git+file://C:/Users/s/llama#main (version 0.1.0). llama_interactive is now pinned to git+file://C:/Users/s/llama#main (version dev) [NOTE] Package llama_midi is currently pinned to git+file://C:/Users/s/llama#main (version 0.1.0). llama_midi is now pinned to git+file://C:/Users/s/llama#main (version dev) [NOTE] Package llama_tests is already pinned to git+file://C:/Users/s/llama#main (version dev). llama_tests is now pinned to git+file://C:/Users/s/llama#main (version dev) The following actions will be performed: === install 44 packages ∗ ao 0.2.4 [required by llama] ∗ base v0.17.2 [required by ppx_inline_test] ∗ bigarray-compat 1.1.0 [required by ctypes] ∗ conf-libffi 2.0.0 [required by ctypes-foreign] ... Proceed with ∗ 44 installations? [y/n] n [NOTE] Pinning command successful, but your installed packages may be out of sync. </code></pre> Just checking that we now don’t have 2 pins for each released package (“0.1.0” and “dev”) from the two different runs of opam pin</code>: PS C:\Users\s\llama> opam pin list conf-ao.1 rsync file://C:/Users/s/conf-ao llama.dev (uninstalled) git git+file://C:/Users/s/llama#main llama_core.dev (uninstalled) git git+file://C:/Users/s/llama#main llama_interactive.dev (uninstalled) git git+file://C:/Users/s/llama#main llama_midi.dev (uninstalled) git git+file://C:/Users/s/llama#main llama_tests.dev (uninstalled) git git+file://C:/Users/s/llama#main </code></pre> Looks good, and also we can see that our custom conf-ao</code> is there which is expected. One potential issue is that the llama</code> packages are fetched with git</code> rather than rsync</code>, which might bite us later if we modify the local files in the llama</code> project without committing the results. We can avoid this by not installing any of these local packages with Opam, and instead just installing their dependencies and then building the project with Dune. Install the deps: PS C:\Users\s\llama> opam install . --deps-only [llama.dev] synchronised (no changes) [llama_core.dev] synchronised (no changes) [llama_interactive.dev] synchronised (no changes) [llama_midi.dev] synchronised (no changes) [llama_tests.dev] synchronised (no changes) The following actions will be performed: === install 39 packages ∗ ao 0.2.4 [required by llama] ∗ base v0.17.2 [required by ppx_inline_test] ∗ bigarray-compat 1.1.0 [required by ctypes] ∗ conf-libffi 2.0.0 [required by ctypes-foreign] ∗ conf-mingw-w64-libffi-x86_64 1 [required by conf-libffi] ∗ conf-mingw-w64-sdl2-x86_64 1 [required by conf-sdl2] ∗ conf-sdl2 1 [required by tsdl] ∗ csexp 1.5.2 [required by dune-configurator] ∗ ctypes 0.23.0 [required by tsdl] ∗ ctypes-foreign 0.23.0 [required by tsdl] ∗ dune 3.19.0 [required by llama_midi, llama_core, llama, etc.] ∗ dune-configurator 3.19.0 [required by ao] ∗ integers 0.7.0 [required by ctypes] ∗ jane-street-headers v0.17.0 [required by time_now] ∗ jst-config v0.17.0 [required by time_now] ∗ ocaml-compiler-libs v0.17.0 [required by ppxlib] ∗ ocaml_intrinsics_kernel v0.17.1 [required by base] ∗ ocamlbuild 0.16.1 [required by tsdl] ∗ ocamlfind 1.9.8 [required by tsdl] ∗ ppx_assert v0.17.0 [required by jst-config] ∗ ppx_base v0.17.0 [required by time_now] ∗ ppx_cold v0.17.0 [required by ppx_base] ∗ ppx_compare v0.17.0 [required by ppx_base] ∗ ppx_derivers 1.2.1 [required by ppxlib] ∗ ppx_enumerate v0.17.0 [required by ppx_base] ∗ ppx_globalize v0.17.0 [required by ppx_base] ∗ ppx_hash v0.17.0 [required by ppx_base] ∗ ppx_here v0.17.0 [required by ppx_assert] ∗ ppx_inline_test v0.17.0 [required by llama_tests] ∗ ppx_optcomp v0.17.0 [required by time_now] ∗ ppx_sexp_conv v0.17.0 [required by ppx_base] ∗ ppxlib 0.35.0 [required by ppx_inline_test] ∗ ppxlib_jane v0.17.2 [required by ppx_globalize, ppx_enumerate, ppx_hash] ∗ sexplib0 v0.17.0 [required by base, ppxlib] ∗ stdio v0.17.0 [required by ppx_optcomp] ∗ stdlib-shims 0.3.0 [required by ppxlib] ∗ time_now v0.17.0 [required by ppx_inline_test] ∗ topkg 1.0.8 [required by tsdl] ∗ tsdl 1.1.0 [required by llama_interactive] Proceed with ∗ 39 installations? [y/n] y The following system packages will first need to be installed: mingw-w64-x86_64-libffi mingw-w64-x86_64-SDL2 ... </code></pre> Note the additional depexts mingw-w64-x86_64-libffi</code> and mingw-w64-x86_64-SDL2</code>. Based on their names these appear to be packages in the Msys2 repo. It’s great that these packages don’t seem to require the manual intervention needed for libao</code>. While my project’s dependencies install, let’s investigate how one of these packages works: PS C:\Users\s> opam show conf-sdl2 ... depends "conf-pkg-config" {build} ("host-arch-x86_32" {os = "win32" & os-distribution != "cygwinports"} & "conf-mingw-w64-sdl2-i686" {os = "win32" & os-distribution != "cygwinports"} | "host-arch-x86_64" {os = "win32" & os-distribution != "cygwinports"} & "conf-mingw-w64-sdl2-x86_64" {os = "win32" & os-distribution != "cygwinports"}) ... </code></pre> Similar to conf-pkg-config</code>, we see the dependency on an additional conf-mingw-w64-*</code> metapackage under some conditions. Here though it’s os-distribution != "cygwinports"</code> rather than os-distribution = "msys2"</code> which makes me wonder if this would cause a problem on a regular Cygwin installation, where os-distribution = "cygwin"</code>. That would cause the os-distribution != "cygwinports"</code> to be true which seems to select conf-mingw-w64-*</code> packages, but my intuition is that those packages should only be selected on Msys2. There’s too much else going on to also investigate that now and maybe my hunch is wrong anyway. There’s a new problem: llama</code>’s dependencies failed to install: #=== ERROR while compiling topkg.1.0.8 ========================================# # context 2.3.0 | win32/x86_64 | ocaml.5.3.0 | https://opam.ocaml.org#11859fd62a66b5e319a415e807797407068a7c13 # path ~\AppData\Local\opam\default\.opam-switch\build\topkg.1.0.8 # command ~\AppData\Local\opam\default\bin\ocaml.exe pkg/pkg.ml build --pkg-name topkg --dev-pkg false # exit-code 125 # env-file ~\AppData\Local\opam\log\topkg-18684-d088ec.env # output-file ~\AppData\Local\opam\log\topkg-18684-d088ec.out ### output ### # Exception: Fl_package_base.No_such_package ("findlib", ""). <><> Error report <><><><><><><><><><><><><><><><><><><><><><><><><><><><><> 🐫 ┌─ The following actions failed │ λ build topkg 1.0.8 └─ </code></pre> The topkg</a> package is a build tool. According to its description it’s in maintenance mode and should no longer be used. It’s got 165 reverse dependencies so the fact that it doesn’t build on Windows (or maybe just when using Msys2 or maybe just on my machine) is a little concerning however for our purposes here it’s only used to build tsdl</code> which is only needed for the interactive components of llama</code>. It would still be nice to get it working but my priority is getting the sound to work, so consider fixing topkg</code> to be a stretch goal. For now, let’s just install the dependencies needed for non-interactive synthesizer demos: PS C:\Users\s\llama> opam install llama --deps-only <><> Synchronising pinned packages ><><><><><><><><><><><><><><><><><><><><> 🐫 [llama.dev] synchronised (no changes) The following actions will be performed: === install 2 packages ∗ llama_core dev (pinned) [required by llama] ∗ llama_midi dev (pinned) [required by llama_core] Proceed with ∗ 2 installations? [y/n] n </code></pre> Good news! All the necessary dependencies were successfully installed in the previous step. Those two deps are local packages in this project so we don’t need to install them with Opam. In theory we should now have everything we need to run an example: </iframe> Honestly that was easier than I thought it would be. I’m really happy that I didn’t need to manually install libao and that Msys2/Opam could take care of installing it and all the other system dependencies needed to build the synth library and to access the sound card. Most of what went wrong during this process could conceivably be called “user error” though the fact that I have 5 years of OCaml programming behind me and still hit some pretty major footguns with Opam maybe suggests some aspects of its UX could be improved. Still some things were actually broken: conf-ao</code> is hardcoded to run pkg-config</code> despite the executable being named pkgconf</code> in some cases, and has no depext for Msys2. The workaround was to pin conf-ao</code> and fix its problems in a local copy of the package.</li> Opam couldn’t find the rsync</code> executable in the Msys2 environment despite being configured to use an Msys2 environment where rsync</code> was installed. The workaround was to manually add C:\msys64\usr\bin</code> to PATH.</li> topkg</code> failed to build. The workaround was to only use the non-interactive components of my project, as topkg</code> is only necessary to compile the SDL bindings which are only needed for interactive synthesizer features.</li> </ul> The parts of Opam’s UX that I evidently still struggle with relate to working with local packages and pins. Looking back at the “user errors” in this post, a couple of times I tried to pin an opam file led to bizarre errors ( Unknown archive type: C:\Users\s\AppData\Local\Temp\opam-4184-d29c4e\conf-ao.opam</code>) and unexpected results (recursively copying my home directory inside itself until I told it to stop). Opam pins are associated with package sources in the form of a directory, git repo, or archive file - not with opam files themselves. What’s confusing when working with packages like conf-ao</code> is that these packages don’t have sources. They are metapackages that just exist to collect some dependencies on other Opam packages or external dependencies, but they have no source code or other files to fetch during installation. I’ve learnt that the correct thing to do is put the opam file I want to pin inside a directory and then pin that directory. The other pinning-related mistake I made was pinning a project containing multiple packages where some but not all of the packages had been released. This led to the non-released packages being pinned at version “dev” while the released packages are pinned to the latest released version of those packages. If the unreleased package depends on a released package, chances are it won’t be able to resolve the dependency because it will try to find a version of the released package with version “dev”. I’ve learnt that for such projects one must run opam pin . --with-version=dev</code>. Possibly that should be the default behaviour or at least Opam should warn when some but not all of the packages in a project are released. I’ve complained about this exact behaviour before</a> but I still make this mistake all the time. I have gotten used to Opam’s quirks and am no longer too phased when things go wrong. And on Windows in particular I had quite low expectations of the OCaml ecosystem since it’s historically been infamously hard to get working. This is why I’m pleasantly surprised it was this easy to get generated audio playing on Windows with OCaml, despite spending over a day on it at this point. The fact that Opam can be installed through WinGet now, and that it takes care of setting up all the external dependencies with Msys2 (or Cygwin) for you during initialization is very slick. It’s definitely come a long way since the last time I tried to use OCaml on Windows in earnest. That said many of the problems I had with Opam in this post were not Windows-related. The problems with pinning are things I had encountered before on Unix so I could recognize them and employ workarounds. I’ve adopted a defensive approach to working with Opam where I expect the unexpected and often explicitly verify that it did what I want such as always running opam pin list</code> after opam pin</code> and using opam show --raw</code> to check that pinning a package has taken effect if I’m changing a pinned package’s metadata. I don’t believe “user error” is an apt term to use here. The error is not with the user it’s with the usability of the tool. Stretch Goal: Fixing topkg</a></h2> I set aside 2 days to get llama</code> working on Windows and it’s only been a day and a half, so let’s see if we can’t get topkg</code> to build and then run the graphical interactive synthesizer demos which that would enable. We’ll start by grabbing the source code for topkg. Opam has a handy feature for doing just this: PS C:\Users\s> opam source topkg Successfully extracted to C:\Users\s\topkg.1.0.8 PS C:\Users\s> cd .\topkg.1.0.8\ </code></pre> Now pin topkg</code> to the local version so we can tweak things locally and test out how they affect building topkg</code> as a dependency: PS C:\Users\s\topkg.1.0.8> opam pin . This will pin the following packages: topkg-care, topkg. Continue? [y/n] y topkg-care is now pinned to file://C:/Users/s/topkg.1.0.8 (version 1.0.8) topkg is now pinned to file://C:/Users/s/topkg.1.0.8 (version 1.0.8) The following actions will be performed: === remove 6 packages ⊘ base-domains base [conflicts with ocaml] ⊘ base-effects base [conflicts with ocaml] ⊘ base-nnp base [uses base-domains] ⊘ ocaml-compiler 5.3.0 ⊘ ocaml_intrinsics_kernel v0.17.1 [conflicts with ocaml] ⊘ ppxlib_jane v0.17.2 [conflicts with ocaml] === downgrade 20 packages ↘ base v0.17.2 to v0.16.4 [uses ocaml] ↘ jane-street-headers v0.17.0 to v0.16.0 [uses ocaml] ↘ jst-config v0.17.0 to v0.16.0 [uses ocaml] ↘ ocaml 5.3.0 to 4.14.2 [required by topkg, topkg-care] ↘ ocaml-base-compiler 5.3.0 to 4.14.2 [required by ocaml] ↘ ocaml-compiler-libs v0.17.0 to v0.12.4 [uses ocaml] ↘ ppx_assert v0.17.0 to v0.16.0 [uses ocaml] ↘ ppx_base v0.17.0 to v0.16.0 [uses ocaml] ↘ ppx_cold v0.17.0 to v0.16.0 [uses ocaml] ↘ ppx_compare v0.17.0 to v0.16.0 [uses ocaml] ↘ ppx_enumerate v0.17.0 to v0.16.0 [uses ocaml] ↘ ppx_globalize v0.17.0 to v0.16.0 [uses ocaml] ↘ ppx_hash v0.17.0 to v0.16.0 [uses ocaml] ↘ ppx_here v0.17.0 to v0.16.0 [uses ocaml] ↘ ppx_inline_test v0.17.0 to v0.16.1 [uses ocaml] ↘ ppx_optcomp v0.17.0 to v0.16.0 [uses ocaml] ↘ ppx_sexp_conv v0.17.0 to v0.16.0 [uses ocaml] ↘ sexplib0 v0.17.0 to v0.16.0 [uses ocaml] ↘ stdio v0.17.0 to v0.16.0 [uses ocaml] ↘ time_now v0.17.0 to v0.16.0 [uses ocaml] ... </code></pre> Opam wants to remove or downgrade lots of packages including the compiler itself. That seems a bit drastic so let’s see if there’s a way to avoid doing that. After all topkg.1.0.8</code> was part of the package solution Opam found when building llama</code>’s dependencies and ocaml.5.3.0</code> was sufficient in that solution. It’s odd that it wouldn’t also be sufficient here. The opam files in topkg</code>’s source archive look like they should be compatible with ocaml.5.3.0</code> so I really have no idea why Opam wanted to downgrade everything. Regardless, we don’t actually need to install topkg</code> while pinning it. It’s pinned now so that should be sufficient for the local copy to be compiled as a dependency of llama</code>. Let’s see if that’s correct: PS C:\Users\s\llama> opam install . --deps-only [llama_core.dev] synchronised (no changes) [llama.dev] synchronised (no changes) [llama_interactive.dev] synchronised (no changes) [llama_midi.dev] synchronised (no changes) [llama_tests.dev] synchronised (no changes) The following actions will be performed: === install 2 packages ∗ topkg 1.0.8 (pinned) [required by tsdl] ∗ tsdl 1.1.0 [required by llama_interactive] Proceed with ∗ 2 installations? [y/n] y <><> Processing actions <><><><><><><><><><><><><><><><><><><><><><><><><><> 🐫 ⬇ retrieved tsdl.1.1.0 (cached) [ERROR] The compilation of topkg.1.0.8 failed at "ocaml pkg/pkg.ml build --pkg-name topkg --dev-pkg true". #=== ERROR while compiling topkg.1.0.8 ========================================# # context 2.3.0 | win32/x86_64 | ocaml.5.3.0 | pinned(file://C:/Users/s/topkg.1.0.8) # path ~\AppData\Local\opam\default\.opam-switch\build\topkg.1.0.8 # command ~\AppData\Local\opam\default\bin\ocaml.exe pkg/pkg.ml build --pkg-name topkg --dev-pkg true # exit-code 125 # env-file ~\AppData\Local\opam\log\topkg-6140-4d0e5a.env # output-file ~\AppData\Local\opam\log\topkg-6140-4d0e5a.out ### output ### # Exception: Fl_package_base.No_such_package ("findlib", ""). <><> Error report <><><><><><><><><><><><><><><><><><><><><><><><><><><><><> 🐫 ┌─ The following actions failed │ λ build topkg 1.0.8 └─ </code></pre> Looks good, especially this line: # context 2.3.0 | win32/x86_64 | ocaml.5.3.0 | pinned(file://C:/Users/s/topkg.1.0.8) </code></pre> To debug this problem it will help to have a command we can run to quickly reproduce it. Running the topkg</code>’s build command, copied from its opam file, causes the same error as we see when installing topkg</code> as a dependency: PS C:\Users\s\topkg.1.0.8> opam exec ocaml -- .\pkg\pkg.ml build --pkg-name topkg --dev-pkg true Exception: Fl_package_base.No_such_package ("findlib", ""). </code></pre> Before digging into the source of topkg</code> too deeply it might pay to verify that findlib is indeed installed: PS C:\Users\s\topkg.1.0.8> cat C:\Users\s\AppData\Local\opam\default\lib\findlib\META # specifications for "findlib": description = "Package manager" requires = "findlib.internal" requires(toploop) += "findlib.top" requires(create_toploop) += "findlib.top" version = "1.9.8" package "internal" ( version = "1.9.8" description = "Package manager" requires = "" archive(byte) = "findlib.cma" archive(native) = "findlib.cmxa" plugin(byte) = "findlib.cma" plugin(native) = "findlib.cmxs" ) package "dynload" ( version = "1.9.8" description = "Package manager dynamic loader" requires = "findlib dynlink" archive(byte) = "findlib_dynload.cma" archive(native) = "findlib_dynload.cmxa" #Even if it strange and discouraged to dynload this package plugin(byte) = "findlib_dynload.cma" plugin(native) = "findlib_dynload.cmxs" linkopts = "-linkall" ) package "top" ( version = "1.9.8" description = "Package manager toplevel support" requires = "findlib.internal" archive(byte) = "findlib_top.cma" archive(native) = "findlib_top.cmxa" ) </code></pre> Ok this suggests that the problem is with topkg</code> itself and not with my environment. I tried installing llama</code>’s dependencies with Opam on Linux and topkg</code> built fine, suggesting that the problem is specific to Windows. A likely hypothesis is that it’s related to differences with how file paths work between the Unix world and Windows, since this is a common point of pain for running OCaml programs on Windows in my experience. The main two differences that tend to cause problems are that the path separator is \</code> on Windows and /</code> on Unix, and that Windows paths begin with C:</code> while :</code> is conventionally used to delimit multiple paths when they appear in strings on Unix systems (Windows tends to use ;</code> for this instead to avoid confusion around the colon in C:</code>). Next step was to instrument topkg</code> with debug printouts to better understand where the error was happening, but pretty quickly I realized that the problem was happening before any code in topkg</code> could run. Here’s a simplified version of pkg/pkg.ml</code> from the topkg</code> package that still exhibits the problem: #!/usr/bin/env ocaml #use "topfind" let () = print_endline "hi" </code></pre> Now I can run: PS C:\Users\s\topkg.1.0.8> opam exec ocaml -- .\pkg\pkg.ml Exception: Fl_package_base.No_such_package ("findlib", ""). </code></pre> And of course removing the #use "topfind"</code> from the top of that file makes the problem go away. Interestingly I can add code before the #use "topfind"</code> line and it still gets executed: #!/usr/bin/env ocaml let () = print_endline "before";; #use "topfind" let () = print_endline "after";; </code></pre> The output is: PS C:\Users\s\topkg.1.0.8> opam exec ocaml -- .\pkg\pkg.ml before Exception: Fl_package_base.No_such_package ("findlib", ""). </code></pre> Searching online I found this issue</a> which mentions the OCAML_TOPLEVEL_PATH</code> variable. On my Windows machine this variable is set to C:\Users\s\AppData\Local\opam\default\lib\toplevel</code>. That path refers to a folder and inside that folder is a file named topfind</code> with some OCaml code in it. I’m not too familiar with the #use</code> directive in OCaml but it seems to behave similarly to #include</code> in C; acting as though the contents of the specified file replaced the occurrence of #use <file></code>. Some of the code in topfind</code> makes calls to the findlib</code> library (part of the ocamlfind</code> package) which is generally concerned with mapping library names to files containing compiled OCaml modules. The ocamlfind</code> package installs a file named findlib.conf</code> containing some metadata about library locations within an Opam switch. On my Windows machine this file was at C:\Users\s\AppData\Local\opam\default\lib\findlib.conf</code> and its contents was: destdir="C:\\Users\\s\\AppData\\Local\\opam\\default\\lib" path="C:\\Users\\s\\AppData\\Local\\opam\\default/lib/ocaml:C:\\Users\\s\\AppData\\Local\\opam\\default\\lib" ocamlc="ocamlc.opt" ocamlopt="ocamlopt.opt" ocamldep="ocamldep.opt" ocamldoc="ocamldoc.opt" </code></pre> The path</code> field looks suspicious, since the paths on Windows begin with C:</code>, but it looks like a colon character is also being used to separate the two paths. Recall that on Windows it’s common to use a semicolon to separate paths, rather than a colon as is typically seen on Unix. As an experiment I manually replaced the colon with a semicolon in findlib.conf</code> and suddenly I could successfully build topkg</code> both on its own and as a dependency for llama</code>: PS C:\Users\s\llama> opam install . --deps-only [llama_core.dev] synchronised (no changes) [llama.dev] synchronised (no changes) [llama_interactive.dev] synchronised (no changes) [llama_midi.dev] synchronised (no changes) [llama_tests.dev] synchronised (no changes) The following actions will be performed: === install 2 packages ∗ topkg 1.0.8 (pinned) [required by tsdl] ∗ tsdl 1.1.0 [required by llama_interactive] Proceed with ∗ 2 installations? [y/n] y <><> Processing actions <><><><><><><><><><><><><><><><><><><><><><><><><><> 🐫 ⬇ retrieved tsdl.1.1.0 (cached) ∗ installed topkg.1.0.8 ∗ installed tsdl.1.1.0 Done. </code></pre> So the problem wasn’t with topkg</code> after all but rather with ocamlfind</code>. The ocamlfind</code> package is a bit old-school, building with a configure</code> script and Makefile</code>. I’m guessing somewhere in there it fails to detect that it’s running on Windows, at least in Msys2 environments, and uses the wrong path delimiter for paths in findlib.conf</code>. With that problem adequately worked around we should finally be able to run a graphical example: PS C:\Users\s\llama> dune exec .\examples\interactive.exe File "examples/dune", line 44, characters 14-25: 44 | (public_name interactive) ^^^^^^^^^^^ C:/msys64/mingw64/bin/../lib/gcc/x86_64-w64-mingw32/14.2.0/../../../../x86_64-w64-mingw32/bin/ld.exe: C:/msys64/mingw64/bin/../lib/libmingw32.a(lib64_libmingw32_a-ucrtexewin.o): in function `wmain': C:/M/B/src/mingw-w64/mingw-w64-crt/crt/crtexewin.c:67:(.text+0xb5): undefined reference to `wWinMain' collect2.exe: error: ld returned 1 exit status ** Fatal error: Error during linking File "caml_startup", line 1: Error: Error during linking (exit code 2) </code></pre> Not quite yet! Fixing the linker error</a></h2> Linker errors like this usually mean that we’re not linking against a certain shared library, in this case whichever shared library would define the symbol wWinMain</code>. I assumed the tsdl</code> library would have taken care of making sure the appropriate linker flags were passed. It works fine on Linux and MacOS but maybe there are some Windows-specific flags it’s leaving out. pkgconf</code> should be able to tell us what flags are necessary to use a certain library. I assume whatever flags are necessary for SDL2 should suffice here: PS C:\Users\s\llama> pkgconf.exe sdl2 --libs -LC:/msys64/mingw64/bin/../lib -lmingw32 -mwindows -lSDL2main -lSDL2 </code></pre> I’ll start by adding these to the library_flags</code> field of the executable</code> stanza of the example I’m trying to run: (executable (public_name interactive) (modules interactive) (package llama_interactive) (libraries llama_interactive keyboard_helper) (link_flags -LC:/msys64/mingw64/bin/../lib -lmingw32 -mwindows -lSDL2main -lSDL2)) </code></pre> Building the example: PS C:\Users\s\llama> dune build .\examples\interactive.exe File "examples/dune", line 44, characters 14-25: 44 | (public_name interactive) ^^^^^^^^^^^ C:\Users\s\AppData\Local\opam\default\bin\ocamlopt.opt.exe: unknown option '-LC:/msys64/mingw64/bin/../lib'. Usage: ocamlopt <options> <files> Try 'ocamlopt --help' for more information. </code></pre> Turns out you can’t pass raw linker flags to the OCaml compiler like that. In the past</a> I’ve had success wrapping the linker flags in -cclib "<flags>"</code> so I tried that: (link_flags -cclib "-LC:/msys64/mingw64/bin/../lib -lmingw32 -mwindows -lSDL2main -lSDL2") </code></pre> And the error message changed which is often a sign of progress: PS C:\Users\s\llama> dune build .\examples\interactive.exe File "examples/dune", line 44, characters 14-25: 44 | (public_name interactive) ^^^^^^^^^^^ flexlink: unknown option '-mwindows'. FlexDLL version 0.44 Usage: flexlink -o <result.dll/exe> file1.obj file2.obj ... -- <extra linker arguments> -o Choose the name of the output file -exe Link the main program as an exe file -maindll Link the main program as a dll file -noflexdllobj Do not add the Flexdll runtime object (for exe) -noentry Do not use the Flexdll entry point (for dll) -noexport Do not export any symbol -norelrelocs Ensure that no relative relocation is generated -base Specify base address (Win64 only) -pthread Pass -pthread to the linker -I <dir> Add a directory where to search for files -L <dir> Add a directory where to search for files -l <lib> Library file -chain {msvc|msvc64|cygwin64|mingw|mingw64|gnat|gnat64|ld} Choose which linker to use -use-linker <cmd> Choose an alternative linker to use -use-mt <cmd> Choose an alternative manifest tool to use -x64 (Deprecated) -defaultlib <obj> External object (no export, no import) -save-temps Do not delete intermediate files -implib Do not delete the generated import library -outdef Produce a def file with exported symbols -v Increment verbosity (can be repeated) -show-exports Show exported symbols -show-imports Show imported symbols -dry Show the linker command line, do not actually run it -dump Only dump the content of object files -patch Only patch the target image (to be used with -stack) -nocygpath Do not use cygpath (default for msvc, mingw) -cygpath Use cygpath (default for cygwin) -no-merge-manifest Do not merge the manifest (takes precedence over -merge-manifest) -merge-manifest Merge manifest to the dll or exe (if generated) -real-manifest Use the generated manifest (default behavior) -default-manifest Use the default manifest (default.manifest/default_amd64.manifest) -export <sym> Explicitly export a symbol -noreexport Do not reexport symbols imported from import libraries -where Show the FlexDLL directory -nounderscore Normal symbols are not prefixed with an underscore -nodefaultlibs Do not assume any default library -builtin Use built-in linker to produce a dll -explain Explain why library objects are linked -subsystem <id> Set the subsystem (default: console) -custom-crt Use a custom CRT -stack <int> Set the stack reserve in the resulting image -link <option> Next argument is passed verbatim to the linker -g (Ignored) -D <symbol> (Ignored) -U <symbol> (Ignored) -- Following arguments are passed verbatim to the linker -version Print linker version and FlexDLL directory and exit -vnum Print linker version number and exit -help Display this list of options --help Display this list of options Notes: * The -I, -l and -L options do not need to be separated from their argument. * An option like /linkXXX is an abbrevation for '-link XXX'. * An option like -Wl,-XXX is an abbreviation for '-link -XXX'. * FlexDLL's object files are searched by default in the same directory as flexlink, or in the directory given by the environment variable FLEXDIR if it is defined. * Extra argument can be passed in the environment variable FLEXLINKFLAGS. Homepage: https://github.com/ocaml/flexdll File "caml_startup", line 1: Error: Error during linking (exit code 2) </code></pre> Getting rid of the -mwindows</code> argument just gets us back to the original linker error, so I assume it’s important. Reading more about wMinMain</code> and it looks like I was wrong assuming that we need to pass additional linker flags to tell the linker which shared library to look in. Rather, the linker was looking for wWinMain</code> as the entry point to the program called by the C runtime’s initialization code. I have to define it myself. Perhaps OCaml assumes that the entry point will be named WinMain</code> which seems to be the entry point for Windows C programs that don’t accept unicode arguments whereas wWinMain</code> is used when programs do accept unicode arguments (I think the “w” stands for “wide” as in “wide character” since unicode characters can be wider than a byte). For some reason depending on SDL seems to require that the entry point be wWinMain</code>. I don’t understand why. Following these instructions</a> I defined a custom entry point in some C code. For starters it’s stolen from here</a>: #include <wchar.h> #include <stdio.h> int wWinMain (int argc, wchar_t **argv) { wprintf(L"Hello\n"); return 0; } </code></pre> And in the dune</code> file: (executable (public_name interactive) (modules interactive) (package llama_interactive) (libraries llama_interactive keyboard_helper) (foreign_stubs (language c) (names interactive_win))) </code></pre> Testing it out: PS C:\Users\s\llama> dune exec .\examples\interactive.exe Done: 49% (96/194, 98 left) (jobs: 0)Hello </code></pre> Nice, the linker error is gone. Obviously this just prints “Hello” and exits without actually calling into any OCaml code. Now I just need to change the C code to call into the original OCaml code: #include <wchar.h> #include <stdio.h> #define CAML_INTERNALS #include "caml/misc.h" #include "caml/mlvalues.h" #include "caml/sys.h" #include "caml/callback.h" int wWinMain (int argc, wchar_t **argv) { caml_main(argv); caml_do_exit(0); return 0; } </code></pre> But then when I ran the example nothing happened. Adding print statements to the OCaml code didn’t have any effect, and it looks like the program is exiting somewhere inside caml_main</code> with no error message. Powershell provides exit codes of programs in the $LastExitCode</code> variable: PS C:\Users\s\llama> dune exec .\examples\interactive.exe Done: 100% (194/194, 0 left) (jobs: 0) PS C:\Users\s\llama> $LastExitCode -1073741819 </code></pre> Converting to a 32-bit unsigned int assuming 2’s complement this is 0xC0000005</code> which corresponds to an “Access Violation” which is similar to a segmentation fault in the Unix world, so probably I’m doing something wrong with pointers. For inspiration I took a look at the real OCaml main</code> function defined here</a>. There’s some Windows-specific parts that I was missing which I added. I also realized I was using the wrong type for my wWinMain</code> function so I changed its arguments based on some Microsoft documentation I found. This meant I needed to convert the Windows way of representing command-line arguments into the Unix-style argv</code> which OCaml presumably expects. I was running out of time so instead I just generated a fake value for argv</code>. Here’s the C program I ended up with: #include <wchar.h> #include <stdio.h> #define CAML_INTERNALS #include "caml/misc.h" #include "caml/mlvalues.h" #include "caml/sys.h" #include "caml/osdeps.h" #include "caml/callback.h" #include <windows.h> int WINAPI wWinMain(HINSTANCE hInstance, HINSTANCE hPrevInstance, PWSTR pCmdLine, int nCmdShow) { // fake argv for now since I don't know how to convert windows arguments to argv char_os argv0[] = { (unsigned short int)'x', 0 }; char_os** argv = malloc(sizeof(char_os*) * 2); argv[0] = argv0; argv[1] = NULL; // ocaml probably uses a null terminator for its argv since there's no argc? caml_main(argv); caml_do_exit(0); return 0; } </code></pre> And finally it works! </iframe> Well it mostly works. There’s about a second of input latency which isn’t there when I run it on Linux or MacOS, but at least it can now open a window and get input from the keyboard and mouse. That brings us to the end of the 2-day period I’ve allocated for working on this project. Clearly llama</code> is not ready for use in “production” on Windows but at least I now know that it’s technically possible to make it work. All the problems I worked around the past 2 days are not problems with llama</code> itself but various other packages in the OCaml ecosystem (at least conf-ao</code> calling the wrong pkg-config</code> executable and missing Msys2 depexts</code> and ocamlfind</code> using the wrong path delimiters on Windows). I’ll gradually work on upstreaming fixes to these problems but in the meantime I’ll be playing my synthesizer on Unix machines only.

gridbugs

7 Day Roguelike 2026: Day 7

7 Day Roguelike 2026: Day 6

7 Day Roguelike 2026: Day 5

7 Day Roguelike 2026: Day 4

7 Day Roguelike 2026: Day 3

7 Day Roguelike 2026: Day 2

7 Day Roguelike 2026: Day 1

Dial-Up over VoIP with a Commodore Modem from 1985

Restoring my Childhood Family Computer Part 4: Emulation

Porting my Toy OCaml Build System to Windows

Alice the Caml

Fixing my Old OS Assignment with Machine Code Hacks

Sound on OCaml on Windows

Scope Creep

7 Day Roguelike 2025: Success!

7 Day Roguelike 2025: Putting it all together

7 Day Roguelike 2025: Map, Pickups

7 Day Roguelike 2025: Text, Item Labels, Central Hub

7 Day Roguelike 2025: Collision Detection and Enemies

7 Day Roguelike 2025: Oscillographics

7 Day Roguelike 2025: Vector 3D Renderer

Every Game I Made Since 2019 had a Lighting Bug

Setting up WinGet for the First Time

Restoring my Childhood Family Computer Part 3: Chime

Restoring my Childhood Family Computer Part 2: Wasps!

Restoring my Childhood Family Computer Part 1: Rust

Frustrating Interactions with the OCaml Ecosystem while developing a Synthesizer Library

Electric Organ

7 Day Roguelike 2024: Shops, Organs, Environment Effects, Boss

7 Day Roguelike 2024: Applying Items, Equipment

7 Day Roguelike 2024: Items

7 Day Roguelike 2024: Ranged Combat, Sound Effects, Message Log

7 Day Roguelike 2024: Title, Pathfinding, UI

7 Day Roguelike 2024: Animation, Music, Level Switching

7 Day Roguelike 2024: Procgen, Graphics

Component Pinouts and Notes

Programming an Arduino the Hard Way

Chargrid SDL Frontend

7 Day Roguelike 2023: Mechanics, Content, Playtesting

Boat Journey

7 Day Roguelike 2023: Passengers, Art

7 Day Roguelike 2023: UI, Night, Loss, Menus

7 Day Roguelike 2023: Even More Procedural Generation!

7 Day Roguelike 2023: More Procedural Generation

7 Day Roguelike 2023: Procedural Generation

7 Day Roguelike 2023: Bootstrapping, Boat Gameplay, Vision

Playing sound on the NES by directly setting its DMC output

Demystifying Floating Points

If you use a custom linker script, _start might not be your entry point

Rain Forest

7 Day Roguelike 2022: Complete

7 Day Roguelike 2022: Interactions

7 Day Roguelike 2022: Motivation

7 Day Roguelike 2022: Time

7 Day Roguelike 2022: Content

7 Day Roguelike 2022: Atmosphere

7 Day Roguelike 2022: Bootstrapping

Reverse-Engineering NES Tetris to add Hard Drop