Building ModuOS

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

Windows:

# Download installer and run
# Or use winget
winget install Docker.DockerDesktop

2. Install QEMU

Download from qemu.org

Windows:

# Download installer or use chocolatey
choco install qemu

Linux:

sudo apt install qemu-system-x86

3. Clone Repository

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

Docker Build Environment

Build Docker Image

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):

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

docker images | grep modu-os

Build Process

Using run.bat (Recommended)

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

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

# 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

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

NASMFLAGS = -f elf64

Explanation:

• -f elf64: Output ELF64 format

Linker Flags

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

ENTRY(start)

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

Userland Build

Building User Programs

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):

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:

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

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

3. Test

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:

CFLAGS += -O2          # Optimize for speed
CFLAGS += -Os          # Optimize for size
CFLAGS += -O3          # Maximum optimization

Debug Symbols

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 - Test the OS
• Debugging Guide - Debug techniques
• Contributing - Contribute to development