Skip to main content

​
Build Commands

Aurora OS uses a Makefile-based build system with multiple targets: 
make build

​
Build Process

1

Build Rust Components

The kernel includes a Rust-based capability system that must be built first:
# Automatic (included in make build)
make rust-caps

# Manual build
cd rust/caps
cargo build --release --target x86_64-unknown-none
This produces libaurora_caps.a which is statically linked into the kernel.
The Rust code is no_std and targets the bare-metal x86_64-unknown-none platform.
2

Compile C Sources

The kernel C code is compiled with freestanding flags:
# Compiler: x86_64-elf-gcc
# Flags:
#   -ffreestanding    No standard library
#   -nostdlib         No libc or crtX
#   -mno-red-zone     Required for interrupt handlers
#   -mcmodel=kernel   Kernel code model (top 2 GiB)
#   -fstack-protector-strong  Stack protection
All .c files in kernel/src/ are compiled to object files in dist/obj/.
3

Assemble Sources

Assembly files (.S) are assembled using GAS syntax:
# Architecture-specific assembly
# - kernel/arch/x86_64/boot.S
# - kernel/arch/x86_64/interrupts.S
4

Link Kernel ELF

All object files and the Rust library are linked using a custom linker script:
x86_64-elf-ld -T kernel/kernel.ld -o dist/aurora-kernel.elf \
  dist/obj/**/*.o rust/caps/target/x86_64-unknown-none/release/libaurora_caps.a \
  --no-undefined
The --no-undefined flag ensures all symbols are resolved at link time.

​
Creating Bootable ISOs

The make iso target creates a bootable ISO image using the Limine bootloader: 
make iso

​
ISO Build Process

1

Build Kernel

Automatically runs make build if the kernel hasn’t been built yet.
2

Prepare ISO Directory

mkdir -p dist/iso/boot/limine
cp dist/aurora-kernel.elf dist/iso/boot/
cp bootloader/legacy/limine.cfg dist/iso/boot/limine/
3

Create ISO Image

xorriso -as mkisofs \
  -b boot/limine/limine-bios-cd.bin \
  -no-emul-boot -boot-load-size 4 -boot-info-table \
  --efi-boot boot/limine/limine-uefi-cd.bin \
  -efi-boot-part --efi-boot-image \
  -o dist/aurora-os.iso dist/iso
This creates a hybrid ISO that boots on both BIOS and UEFI systems.
The resulting ISO is located at dist/aurora-os.iso and can be burned to USB or CD.

​
Running in QEMU

make run
This boots the ISO in QEMU with:
  • 128 MB RAM
  • Serial output to stdio
  • SDL display window
  • No automatic reboot on crash
qemu-system-x86_64 \
  -cdrom dist/aurora-os.iso \
  -m 128M \
  -serial stdio \
  -display sdl \
  -no-reboot

​
Build Configuration

​
Architecture Selection

# Default: x86_64
make build ARCH=x86_64

# Future: ARM64 support
make build ARCH=aarch64

​
Compiler Overrides

# Use system GCC instead of cross-compiler
make build CC=gcc AS_GAS=gcc LD=ld OBJCOPY=objcopy

# Use Clang
make build CC=clang LD=ld.lld
Using system compilers may produce incompatible binaries. The cross-compiler (x86_64-elf-gcc) is recommended.

​
WebAssembly Build

Aurora OS can also compile a kernel bridge for WebAssembly runtime: 
make wasm
This uses Emscripten to compile the kernel bridge: 
emcc wasm-runtime/bridge/kernel-wasm.c -o wasm-runtime/pwa/kernel.js \
  -s EXPORTED_RUNTIME_METHODS='["ccall","cwrap","UTF8ToString"]' \
  -s ALLOW_MEMORY_GROWTH=1 \
  -s INITIAL_MEMORY=16777216 \
  -s MODULARIZE=1 \
  -s EXPORT_NAME='AuroraKernel' \
  -s ENVIRONMENT='web' \
  -s NO_EXIT_RUNTIME=1 \
  -s FILESYSTEM=0 \
  -O2
Output:
  • wasm-runtime/pwa/kernel.js - JavaScript loader
  • wasm-runtime/pwa/kernel.wasm - WebAssembly binary

​
Build Artifacts

After a successful build, the dist/ directory contains: 
dist/
├── aurora-kernel.elf      # Kernel ELF binary
├── aurora-os.iso          # Bootable ISO image
├── obj/                   # Object files
│   └── kernel/
│       ├── src/
│       └── arch/
└── iso/                   # ISO staging directory
    └── boot/

​
Troubleshooting

# Ensure Rust library is built first
make clean
make rust-caps
make build
Check that rust/caps/target/x86_64-unknown-none/release/libaurora_caps.a exists.
# Install QEMU for your platform
sudo apt-get install qemu-system-x86    # Debian/Ubuntu
sudo dnf install qemu-system-x86        # Fedora
sudo pacman -S qemu-full                # Arch
Ensure xorriso and mtools are installed:
sudo apt-get install xorriso mtools grub-pc-bin
If you see undefined reference to __stack_chk_fail:
# The kernel must provide this symbol
# Check kernel/src/security/stack-protector.c

​
Next Steps

Run Tests

Validate your build with the test suite

Contributing

Learn the contribution workflow

Build docs developers (and LLMs) love

Get started for freeTalk to us