Chapp-E Toolchain

Overview

The Chapp-E toolchain provides all the tools necessary to compile, assemble, and link programs for the Chapp-E Neural OS.

Components

Compiler (chappe-cc)

A C compiler that targets Chapp-E's x86-64 architecture and generates assembly code compatible with Chapp-E's calling conventions and system calls.

Status: ✅ Phase 1 Complete - Basic C to assembly compilation working

Features:

✅ Function compilation
✅ Integer literals and basic expressions
✅ Return statements
✅ NASM-compatible assembly output
⏳ Variable support (planned)
⏳ Preprocessor support (planned)
⏳ Arrays and pointers (planned)

Location: toolchain/compiler/

Assembler (chappe-as)

An assembler that processes assembly code and generates object files for Chapp-E.

Status: Using NASM (external) for now - Custom assembler planned for future

Linker (chappe-ld)

A linker that combines object files and libraries into executable binaries for Chapp-E. Generates ELF64 executables with Chapp-E's memory layout.

Status: ✅ Phase 1 Complete - Core linking functionality implemented

Features:

✅ ELF64 object file reading
✅ Symbol resolution and conflict detection
✅ Section merging (.text, .data, .rodata, .bss)
✅ Address assignment (code: 0x100000, data: 0x200000, bss: 0x300000)
✅ ELF64 executable generation
✅ Program header creation
✅ Entry point resolution (_start)
⏳ Relocation processing (planned)
⏳ Library linking (-lchappe) (planned)

Memory Layout:

Code Base: 0x100000 (executable code)
Data Base: 0x200000 (initialized data)
BSS Base: 0x300000 (uninitialized data - note: conflicts with DAG-FS, needs adjustment)

Location: toolchain/linker/

See Also: Memory Layout for complete address map

Binary Utilities

Standard tools for working with Chapp-E binaries:

objcopy - Copy and manipulate object files
objdump - Disassemble object files
nm - Display symbol tables

Status: TODO - Implementation pending

Memory Layout

The toolchain respects Chapp-E's memory layout. The linker (chappe-ld) assigns addresses based on this layout:

Address	Section	Purpose	Status
`0x100000`	.text (Code)	Executable code sections	✅ Active
`0x200000`	.data (Data)	Initialized data sections	✅ Active
`0x300000`	.bss (BSS)	Uninitialized data sections	⚠️ Conflicts with DAG-FS

✅ NOTE: The linker's BSS base (0x300000) is stored as metadata in the `.chappe` executable header. Executables are stored as DAG-FS patterns and loaded into Working Memory (0x200000) when executed, so there's no actual conflict. The address is just metadata for the executable format.

See Also: Complete Memory Layout for full address map

Integration with libchappe

The toolchain automatically links with libchappe when compiling C programs. The compiler knows about:

Chapp-E's calling conventions
System call interface
Memory layout
Brain-inspired features

Implementation Plan

See toolchain/IMPLEMENTATION_PLAN.md for detailed implementation plan.

Phase 1: Basic Compiler

Port TCC (Tiny C Compiler) or write minimal compiler to target Chapp-E.

Phase 2: Linker

Implement basic linker for ELF64 executables with Chapp-E memory layout.

Phase 3: Full C Support

Complete C99 support with libchappe integration.

Phase 4: Optimizations

Brain-inspired optimizations and memory layout optimizations.

Current Status

Component	Status	Notes
Toolchain Structure	✅ Created	Directory structure and build scripts in place
Compiler (chappe-cc)	✅ Phase 1 Complete	Basic C to assembly compilation working. Functions, integers, returns implemented.
Assembler (chappe-as)	✅ Using NASM	External NASM assembler used. Custom assembler planned for future.
Linker (chappe-ld)	✅ Phase 1 Complete	Core linking functionality implemented. ELF64 generation working.
Binary Utilities	⏳ Planned	objcopy, objdump, nm, readelf planned for future

Usage Examples

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

Full Pipeline

chappe-cc hello.c -o hello.asm
nasm -f elf64 hello.asm -o hello.o
chappe-ld -o hello.elf hello.o