Mu programs build natively either on Linux or on Windows using WSL 2. For Macs and other Unix-like systems, use the (much slower) emulator:

./translate_emulated apps/ex2.mu  # 2-5 minutes to emit code.img

Mu programs can be written for two very different environments:

• At the top-level, Mu programs emit a bootable image that runs without an OS (under emulation; I haven't tested on native hardware yet). There's rudimentary support for some core peripherals: a 1024x768 screen, a keyboard with some key-combinations, a PS/2 mouse that must be polled, a slow ATA disk drive. No hardware acceleration, no virtual memory, no process separation, no multi-tasking, no network. Boot always runs all tests, and only gets to main if all tests pass.

• The top-level is built using tools created under the linux/ sub-directory. This sub-directory contains an entirely separate set of libraries intended for building programs that run with just a Linux kernel, reading from stdin and writing to stdout. The Mu compiler is such a program, at linux/mu.subx. Individual programs typically run tests if given a command-line argument called test.

The largest program built in Mu today is its prototyping environment for writing slow, interpreted programs in a Lisp-based high-level language.

(For more details, see the shell/ directory.)

While I currently focus on programs without an OS, the linux/ sub-directory is fairly ergonomic. There's a couple of dozen example programs to try out there. It is likely to be the option for a network stack in the foreseeable future; I have no idea how to interact on the network without Linux.

Syntax

The entire stack shares certain properties and conventions. Programs consist of functions and functions consist of statements, each performing a single operation. Operands to statements are always variables or constants. You can't perform a + b*c in a single statement; you have to break it up into two. Variables can live in memory or in registers. Registers must be explicitly specified. There are some shared lexical rules. Comments always start with '#'. Numbers are always written in hex. Many terms can have context-dependent metadata attached after '/'.

Here's an example program in Mu:

More resources on Mu:

• Mu Syntax reference

• Library reference. Mu programs can transparently call low-level functions written in SubX.

Here's an example program in SubX:

== code
Entry:
  # ebx = 1
  bb/copy-to-ebx  1/imm32
  # increment ebx
  43/increment-ebx
  # exit(ebx)
  e8/call  syscall_exit/disp32

More resources on SubX:

• SubX syntax reference

• Some starter exercises for learning SubX (labelled hello). Feel free to ping me with any questions.

• The list of x86 opcodes supported in SubX: linux/bootstrap/bootstrap help opcodes.

• Some tips for debugging SubX programs.

Mirrors and Forks

Updates to Mu can be downloaded from the following mirrors: * https://github.com/akkartik/mu * https://repo.or.cz/mu.git * https://codeberg.org/akkartik/mu * https://tildegit.org/akkartik/mu * https://git.tilde.institute/akkartik/mu * https://git.sr.ht/~akkartik/mu

Forks of Mu are encouraged. If you don't like something about this repo, feel free to make a fork. If you show it to me, I'll link to it here. I might even pull features upstream!

• uCISC: a 16-bit processor being designed from scratch by Robert Butler and programmed with a SubX-like syntax.
• subv: experimental SubX-like syntax by s-ol bekic for the RISC-V instruction set.
• mu-x86_64: experimental fork for 64-bit x86 in collaboration with Max Bernstein. It's brought up a few concrete open problems that I don't have good solutions for yet.
• mu-normie: with a more standard build system for the linux/bootstrap/ directory that organizes the repo by header files and compilation units. Stays in sync with this repo.

Desiderata

If you're still reading, here are some more things to check out:

• A slow guided tour of Mu.

• How to get your text editor set up for Mu and SubX programs.

• Some videos demonstrating Mu programs and features.

• A summary of how the Mu compiler translates statements to SubX. Most Mu statements map to a single x86 instruction. (colorized version)

• A prototype live-updating programming environment for a postfix language that I might work on again one day:

sh cd linux ./translate tile/*.mu ./a.elf screen

• Previous prototypes: mu0, mu1.

Credits

Mu builds on many ideas that have come before, especially:

• Peter Naur for articulating the paramount problem of programming: communicating a codebase to others;
• Christopher Alexander and Richard Gabriel for the intellectual tools for reasoning about the higher order design of a codebase;
• David Parnas and others for highlighting the value of separating concerns and stepwise refinement;
• The folklore of debugging by print and the trace facility in many Lisp systems;
• Automated tests for showing the value of developing programs inside an elaborate harness;

On a more tactical level, this project has made progress in a series of bursts as I discovered the following resources. In autobiographical order, with no claims of completeness: - “Bootstrapping a compiler from nothing” by Edmund Grimley-Evans. - StoneKnifeForth by Kragen Sitaker, including a tiny sketch of an ELF loader. - “Creating tiny ELF executables” by Brian Raiter. - Single-page cheatsheet for the x86 ISA by Daniel Plohmann (cached local copy) - Minimal Linux Live for teaching how to create a bootable disk image using the syslinux bootloader. - “Writing a bootloader from scratch” by Nick Blundell. - Wikipedia on BIOS interfaces: Int 10h, Int 13h. - Some tips on programming bootloaders by Michael Petch. - xv6, the port of Unix Version 6 to x86 processors - Some tips on handling keyboard interrupts by Alex Dzyoba and Michael Petch.