Getting started

Getting Started

Requirements

Linux host with:

• gcc, ld, nasm, objcopy — toolchain
• cpio — builds the initrd archive
• grub-mkrescue — builds the bootable ISO
• qemu-system-x86_64 with KVM — runs the result

On Debian/Ubuntu:

sudo apt install build-essential nasm cpio grub-pc-bin \
                 grub-common xorriso qemu-system-x86

Build and run

From the project root:

make clean
make run

make run does the whole chain:

1. Builds the userspace programs (init, test, echo, exy-vfs, console) into build/*.elf.
2. Packages them into build/initrd with tools/mkinitrd.sh (cpio newc).
3. Runs objcopy -I binary on build/init.elf and build/initrd to embed them into the kernel as byte arrays.
4. Links build/exyde-kernel.elf.
5. Wraps it into build/exyde.iso with GRUB.
6. Boots the ISO under QEMU with -serial stdio.

The kernel log appears on stdout. A run is healthy if the last line is idle: entering hlt loop and there is no *** KERNEL PANIC ***.

Individual targets

make                 # build the kernel ELF only
make -C src/userspace # build userspace programs only
make iso             # build the bootable ISO, do not run
make clean           # rm -rf build/

What you should see

A successful run ends with:

userspace: after reaper, pmm free=<N> heap=4460544
userspace test: OK (init spawned, ran, exited)
uaccess test: OK (range bounds, wrap, zero-len, extable)
idle: entering hlt loop

pmm free before and after the userspace phase is the same number. If it is not, the kernel leaked physical pages and the run will panic with userspace test: reaper leaked pages.

Troubleshooting

• cpio: command not found — install cpio.
• grub-mkrescue: command not found — install grub-pc-bin and xorriso.
• QEMU boots but hangs before idle: — look for a panic earlier in the log. The panic message names the failing subsystem.
• -accel kvm fails — either enable KVM in your kernel or replace it with -accel tcg in src/kernel/Makefile (much slower).