jompiler/AGENTS.md

Jompiler Agent Instructions

This is a C compiler that targets x86-64 ELF object files.

Key Commands

• node index.js input.c - Compile and link input.c to produce a.out
• node index.js input.c && ./a.out - Compile, link, and run the compiled program
• ./run-tests.sh - Run the full test suite using test-current.js

Architecture

This is a single-file compiler written in JavaScript with the following phases:

1. Lexing (tokenization) - lex() function
2. Parsing (AST construction) - parse() function
3. Lowering (x86-64 code generation) - lower() function
4. Linking - link() function that shells out to gcc

Dependencies

The system requires:

• Node.js (tested with Node.js 22)
• GCC (for linking)
• LLVM tools (for development environment - installed via nix)

Important Details

• The compiler supports basic C constructs: integers, variables, basic arithmetic, function declarations, function calls, returns, and basic control flow
• Uses the standard C calling convention for x86-64
• Generates x86-64 ELF object files
• Has no support for complex C features like pointers, conditionals, loops, arrays
• Supports the same C standard as referenced in the comment: C11 (ISO/IEC 9899:2011)
• Has a specific test case in input.c that demonstrates basic functionality
• The dump-main.gdb file is used for debugging and disassembly

Runtime Environment

• Uses Nix for environment setup: nix-shell or direnv with the provided shell.nix
• Requires node to be available from PATH
• Requires gcc and gdb for linking and debugging
• Uses spawn to execute external commands (GCC linking, GDB debugging)