Getting Started - cupidthecat/cupid-os GitHub Wiki

Getting Started

This guide walks you through building Cupid OS from source and running it in QEMU.

Requirements

Tool Purpose
GNU Make Build system
Python 3 Remaining build coordination, verification and image publication
Checked Cupid Toolchain seeds Compile, assemble, link and inspect normal build outputs
QEMU (qemu-system-i386) x86 emulator for testing
Windows or Linux host Runs its checked native six-tool seed cohort

The paired seeds ship in bootstrap/seeds/. Normal OS, user and hosted toolchain builds do not require GCC, Clang, NASM or a host linker. Those tools remain optional development and comparison tools. QEMU is needed for guest testing. CupidObj constructs the normal image templates; the Python image publisher retains filesystem and replacement checks.

Install Dependencies

Ubuntu / Debian

sudo apt-get install make python3 qemu-system-x86

Arch Linux

sudo pacman -S make python qemu-full

WSL (Windows Subsystem for Linux)

Same as Ubuntu/Debian. For display, ensure an X server (VcXsrv, WSLg) is available for QEMU's graphical output.

Building

git clone --branch bootstrap/cupid-self-hosting https://github.com/cupidthecat/cupid-os.git
cd cupid-os
make

This produces:

  • boot/boot.bin - 2,560-byte bootloader with its second stage
  • kernel/kernel.bin - Flat binary kernel
  • cupidos.img - Bootable IDE HDD image (default 200 MiB) with embedded FAT16 partition

Choose HDD Size

make HDD_MB=100
make HDD_MB=200

Default is HDD_MB=200.

Build Targets

Target Description
make Build the OS image
make clean Remove build artifacts (keeps cupidos.img)
make clean-image Remove only cupidos.img
make distclean Remove build artifacts + cupidos.img
make run Build and run in QEMU (serial to stdout)
make run-log Build and run with serial output saved to debug.log
make sync-demos Copy local demos/*.asm into /home/demos in cupidos.img

Running in QEMU

Basic Boot

make run

Boots into the graphical desktop from HDD (-boot c -hda cupidos.img). Serial output appears in your terminal.

Serial Logging

make run-log

All serial output (debug logs, kernel messages) saved to debug.log.

HDD image and persistent files

cupidos.img contains the bootloader, kernel prefix and a FAT16 partition. The default FAT start is LBA 20480, byte offset 10485760. Cupid OS mounts raw FAT at /disk. Persistent /home files use HomeFS, whose HOMEFS.SYS container is stored on FAT16.

Stage host files

Use the image publisher after building the image:

python3 tools/hostbuild.py stage --image cupidos.img --fat-start-lba 20480 cupid.bmp:/cupid.bmp

On Windows, use the configured Python executable. The staged file is available as /disk/cupid.bmp. A fresh first boot imports staged files into HomeFS; an existing image can copy a new file with cp /disk/cupid.bmp /home/cupid.bmp in the guest. Staging requires no external mcopy utility.

make sync-user builds and stages the three validated ELF examples. See ELF programs for their entry contract and guest commands. If FAT_START_LBA changes, the byte offset is FAT_START_LBA * 512.

First Boot

When cupid-os boots, you'll see:

  1. Bootloader - Loads kernel from HDD LBA sectors to 0x100000, switches to protected mode
  2. Kernel init - IDT, PIC, PIT, keyboard, memory, paging, serial
  3. Desktop - VBE 640×480 32bpp graphical desktop with pastel theme

Live Docs

CupidOS ships a TempleOS-inspired DolDoc-like manual set inside the OS.

Open Notepad, browse to /docs/00INDEX.ctxt, and press F2 to switch between raw source and rendered view.

In rendered view, .ctxt manuals can contain:

  • runnable CupidC code blocks
  • clickable open:, shell:, and repl: links
  • buttons, tree widgets, and inline BMP sprites

The shipped manuals also embed /docs/image.bmp, which is used by the DolDoc examples and widget demos.

Exploring the Shell

Click the Terminal icon on the desktop (or boot in text mode). You'll see:

cupid-os shell
> help

Try these commands to get started:

help              # List all commands
sysinfo           # System information
ls                # List in-memory files
ls /docs          # List embedded manuals
lsdisk            # List files on FAT16 disk
ed hello.cup      # Create a script with the editor
cupid hello.cup   # Run your script

Next Steps