Skip to content

Quick Start Guide

Jump to bottom
NtinosTheGamer2324 edited this page Dec 11, 2025 · 2 revisions

Quick Start Guide

Get ModuOS up and running in just a few minutes!

Prerequisites

Before you begin, ensure you have:

  • Windows (Linux/macOS may work with modifications)
  • Docker Desktop - Download here
  • QEMU - Download here
  • Git - For cloning the repository

Step 1: Clone the Repository

git clone https://github.com/NtinosTheGamer2324/ModuOS.git
cd ModuOS

Step 2: Build Docker Environment

ModuOS uses a Docker container with the cross-compilation toolchain (x86_64-elf-gcc, NASM, GRUB tools).

docker build buildenv -t modu-os

This creates a Docker image named modu-os containing:

  • x86_64-elf-gcc: Cross-compiler for x86-64
  • NASM: Netwide Assembler for assembly code
  • GRUB: Bootloader tools
  • xorriso: ISO creation utility

⏱️ Build time: ~5-10 minutes (one-time setup)

Step 3: Create a Disk Image

ModuOS requires a 1GB FAT32-formatted disk image named disk.img in the project root.

Option A: PowerShell (Windows)

# Create 1GB blank file
fsutil file createnew disk.img 1073741824

# Format as FAT32 using Disk Management:
# 1. Open Disk Management (diskmgmt.msc)
# 2. Action > Attach VHD > Select disk.img
# 3. Initialize as MBR
# 4. Create volume and format as FAT32
# 5. Detach VHD

Option B: diskpart (Windows)

diskpart
> select vdisk file="C:\path\to\ModuOS\disk.img"
> create vdisk file="C:\path\to\ModuOS\disk.img" maximum=1024 type=fixed
> attach vdisk
> create partition primary
> format fs=fat32 quick
> assign letter=X
> detach vdisk
> exit

Option C: Third-Party Tools

  • Win32 Disk Imager: Create and format disk images
  • Rufus: Create FAT32 formatted files

⚠️ Important: The run.bat script does NOT create disk.img automatically!

Step 4: Build and Run

Simply execute the batch script:

run.bat

This script will:

  1. ✅ Check if Docker Desktop is running (starts it if needed)
  2. 🔨 Build the kernel inside the Docker container
  3. 📦 Create a bootable ISO with GRUB2
  4. 🚀 Launch QEMU with the kernel ISO and disk image
  5. 📄 Open log viewers for COM1 and COM2 output

What You'll See

Boot Sequence

  1. GRUB bootloader menu
  2. Kernel initialization messages
  3. Hardware detection (PCI, drives, memory)
  4. File system mounting
  5. Shell prompt

Initial Shell

ModuOS v0.1
Type 'help' for available commands

Z:\> _

Basic Commands

Try these commands to explore the system:

# System information
zsfetch

# List files
dir

# Read a file
cat /ModuOS/System64/mdsys.sqr

# Memory test
memtest

# Run the shell
sh

# Launch a game
game

Optional: Log Viewer Setup

To view real-time COM port logs during execution:

  1. Download Log Viewer v1
  2. Place the executable at: vendor/NTSoftware/Log Viewer.exe
  3. The run.bat script will automatically open it

Log files:

  • com1.log: Kernel debug output
  • com2.log: Additional system logs

Troubleshooting

Docker not starting

# Manually start Docker Desktop
"C:\Program Files\Docker\Docker\Docker Desktop.exe"

# Wait 30 seconds, then run run.bat again

QEMU not found

Make sure QEMU is installed and in your PATH:

qemu-system-x86_64 --version

disk.img missing

Error: disk.img not found

Create the disk image as described in Step 3.

Build errors

# Clean build artifacts
docker run --rm -it -v "%cd%":/root/env modu-os make clean

# Rebuild
run.bat

QEMU black screen

  • Press Ctrl+Alt+2 to access QEMU monitor
  • Check com1.log for kernel panic messages
  • Ensure disk.img is properly formatted as FAT32

Next Steps

Manual Build (Advanced)

If you prefer not to use run.bat:

# Build kernel
docker run --rm -it -v "%cd%":/root/env modu-os make clean build-AMD64

# Run in QEMU
qemu-system-x86_64 ^
    -M pc-i440fx-6.2 ^
    -m 1024M ^
    -smp 2 ^
    -serial file:com1.log ^
    -serial file:com2.log ^
    -drive file=dist/AMD64/kernel.iso,format=raw,media=cdrom ^
    -drive id=disk,file=disk.img,if=none,format=raw ^
    -device ahci,id=ahci ^
    -device ide-hd,drive=disk,bus=ahci.0 ^
    -boot d

Getting Help

Clone this wiki locally