MetalOS/docs/BUILD.md

Building MetalOS

Prerequisites

Required Tools

1. GNU Compiler Collection (GCC)

   • Cross-compiler for x86_64-elf target
   • Version 11.0 or later recommended

2. GNU Binutils

   • Cross-binutils for x86_64-elf target
   • Includes ld, as, objcopy, etc.

3. NASM

   • Netwide Assembler for x86_64
   • Version 2.15 or later

4. GNU Make

   • Build automation
   • Version 4.0 or later

5. QEMU (for testing)

   • QEMU system x86_64
   • Version 6.0 or later with UEFI support

6. EDK II OVMF

   • UEFI firmware for QEMU
   • Required for UEFI boot testing

Installing Prerequisites on Ubuntu/Debian

# Install basic build tools
sudo apt-get update
sudo apt-get install -y build-essential nasm qemu-system-x86 ovmf mtools xorriso

# Install cross-compiler prerequisites
sudo apt-get install -y libgmp-dev libmpfr-dev libmpc-dev texinfo

# Note: You may need to build the cross-compiler manually
# See docs/CROSS_COMPILER.md for instructions

Installing Prerequisites on Arch Linux

sudo pacman -S base-devel nasm qemu-full edk2-ovmf mtools xorriso

Installing Prerequisites on macOS

brew install nasm qemu x86_64-elf-gcc x86_64-elf-binutils

Building the Bootloader

# From repository root
cd bootloader
make

This produces bootloader/bootx64.efi - the UEFI bootloader.

Building the Kernel

# From repository root
cd kernel
make

This produces kernel/metalos.bin - the kernel binary.

Creating Bootable Image

# From repository root
make image

This creates build/metalos.img - a bootable disk image containing:

• EFI System Partition with bootloader
• Kernel binary
• Any required data files

Testing in QEMU

Boot MetalOS

make qemu

Boot with Debug Output

make qemu-debug

Boot with GDB Support

# Terminal 1
make qemu-gdb

# Terminal 2
gdb kernel/metalos.bin
(gdb) target remote localhost:1234
(gdb) continue

Testing on Real Hardware

⚠️ WARNING: Testing on real hardware can be risky. Always backup your data.

USB Boot Drive Creation

# Create bootable USB (replace /dev/sdX with your USB device)
sudo dd if=build/metalos.img of=/dev/sdX bs=4M status=progress
sync

Requirements for Hardware Testing

• AMD64 system with UEFI firmware
• Radeon RX 6600 GPU (for full functionality)
• USB drive (1GB or larger)
• Ability to boot from USB in UEFI mode

Build Configuration

Build options can be configured in config.mk:

# Debug build (includes symbols, verbose output)
DEBUG ?= 1

# Optimization level (0, 1, 2, 3, s)
OPT_LEVEL ?= 2

# Target architecture
ARCH ?= x86_64

# Enable specific features
ENABLE_LOGGING ?= 1
ENABLE_SERIAL ?= 1

Clean Builds

# Clean all build artifacts
make clean

# Clean everything including dependencies
make distclean

Troubleshooting

Cross-Compiler Not Found

If you get errors about missing cross-compiler:

1. Check that x86_64-elf-gcc is in your PATH
2. See docs/CROSS_COMPILER.md for building instructions

QEMU UEFI Firmware Missing

# Ubuntu/Debian
sudo apt-get install ovmf

# Arch
sudo pacman -S edk2-ovmf

Build Fails with "Permission Denied"

# Make sure scripts are executable
chmod +x scripts/*.sh

Next Steps

After successful build:

1. Review docs/ARCHITECTURE.md for system design
2. See docs/DEVELOPMENT.md for development workflow
3. Check docs/DEBUGGING.md for debugging techniques