uBixOS is now 64-bit. The active development path is macOS + Homebrew cross-toolchain + QEMU,
on both Apple Silicon and Intel Macs. The default architecture is
ARM64 (aarch64); pass TARGET=x86_64 to
build the x86_64 port instead. (32-bit i386 is retired to the releng/2 branch.)
# 1. Install the toolchain (aarch64 is the default target) brew install aarch64-elf-gcc aarch64-elf-binutils bmake qemu mtools # 2. Clone git clone https://github.com/cwolsen7905/UbixOS.git cd UbixOS # 3. Build kernel + userland bmake # 4. Create the bootable disk image bmake image # 5. Run in QEMU (opens a qemu-system-aarch64 'virt' machine) bmake run
QEMU opens a graphical window and boots to the Views desktop. At the login prompt use
root / user. Serial debug output streams to serial.log.
x86_64-elf-gcc x86_64-elf-binutils,
then append TARGET=x86_64 to each step:
bmake TARGET=x86_64 && bmake image TARGET=x86_64 && bmake run TARGET=x86_64.
| PACKAGE | PURPOSE |
|---|---|
aarch64-elf-gcc | ARM64 cross GCC — the default target. The Makefile sets CROSS_PREFIX=aarch64-elf- automatically. |
aarch64-elf-binutils | ARM64 cross binutils (as, ld, ar, objcopy, …) |
x86_64-elf-gcc | x86_64 cross GCC — only for TARGET=x86_64 builds |
x86_64-elf-binutils | x86_64 cross binutils — only for TARGET=x86_64 |
bmake | BSD make — required. GNU make will not work; the Makefiles use BSD-specific syntax. |
qemu | Emulator: qemu-system-aarch64 (default) or qemu-system-x86_64 |
mtools | FAT image tools (mformat, mcopy, mmd) used by the image builder |
aarch64-elf-*
formulae on a very new macOS, either set HOMEBREW_FAKE_MACOS to the newest release
your Homebrew knows, or install the signed Arm cask
brew install --cask gcc-aarch64-embedded and build with
CROSS_PREFIX=aarch64-none-elf-. See BUILDING.md for details.
Every target takes an optional TARGET=aarch64 (default) or TARGET=x86_64,
and an optional SMP=N to boot N cores.
| COMMAND | ACTION |
|---|---|
bmake | Build kernel + full userland |
bmake kernel | Build kernel only (faster when only sys/ changed) |
bmake world | Build userland only (lib/, bin/, sbin/, usr.bin/, libexec/) |
bmake image | Create the bootable disk image (FAT boot + native root partition) |
bmake image-rpi3 | Build the Raspberry Pi 3 microSD image — real-hardware ARM (bring-up in progress) |
bmake run | Launch QEMU; graphical window, serial to serial.log |
bmake run-debug | Headless QEMU, serial to stdout. Press Ctrl-A X to exit. |
bmake clean | Remove all build artifacts |
bmake run (aarch64 default) launches a virt machine with a
virtio disk and NIC:
qemu-system-aarch64 -machine virt,gic-version=2 \ -accel hvf -cpu host -m 512 -smp 1 \ -kernel build/aarch64/boot/kernel \ -serial file:serial.log ...
bmake run TARGET=x86_64 launches the x86_64 port:
qemu-system-x86_64 -m 256 -smp 1 -cpu qemu64,+x2apic \ -kernel build/x86_64/boot/kernel \ -serial file:serial.log ...
Kernel kprintf output streams to COM1 / the serial console.
Watch it live in a second terminal:
tail -f serial.log
login: root password: user
Add -s -S to the QEMU command to enable the GDB stub and halt at startup,
then connect from a second terminal with the matching cross-GDB:
# aarch64 aarch64-elf-gdb build/aarch64/boot/kernel (gdb) target remote localhost:1234 (gdb) continue # x86_64 x86_64-elf-gdb build/x86_64/boot/kernel (gdb) target remote localhost:1234 (gdb) continue
.vscode/launch.json — it automates the QEMU + GDB connection.
For source-level stepping, build with reduced optimization.
brew install bmake export PATH="/opt/homebrew/bin:$PATH" # Apple Silicon # or export PATH="/usr/local/bin:$PATH" # Intel Mac
Homebrew can report "no bottle available" or "unsupported macOS version" on a pre-release OS.
Set HOMEBREW_FAKE_MACOS to your newest known release for the install, or use the
signed Arm cask:
brew install --cask gcc-aarch64-embedded # then build with CROSS_PREFIX=aarch64-none-elf-
serial.log with nothing on screen. Confirm bmake image
finished cleanly and that the kernel binary under build/<arch>/boot/ is non-zero.
The world loads through ld-musl-<arch>.so.1. Ensure
bmake world && bmake image ran successfully for your target and that
build/<arch>/ is populated before creating the image.
Check serial.log — the kernel prints its boot sequence over serial
before anything appears on VGA. A very early crash will show nothing on screen;
verify bmake image completed without errors and that
sys/compile/kernel is non-zero in size.
uBixOS boots to the desktop on ARM64 under QEMU; bringing it up on real silicon is
actively in progress. The Raspberry Pi 3 Model B (BCM2837) is the primary
board — it reuses the same PL011 UART driver as QEMU virt. Build a microSD
image with:
bmake world TARGET=aarch64 bmake image-rpi3 # → build/aarch64/boards/rpi3/rpi3-sd.img
docs/design/raspberry-pi-3b-bringup.md for the
milestone plan and flashing steps.
32-bit i386 — the architecture uBixOS ran on for its first 20+ years — is frozen
on the releng/2 branch. Master is 64-bit only. To build the classic i386 world
(GRUB + qemu-system-i386), check out that branch and follow its build guide.
git checkout releng/2
| PATH | CONTENTS |
|---|---|
build/<arch>/boot/kernel | Final kernel ELF binary (aarch64 / x86_64) |
build/<arch>/bin/ | Userland executables |
build/<arch>/lib/ | Shared and static libraries (incl. ld-musl-<arch>.so.1) |
build/aarch64/boards/rpi3/ | Raspberry Pi 3 microSD image |
| disk image | Bootable QEMU disk image (FAT boot + native root) |
serial.log | QEMU serial output (created by bmake run) |