Skip to main content

​
Prerequisites

Aeolos is an x86_64 hobby operating system that requires specific tools for building and testing. You’ll need a Linux environment (or WSL on Windows) with the following dependencies installed.

​
Required Dependencies

sudo apt-get install -y nasm gcc mtools xorriso
  • nasm: Netwide Assembler for x86 assembly code
  • gcc: GNU Compiler Collection for C compilation
  • mtools: Utilities for accessing DOS disks
  • xorriso: Tool for creating ISO 9660 filesystem images

​
Optional Dependencies

For testing and debugging: 
sudo apt-get install -y qemu-system-x86
QEMU with KVM acceleration provides the best performance for testing. Make sure KVM is enabled on your system.

​
Cloning the Repository

Clone Aeolos with its submodules: 
git clone --recursive https://github.com/chocabloc/aeolos.git
cd aeolos
The --recursive flag is important as Aeolos uses git submodules for third-party dependencies like Limine bootloader and SAF filesystem tools.
If you forgot to use --recursive, initialize submodules manually: 
git submodule update --init --recursive

​
Building Aeolos

​
Build Process Overview

The build system is organized into multiple stages:
  1. Kernel compilation - Compiles all C and assembly sources
  2. Symbol generation - Extracts kernel symbols for debugging
  3. Initrd creation - Builds the initial ramdisk using SAF filesystem
  4. ISO generation - Creates a bootable ISO image with Limine bootloader

​
Building the Kernel

Build just the kernel: 
make -C kernel
This compiles all kernel sources with the following flags from kernel/Makefile:21-36: 
CFLAGS = -std=gnu2x \
         -ffreestanding \
         -fno-pic \
         -fno-omit-frame-pointer \
         -fno-stack-protector \
         -mcmodel=kernel \
         -mno-red-zone \
         -mno-80387 \
         -mno-mmx \
         -mno-sse \
         -mno-sse2 \
         -Wall \
         -Wextra \
         -Og \
         -I . \
         -I lib
The -Og flag enables optimizations that don’t interfere with debugging. The -fno-omit-frame-pointer flag ensures stack traces work correctly.

​
Building the Complete ISO

Build the bootable ISO image: 
make
This will:
  1. Build third-party tools (SAF filesystem utilities)
  2. Compile the kernel with symbol table generation
  3. Create the compressed initrd (initrd.saf.gz)
  4. Generate os.iso using the genimg script
The resulting os.iso file can be booted in QEMU or written to physical media.

​
Build Artifacts

After a successful build, you’ll find:
  • kernel/kernel.elf - The kernel executable with debug symbols
  • image/boot/initrd.saf.gz - Compressed initial ramdisk
  • os.iso - Bootable ISO image

​
Running in QEMU

Test Aeolos in QEMU: 
make run
This launches QEMU with these parameters from Makefile:5-10: 
QEMUFLAGS = -m 128 \
            -no-reboot \
            -no-shutdown \
            -smp 4 \
            -cpu host \
            -M accel=kvm:tcg
  • -m 128: Allocate 128MB of RAM
  • -no-reboot -no-shutdown: Halt on kernel panic instead of rebooting
  • -smp 4: Emulate 4 CPU cores for SMP testing
  • -cpu host: Use host CPU features (requires KVM)
  • -M accel=kvm:tcg: Use KVM if available, fallback to TCG emulation

​
Bootloader Configuration

Aeolos uses the Limine bootloader with the Stivale2 protocol. The configuration is in image/boot/limine.cfg: 
:Aeolos

PROTOCOL=stivale2
RESOLUTION=800x600x32
KERNEL_PATH=boot:///boot/kernel.elf
MODULE_PATH=$boot:///boot/initrd.saf.gz
MODULE_STRING=initrd
TIMEOUT=0
  • Boot protocol: Stivale2
  • Default resolution: 800x600x32
  • Kernel: boot/kernel.elf
  • Initrd: boot/initrd.saf.gz

​
Cleaning Build Artifacts

Remove all build artifacts: 
make clean
This removes:
  • All object files (*.o)
  • Kernel executable
  • Generated symbol files
  • Initrd archive
  • Third-party build artifacts

​
Troubleshooting

Install NASM:
sudo apt-get install nasm
If you see KVM-related errors, QEMU will automatically fall back to TCG (slower emulation). To use KVM:
  1. Ensure your CPU supports virtualization
  2. Enable it in BIOS/UEFI
  3. Load the KVM module: sudo modprobe kvm-intel or sudo modprobe kvm-amd
Initialize submodules:
git submodule update --init --recursive
Ensure xorriso is installed:
sudo apt-get install xorriso

​
Next Steps

Debugging

Learn how to debug Aeolos using QEMU and serial output

Contributing

Start contributing to the Aeolos project

Build docs developers (and LLMs) love

Get started for freeTalk to us