Building and Testing Chapp-E

Complete guide to building and testing the Chapp-E Neural OS

Building

Run the build script from the Chapp-E directory:

.\scripts\build_multiboot.ps1

This will:

  1. Assemble all bootloader files (header, main, main64, kernel)
  2. Use WSL's ld to link as ELF64 (required for multiboot)
  3. Output build/chappe.bin

Requirements

  • NASM: For assembling assembly files
  • GCC or Clang: For building the toolchain (compiler and linker)
  • WSL (Windows Subsystem for Linux): For ELF linking (MinGW's ld only supports PE) - Optional if using chappe-ld
  • QEMU: For testing

Building the Toolchain

Chapp-E has its own toolchain for compiling and linking programs:

Build Compiler (chappe-cc)

cd toolchain\compiler
.\build.ps1

This builds the C compiler that generates assembly code from C source files.

Build Linker (chappe-ld)

cd toolchain\linker
.\build.ps1

This builds the linker that combines object files into ELF64 executables.

Using the Toolchain

Full pipeline from C source to executable:

# Compile C to assembly
chappe-cc hello.c -o hello.asm

# Assemble to object file
nasm -f elf64 hello.asm -o hello.o

# Link to executable
chappe-ld -o hello.elf hello.o

See Also: Toolchain Documentation for complete details

What Was Built

The bootloader follows the multiboot2 specification:

  1. Multiboot2 Header (header.asm) - Identifies kernel to bootloader
  2. 32-bit Bootloader (main.asm) - Checks CPU, sets up paging, transitions to 64-bit
  3. 64-bit Entry (main64.asm) - Entry point for 64-bit code
  4. Brain Controller Kernel (kernel_main.asm + braincontroller_64.asm) - The actual kernel

Testing

Option 1: Direct QEMU (May Not Work)

QEMU's -kernel option expects a Linux kernel format, not multiboot:

qemu-system-x86_64 -kernel build/chappe.bin

This may give an error because QEMU tries to load it as a Linux kernel.

Option 2: Use GRUB (Recommended)

For proper multiboot support, use GRUB:

  1. Install GRUB using scripts/install_grub.sh
  2. Boot from the created disk image
qemu-system-x86_64 -drive format=raw,file=build/chappe_grub.img

Current Status

  • Build System: Working (uses WSL for ELF linking, or chappe-ld)
  • Multiboot Header: Created
  • 32-bit Bootloader: Created
  • 64-bit Transition: Implemented
  • Brain Controller: 64-bit version created
  • Shell: 64-bit implementation with scrolling
  • Formatting System: Color and text formatting
  • Toolchain: Compiler (chappe-cc) Phase 1 complete, Linker (chappe-ld) Phase 1 complete

Troubleshooting

"WSL not found"

  • Install WSL: wsl --install
  • Or use a Linux environment

"Error loading kernel"

  • QEMU's -kernel expects Linux format
  • Use GRUB for multiboot kernels

Linker errors

  • If using WSL: Make sure WSL has ld installed
  • Try: wsl bash -c "which ld"
  • If using chappe-ld: Make sure the linker is built (toolchain\linker\build\chappe-ld.exe)
  • Build the linker: cd toolchain\linker && .\build.ps1

Compiler errors

  • Make sure the compiler is built (toolchain\compiler\build\chappe-cc.exe)
  • Build the compiler: cd toolchain\compiler && .\build.ps1
  • Ensure GCC or Clang is available for building the toolchain