Bootstrapping UXN Software Stack

During the last days of 2025 we continued our journey to the strange world of uxn. This time it was the bootstrapping process of its software stack. And it turns out rather surprisingly - the bigger the better!

Most of the software for the uxn ecosystem is programmed in uxn assemble language called uxntal. Currently the uxntal compiler is drifblim which is written in uxntal itself. The bootstrapping process assumes a machine able to run uxn binaries. That is a sane assumption given the fact that most implementations are hosted on other systems and it does not make much sense to bootstrap software if no hardware (albeit virtual) was available to run it.

But how do we get the first binary to run on it? If we can get text data - the source code in uxntal - we can compile any further programs. That means our first binary should be the uxntal drifblim compiler itself. Originally the bootstrapping process assumed the existence of a xxd binary from the vim distribution.

In December, neauoire updated the bootstrapping process by replacing the xxd with uxn program only 70 bytes long. Trouble was, you still needed to get those 70 bytes in a file and most of them were not easily produced on a keyboard.

Now, these 199 characters are much better:

FAFAFXFZFwfaalFBFAAFFZFZXVGfoAAFXFZFFXXfoKgaam&/$AAAFXJgaam&/AFAAFXFFZZDYJF$/FXAKF|Bgaam/AAFXFZFXgBFAYXFEF|BGGoGAFAFXFZDYFEF|B/DAAFX_gBAGYgDAAFXFXAXZEEZXGPgBAAFXFFZZ_]GQFAPGA^GAQFAPgaamFPGAAFXFXFFXXW

If you save these 199 characters in a file, it is a valid uxn program that converts any input stream of hexdump file into a binary file output stream. How is that even possible you may ask. The answer lies in comparing the uxn opcode table with ASCII table. We can observe that the characters in the range 0x20-0x7e can be mostly deemed "safe". With some exceptions. One should probably avoid spaces and backslashes for a start. It is also a good idea to avoid an apostrophe and quotes, should the whole string of characters be an actual string in some programming or shell language.

It turns out that it is impossible to create any LIT instructions and all literal numbers have to be constructed. It also turns out that most of the usable characters operate on the return stack. Therefore we create literals by incrementing zeroes, adding ones and multiplying twos.

DUPr INCr INCr DUPr ADDr DUPr MULr

This program assumes a clean return stack (full of zeroes) and creates a correct 0x10 byte at the top of it. The process is as follows:

• DUPr copy pre-existing zero and push it to the top of the stack
• INCr increment the zero on the top of the stack and make it one
• INCr again to make it two
• DUPr copy the created number two to get two twos
• ADDr add the two twos to get a four
• DUPr copy the created four to get two fours
• MULr multiply the two fours to get a sixteen

The actual source of the aforementioned ASCII program is already in the drifblim repository and you can use it for bootstrapping your systems as well!

Hope you liked another venture into a slightly nostalgic computing and see you next time!