# Getting Started with CubeCactusOS

This guide will help you set up and build CubeCactusOS based on MINIX3.

## Prerequisites

### Required Tools

1. **Build essentials**:
   ```bash
   # macOS
   xcode-select --install
   brew install gcc make
   
   # Ubuntu/Debian
   sudo apt-get install build-essential
   ```

2. **Cross-compiler** (for x86 target):
   ```bash
   # macOS
   brew install i386-elf-gcc
   
   # Ubuntu/Debian
   sudo apt-get install gcc-multilib g++-multilib
   ```

3. **QEMU** (for testing):
   ```bash
   # macOS
   brew install qemu
   
   # Ubuntu/Debian
   sudo apt-get install qemu-system-x86
   ```

4. **GRUB** (for bootable images):
   ```bash
   # macOS
   brew install grub xorriso
   
   # Ubuntu/Debian
   sudo apt-get install grub-pc-bin xorriso
   ```

## Building MINIX3 from Source

The current CubeCactusOS provides a framework. To build a complete bootable OS:

### Step 1: Clone MINIX3

```bash
cd /Users/agalyaramadoss/repo/CubeCactusCpp
git clone https://github.com/Stichting-MINIX-Research-Foundation/minix.git minix3-source
cd minix3-source
```

### Step 2: Build MINIX3

```bash
# Follow MINIX3 build instructions
./build.sh
```

### Step 3: Customize with CubeCactusOS

Copy your custom kernel and drivers to the MINIX3 source tree:

```bash
cp -r ../os/kernel/* minix/kernel/
cp -r ../os/servers/* minix/servers/
cp -r ../os/drivers/* minix/drivers/
```

### Step 4: Rebuild and Create ISO

```bash
./build.sh
cd releasetools
./mkimage.sh
```

## Quick Development Build

For rapid development and testing of individual components:

```bash
# Build kernel components only
make -f Makefile.os os-build

# This compiles but doesn't create a bootable image
# Useful for syntax checking and development
```

## Running in QEMU

Once you have a bootable ISO:

```bash
qemu-system-i386 \
  -cdrom minix3-source/minix_x86.iso \
  -m 512M \
  -enable-kvm
```

## Development Workflow

1. **Edit code** in `os/kernel/`, `os/servers/`, or `os/drivers/`
2. **Test compilation**: `make -f Makefile.os os-build`
3. **Integrate with MINIX3**: Copy to MINIX3 source tree
4. **Build complete OS**: Run MINIX3 build script
5. **Test in QEMU**: Boot the generated ISO

## Troubleshooting

### "Cannot find compiler"
- Install cross-compiler: `brew install i386-elf-gcc`
- Or use multilib: `sudo apt-get install gcc-multilib`

### "GRUB not found"
- Install GRUB tools: `brew install grub xorriso`

### "QEMU fails to boot"
- Check ISO was created correctly
- Ensure GRUB configuration is valid
- Try with more memory: `-m 1024M`

## Learning Resources

- **MINIX3 Book**: "Operating Systems Design and Implementation" by Tanenbaum
- **OSDev Wiki**: https://wiki.osdev.org/
- **MINIX3 Documentation**: https://wiki.minix3.org/

## Next Steps

1. Study MINIX3 architecture
2. Modify kernel functionality
3. Add custom system calls
4. Create new device drivers
5. Implement new servers

---

For detailed architecture information, see `os/README.md`