How graysonhuey/auroralang works
Project type and purpose
• This is a compiler for the Aurora programming language, written in Rust.
• It takes a .aur source file, tokenizes it, generates x86-64 assembly, and then invokes FASM and LD to produce a runnable executable.
File structure
• Top-level files:
– Cargo.toml / Cargo.lock: Rust build and dependency manifest
– README.md, LICENSE: documentation
• src/ directory:
– main.rs: entry point, CLI parsing, overall compilation workflow
– tokens.rs: lexical analysis (tokenizer)
– generateASM.rs: core code generation into x86-64 assembly
– utils.rs: shared constants, helper functions
• tests/ directory:
– .aur test programs plus prebuilt binaries for gold-file testing
– A test harness in Rust likely under tests/ (invokes the compiler, assembles, runs)
README for additional insights
• Compilation pipeline is linear: tokenization → assembly instruction generation → FASM assembly → LD linking
• Uses external tools: FASM (Flat Assembler) and LD (GNU Linker)
• No separate parsing/AST stage—tokens flow directly into code generator
Main components and their interactions
a. Components
1. User (CLI)
2. Compiler binary (Rust):
• CLI handler (main.rs)
• Tokenizer (tokens.rs)
• Code generator (generateASM.rs)
• Utilities (utils.rs)
3. External tools: FASM assembler, LD linker
4. File artifacts:
• Input: .aur source file
• Intermediate: .asm file, object file .o
• Output: final executable binary
5. Test harness (in tests/): drives end-to-end compilation and validation
b. Relationships / Data flow
– CLI invokes the compiler with a .aur file
– main.rs reads file → calls tokenizer → receives a stream of tokens
– code generator consumes tokens → emits x86-64 assembly text → writes .asm
– Rust process spawns FASM on .asm → produces .o
– Rust process spawns LD on .o → links into final executable
– Tests invoke the same pipeline, then run the produced binary and compare output to expected results
c. Architectural patterns / design principles
– Single-pass linear pipeline (no full AST, tokens go straight to codegen)
– Modular separation of concerns: CLI, lexing, codegen, utils
– Externalizing platform-specific assembly and linking to FASM/LD
d. Key technologies
– Rust (edition 2018)
– FASM (x86-64 assembler), GNU LD (linker)
– Cargo (build tool)
Diagramming recommendations
– Rounded rectangles for user and file artifacts
– Rectangles for internal compiler modules
– Hexagons or clouds for external services/tools (FASM, LD)
– Blue for CLI / user interaction
– Green for compiler internals
– Orange for external tools
– Gray for file artifacts
• Major utility or shared functionality (e.g., integer-printing helpers in utils.rs)
Essential elements
• Arrowheads to show data flow direction
• A note on the linear nature of the pipeline (no multi-pass AST)
• The test harness and its comparison against expected outputs