Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pastaboy12345/NKLegacy/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks you through cloning the NKLegacy repository, installing the required toolchain, compiling the kernel and NKBootman bootloader, assembling the disk image, and finally booting the whole system inside QEMU. By the end you will see the NT-style boot banner in your terminal and land at an interactive C:\> prompt — all running on bare-metal emulated x86 hardware.
The GRUB ISO path (make run) is the easiest way to test NKLegacy. It avoids any MBR geometry concerns and lets QEMU load the Multiboot ELF directly via GRUB. Use the NKBootman floppy image (make run-bootman) only when you specifically want to test the two-stage bootloader.

​
Prerequisites and build steps

1

Install prerequisites

You need a 32-bit–capable GCC cross toolchain, NASM, GNU ld, GRUB rescue tools, and QEMU.On Debian or Ubuntu:
sudo apt install gcc nasm grub-pc-bin grub-common xorriso qemu-system-x86
Verify the key tools are available:
gcc --version          # must support -m32
nasm --version
ld --version
grub-mkrescue --version
qemu-system-i386 --version
2

Clone and enter the repository

git clone https://github.com/pastaboy12345/NKLegacy.git
cd NKLegacy
3

Build everything

A single top-level target compiles the kernel, assembles both bootloader stages, and produces the floppy disk image:
make all
This runs three sub-targets in order:
Sub-targetWhat it does
kernelCompiles all C sources and assembles boot.asm/isr.asm into ELF objects, then links them with ntoskrnl/linker.ld to produce build/nklegacy.elf (loaded at 0x100000).
bootloaderAssembles boot/stage1/mbr.asm → build/boot/mbr.bin (flat binary, 512 bytes) and boot/stage2/stage2.asm → build/boot/stage2.bin (flat binary).
imageFlattens build/nklegacy.elf to build/nklegacy.bin, creates a 1.44 MB floppy image (build/nklegacy.img), writes the MBR to sector 0, Stage 2 to sectors 1–16, and the kernel binary starting at sector 17.
After a successful build you will have:
build/
├── nklegacy.elf        # Kernel ELF (linked at 0x100000, used by GRUB ISO)
├── nklegacy.bin        # Flat kernel binary (used by NKBootman floppy)
├── boot/
│   ├── mbr.bin         # Stage 1: 512-byte MBR
│   └── stage2.bin      # Stage 2: Protected-mode setup
└── nklegacy.img        # 1.44 MB floppy image (MBR + Stage2 + kernel)
4

Run via GRUB ISO (recommended)

make run
This target first runs make iso, which:
  • Creates build/iso/boot/grub/grub.cfg with a single NKLegacy menu entry using multiboot.
  • Calls grub-mkrescue to produce build/nklegacy.iso.
QEMU is then launched as:
qemu-system-i386 -cdrom build/nklegacy.iso -serial stdio -m 32M
The -serial stdio flag mirrors COM1 output to your terminal. You should see the serial debug log appear immediately before the VGA window opens.
5

Run via NKBootman floppy

To exercise the custom two-stage bootloader instead of GRUB:
make run-bootman
This launches:
qemu-system-i386 -fda build/nklegacy.img -serial stdio -m 32M -boot a
QEMU boots from the 1.44 MB floppy image. The MBR loads Stage 2, which switches to protected mode and jumps to the kernel at 0x100000.
6

Optional: headless serial-only run

If you only want the serial log and no graphical window (useful in CI or SSH sessions):
make run-serial
This uses the GRUB ISO but adds -display none -no-reboot:
qemu-system-i386 -cdrom build/nklegacy.iso -serial stdio -m 32M -display none -no-reboot
All kernel output is written to stdout via COM1.

​
Expected boot output

A successful boot produces the following on the VGA console (and mirrored to serial): 
NKLegacy Kernel v0.1.0 [Build: <date> <time>]
Copyright (c) 2026 William Beauregard. MIT License.
Windows NT-inspired kernel operating system.

  [OK] Global Descriptor Table
  [OK] Interrupt Descriptor Table
  [OK] Programmable Interrupt Controller (8259)
  [OK] Programmable Interval Timer (1000 Hz)
  [OK] PS/2 Keyboard Driver
  [OK] Serial Debug (COM1 @ 115200)

NKLegacy kernel initialized. <N> ticks elapsed.

nklegacy>
After NKFS initialises, the shell takes over and you land at: 
C:\>
Type help and press Enter to list all available commands.

​
Cleaning build artifacts

make clean
This removes the entire build/ directory, including all object files, binaries, and disk images.

Build docs developers (and LLMs) love

Get started for freeTalk to us