# Building CubeCactusOS - Quick Guide

## Prerequisites Check

The OS build requires a cross-compiler toolchain. You have three options:

### Option 1: Install Toolchain on macOS (Recommended for development)

```bash
./os/install-toolchain.sh
```

This installs:
- i386-elf-gcc (cross-compiler)
- i386-elf-binutils (assembler, linker)
- QEMU (emulator)
- GRUB (bootloader tools)

### Option 2: Use Docker (Works on any platform)

```bash
./build-docker.sh
```

Builds everything in a container with all tools pre-installed.

### Option 3: Manual Installation

**macOS:**
```bash
brew tap nativeos/i386-elf-toolchain
brew install i386-elf-binutils i386-elf-gcc
brew install qemu xorriso
brew install grub --HEAD
```

**Linux:**
```bash
sudo apt-get install build-essential gcc-multilib g++-multilib
sudo apt-get install qemu-system-x86 grub-pc-bin xorriso
```

## Building the OS

Once toolchain is installed:

```bash
# Build kernel and create bootable ISO
make -f Makefile.os os-image

# Run in QEMU emulator
make -f Makefile.os os-run
```

## Build Targets

- `make -f Makefile.os os-build` - Compile kernel only
- `make -f Makefile.os os-image` - Build + create ISO file
- `make -f Makefile.os os-run` - Build + create ISO + run in QEMU
- `make -f Makefile.os os-clean` - Clean build artifacts

## Output

- Kernel binary: `os/build/cubecactusos.bin`
- ISO image: `os/build/cubecactusos.iso`

## Testing

```bash
# Run in QEMU
qemu-system-i386 -cdrom os/build/cubecactusos.iso -m 512M

# Or use the Makefile target
make -f Makefile.os os-run
```

## Troubleshooting

### "Cross-compiler not found"
Run `./os/install-toolchain.sh` or use Docker build

### "grub-mkrescue: command not found"
```bash
brew install grub --HEAD xorriso
```

### "QEMU not found"
```bash
brew install qemu
```

## Current Status

The build system creates:
1. ✓ Boot loader (Multiboot-compliant)
2. ✓ Kernel with microkernel architecture
3. ✓ System servers (PM, VFS)
4. ✓ Device drivers (TTY)
5. ✓ Bootable ISO image
6. ✓ GRUB configuration

This is a development/educational OS based on MINIX3 architecture.