SpecterCC

A educational compiler written in C++.

Architecture

SpecterCC follows a classic compiler pipeline:

        Source Code 
             |
           Lexer
             |
           Parser
             |
            AST
             |  
     Semantic Analyzer
             |
      Code Generator
             |
          Assembly

Components

• Lexer: Tokenizes source code into a stream of tokens
• Parser: Constructs an Abstract Syntax Tree (AST) from tokens
• Semantic Analyzer: Type checking and symbol resolution
• Code Generator: Generates x86-64 assembly code

Features

• Basic types: int, float, double, char, bool, void
• Variables and assignments
• Arithmetic operators: +, -, *, /, %
• Comparison operators: ==, !=, <, <=, >, >=
• Logical operators: &&, ||, !
• Control flow: if/else, while
• Functions with parameters and return values
• Block scoping
• C preprocessor integration (#define macros, conditional compilation)

Building

mkdir build && cd build
cmake ..
make

Usage

./spectercc <input-file> [-o <output-file>] [-S] [-c] [-E] [-P]

Options:

• -o <file>: Write output to <file> (default: a.out for executable, out.s for assembly)
• -S: Generate assembly only (stops before assembling)
• -c: Compile to object file only (stops before linking)
• -E: Preprocess only (run C preprocessor and output result)
• -P: Enable preprocessing with system C preprocessor before compilation

Examples

Compile to executable (default behavior):

./spectercc examples/simple.spc -o simple
./simple

Generate assembly only:

./spectercc examples/simple.spc -S -o simple.s

Generate object file only:

./spectercc examples/simple.spc -c -o simple.o

Use C preprocessor (for #define macros):

./spectercc myfile.spc -P -o myprogram

Preprocess only (debug preprocessor output):

./spectercc myfile.spc -E -o output.i

The compiler now handles assembly and linking internally, producing a ready-to-run executable by default!

Examples

See the examples/ directory for sample programs:

• simple.spc: Basic variable assignment
• arithmetic.spc: Arithmetic operations and function calls
• conditional.spc: If/else statements
• loop.spc: While loops and factorial calculation

Language Syntax

SpecterCC supports a C-like syntax:

int factorial(int n) {
    int result;
    result = 1;
    
    while (n > 1) {
        result = result * n;
        n = n - 1;
    }
    
    return result;
}

int main() {
    int f;
    f = factorial(5);
    return f;
}

Preprocessing Support

SpecterCC supports C preprocessor directives through integration with the system C preprocessor (gcc -E).

What Works

With the -P flag, you can use:

• #define for simple macros
• #define with parameters: #define ADD(a,b) ((a)+(b))
• Conditional compilation: #ifdef, #ifndef, #if, #else, #endif
• File inclusion: #include (but see limitations below)

Example with Preprocessor

#define MAX_VALUE 100
#define DOUBLE(x) ((x) * 2)

int main() {
    int x;
    x = DOUBLE(MAX_VALUE);
    return x;
}

Compile with:

./spectercc myfile.spc -P -o myprogram

Issues

Important: While #include <stdio.h> is now acepted, it brings in complex C features (function pointers, complex types, etc.) that SpecterCC doesn't support. Including system headers will likely cause parsing errors.

Recommendation: Use -P for your own #define macros and custom headers, but avoid including standard system headers like stdio.h, stdlib.h, etc.