# Quick Start Guide

## Paths and namespaces

Inside ModuOS, paths look like:

- `/` – root of the currently selected mount (boot filesystem by default)
- `$/mnt/vDrive0/` … `$/mnt/vDriveN/` – explicit per-drive mount views
- `$/dev/` – DevFS devices

Examples:

```
# dir /
# dir $/mnt/vDrive0/
# dir $/dev
```

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](https://www.docker.com/products/docker-desktop)
- **QEMU** - [Download here](https://www.qemu.org/download/)
- **Git** - For cloning the repository

## Step 1: Clone the Repository

```bash
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).

```bash
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)

```powershell
# 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)

```cmd
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:

```bash
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

# _
```

## Basic Commands

Try these commands to explore the system:

```bash
# 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](https://sourceforge.net/projects/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

```bash
# 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:

```bash
qemu-system-x86_64 --version
```

### disk.img missing

```
Error: disk.img not found
```

Create the disk image as described in Step 3.

### Build errors

```bash
# 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

- [Shell Commands](Shell-Commands.md) - Learn available commands
- [Applications](Applications.md) - Explore userland programs
- [Games](Games.md) - Play built-in games
- [Building ModuOS](Building-ModuOS.md) - Manual build process
- [Debugging Guide](Debugging-Guide.md) - Debug the kernel

## Manual Build (Advanced)

If you prefer not to use `run.bat`:

```bash
# 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

- **Issues**: [GitHub Issues](https://github.com/NtinosTheGamer2324/ModuOS/issues)
- **OSDev Community**: [wiki.osdev.org](https://wiki.osdev.org)
- **Documentation**: Continue reading the wiki!