# Building ModuOS

Detailed instructions for building ModuOS from source.

## Prerequisites

### Required Tools

- **Docker Desktop** - Cross-compilation environment
- **QEMU** - x86_64 emulator for testing
- **Git** - Version control
- **Make** - Build automation

### Optional Tools

- **GDB** - Debugging
- **Log Viewer** - COM port log viewing

## Build Environment Setup

### 1. Install Docker Desktop

Download and install from [docker.com](https://www.docker.com/products/docker-desktop)

**Windows**:
```powershell
# Download installer and run
# Or use winget
winget install Docker.DockerDesktop
```

### 2. Install QEMU

Download from [qemu.org](https://www.qemu.org/download/)

**Windows**:
```powershell
# Download installer or use chocolatey
choco install qemu
```

**Linux**:
```bash
sudo apt install qemu-system-x86
```

### 3. Clone Repository

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

## Docker Build Environment

### Build Docker Image

```bash
docker build buildenv -t modu-os
```

**What's Inside**:
- **Base**: Ubuntu with build essentials
- **Cross-compiler**: x86_64-elf-gcc
- **Assembler**: NASM
- **Bootloader**: GRUB tools (grub-mkrescue)
- **ISO tools**: xorriso

**Dockerfile** (`buildenv/Dockerfile`):
```dockerfile
FROM randomdude/gcc-cross-x86_64-elf
RUN apt-get update && apt-get install -y \
    nasm \
    grub-pc-bin \
    grub-common \
    xorriso \
    mtools
```

### Verify Docker Image

```bash
docker images | grep modu-os
```

## Build Process

### Using run.bat (Recommended)

```bash
run.bat
```

This script:
1. Checks Docker is running
2. Builds kernel
3. Creates bootable ISO
4. Launches QEMU
5. Opens log viewers

### Manual Build

**Step 1: Build Kernel**
```bash
docker run --rm -it -v "%cd%":/root/env modu-os make build-AMD64
```

**Step 2: Output Files**
- `build/` - Object files
- `dist/AMD64/mdsys.sqr` - Kernel binary
- `dist/AMD64/kernel.iso` - Bootable ISO

## Makefile Targets

### Main Targets

```bash
# Build for AMD64
make build-AMD64

# Clean build artifacts
make clean

# Rebuild from scratch
make clean build-AMD64
```

### Architecture-Specific

Current architecture: **AMD64** (x86-64)

Future architectures may include ARM64, RISC-V.

## Build Artifacts

### Directory Structure

```
ModuOS/
├── build/              # Intermediate object files
│   ├── kernel/
│   ├── drivers/
│   ├── fs/
│   └── arch/AMD64/
├── dist/               # Final build output
│   └── AMD64/
│       ├── mdsys.sqr   # Kernel binary
│       └── kernel.iso  # Bootable ISO
```

### Kernel Binary

**mdsys.sqr**: ELF64 executable
- Entry point: `long_mode_start` → `kernel_main`
- Load address: 0x100000 (1MB)
- Format: ELF64 (x86-64)

### ISO Structure

```
kernel.iso/
├── boot/
│   └── grub/
│       ├── grub.cfg        # GRUB configuration
│       └── *.pf2           # Font files
├── ModuOS/
│   ├── System64/
│   │   └── mdsys.sqr       # Kernel binary
│   ├── bin/                # System binaries
│   └── Modules/            # Kernel modules (SQRM)
└── Apps/                   # User applications
    ├── cat.sqr
    ├── echo.sqr
    ├── sh.sqr
    └── ...
```

## Compilation Flags

### GCC Flags

```makefile
CFLAGS = -c -I include -ffreestanding
```

**Explanation**:
- `-c`: Compile only, don't link
- `-I include`: Include directory for headers
- `-ffreestanding`: Freestanding environment (no standard library)

### NASM Flags

```makefile
NASMFLAGS = -f elf64
```

**Explanation**:
- `-f elf64`: Output ELF64 format

### Linker Flags

```makefile
LDFLAGS = -n -T targets/AMD64/linker.ld
```

**Explanation**:
- `-n`: Do not page-align sections
- `-T linker.ld`: Use custom linker script

## Linker Script

**File**: `targets/AMD64/linker.ld`

```ld
ENTRY(start)

SECTIONS {
    . = 1M;
    
    .boot : {
        *(.multiboot_header)
    }
    
    .text : {
        *(.text)
    }
    
    .rodata : {
        *(.rodata)
    }
    
    .data : {
        *(.data)
    }
    
    .bss : {
        *(.bss)
    }
}
```

## Userland Build

### Building User Programs

```bash
cd userland
./build.sh
```

**Process**:
1. Compile each `.c` file
2. Link with user linker script
3. Output `.sqr` files to `targets/AMD64/iso/Apps/`

**User Linker Script** (`userland/user.ld`):
```ld
ENTRY(_start)

SECTIONS {
    . = 0x400000;
    
    .text : { *(.text) }
    .rodata : { *(.rodata) }
    .data : { *(.data) }
    .bss : { *(.bss) }
}
```

## Troubleshooting

### Docker Build Fails

**Issue**: Cannot pull base image
```
Error response from daemon: pull access denied
```

**Solution**: Check internet connection, try alternative base image

### Compilation Errors

**Issue**: `x86_64-elf-gcc: command not found`

**Solution**: Docker image not built correctly, rebuild:
```bash
docker build buildenv -t modu-os --no-cache
```

### Linker Errors

**Issue**: Undefined reference to `function`

**Solution**: Check that all source files are included in Makefile

### ISO Creation Fails

**Issue**: `grub-mkrescue: command not found`

**Solution**: GRUB tools not installed in Docker image

## Development Workflow

### 1. Edit Code

Make changes to source files in `src/` or `include/`

### 2. Build

```bash
docker run --rm -it -v "%cd%":/root/env modu-os make build-AMD64
```

### 3. Test

```bash
qemu-system-x86_64 -cdrom dist/AMD64/kernel.iso -m 1024M
```

### 4. Debug

Check `com1.log` for kernel output

### 5. Iterate

Repeat steps 1-4

## Performance Optimization

### Compiler Optimizations

Add to CFLAGS:
```makefile
CFLAGS += -O2          # Optimize for speed
CFLAGS += -Os          # Optimize for size
CFLAGS += -O3          # Maximum optimization
```

### Debug Symbols

```makefile
CFLAGS += -g           # Include debug info
```

## Cross-Compilation

### Why Cross-Compile?

- **Host OS**: Your development machine (Windows/Linux/macOS)
- **Target OS**: ModuOS (freestanding x86-64)

Cannot use host compiler because:
- Host compiler targets host OS
- ModuOS has no standard library
- Need specific ABI and format

### Cross-Compiler Toolchain

**x86_64-elf-gcc**:
- Target: x86-64 ELF format
- No C standard library
- Bare metal code generation

## Next Steps

- [Running and Testing](Running-and-Testing.md) - Test the OS
- [Debugging Guide](Debugging-Guide.md) - Debug techniques
- [Contributing](Contributing.md) - Contribute to development