common/README_TESTS.md

Common Compiler - Test Suite and Examples

This directory contains a comprehensive test suite and example programs for the Common programming language compiler.

Building the Compiler

First, build the compiler:

gcc -o common common.c

Test Suite

Building and Running Tests

The test suite is a dependency-free C99 program that automatically compiles, assembles, links, and runs test programs.

# Build the test runner
gcc -std=c99 -o test_runner test_runner.c

# Run all tests
./test_runner

The test runner will:

1. Compile each test program with the Common compiler
2. Assemble with NASM
3. Link with GCC
4. Execute and verify the results
5. Report pass/fail status

Test Coverage

The test suite includes over 60 tests covering:

• Arithmetic: add, subtract, multiply, divide, modulo
• Variables: local and global variables with initialization
• Control Flow: if/else, while, for, switch/case, break, continue
• Operators:
  • Comparison: ==, !=, <, <=, >, >=
  • Logical: &&, ||, !
  • Bitwise: &, |, ^, ~, <<, >>
  • Increment/Decrement: ++, --
  • Compound Assignment: +=, -=, *=, /=, etc.
• Functions: calls, recursion, multiple parameters
• Arrays: declaration, initialization, indexing
• Pointers: address-of, dereference, pointer arithmetic
• Type Casting: explicit casts between integer types
• Integer Types: uint8, uint16, uint32, uint64, int8, int16, int32, int64
• Ternary Operator: ? :

Example Programs

The examples/ directory contains practical programs demonstrating Common language features.

Compiling Examples

All examples follow this pattern:

./common examples/hello.cm hello.asm
nasm -f elf32 hello.asm -o hello.o
gcc -m32 hello.o -o hello
./hello

Or use this one-liner:

./common examples/hello.cm hello.asm && nasm -f elf32 hello.asm && gcc -m32 hello.o -o hello && ./hello

Available Examples

hello.cm

Basic "Hello, World!" program.

./common examples/hello.cm hello.asm && nasm -f elf32 hello.asm && gcc -m32 hello.o -o hello
./hello

fibonacci.cm

Recursive Fibonacci number calculator. Demonstrates:

• Function recursion
• Conditionals
• Loops

./common examples/fibonacci.cm fib.asm && nasm -f elf32 fib.asm && gcc -m32 fib.o -o fib
./fib

arrays.cm

Array manipulation with sum and reverse operations. Demonstrates:

• Array initialization
• Array traversal
• Function parameters with arrays
• Array modification

./common examples/arrays.cm arrays.asm && nasm -f elf32 arrays.asm && gcc -m32 arrays.o -o arrays
./arrays

pointers.cm

Pointer operations and pointer arithmetic. Demonstrates:

• Pointer declaration and dereferencing
• Address-of operator
• Pointer arithmetic
• Pointer to pointer
• Pass-by-reference with pointers

./common examples/pointers.cm ptrs.asm && nasm -f elf32 ptrs.asm && gcc -m32 ptrs.o -o ptrs
./ptrs

bubblesort.cm

Bubble sort implementation. Demonstrates:

• Nested loops
• Array sorting
• Swap algorithm

./common examples/bubblesort.cm sort.asm && nasm -f elf32 sort.asm && gcc -m32 sort.o -o sort
./sort

bitwise.cm

Comprehensive bitwise operations. Demonstrates:

• Bitwise AND, OR, XOR, NOT
• Bit shifts
• Bit counting
• Bit manipulation algorithms

./common examples/bitwise.cm bits.asm && nasm -f elf32 bits.asm && gcc -m32 bits.o -o bits
./bits

types.cm

Different integer types and type casting. Demonstrates:

• uint8, uint16, uint32
• int8, int16, int32
• Type casting
• Sign extension
• Truncation behavior

./common examples/types.cm types.asm && nasm -f elf32 types.asm && gcc -m32 types.o -o types
./types

switch.cm

Switch/case statement usage. Demonstrates:

• Switch statements
• Case labels
• Default case
• Fall-through behavior

./common examples/switch.cm switch.asm && nasm -f elf32 switch.asm && gcc -m32 switch.o -o switch
./switch

primes.cm

Prime number calculator. Demonstrates:

• Mathematical algorithms
• Optimized loop conditions
• Complex conditionals

./common examples/primes.cm primes.asm && nasm -f elf32 primes.asm && gcc -m32 primes.o -o primes
./primes

strings.cm

String manipulation functions. Demonstrates:

• String literals
• Character arrays
• String length, copy, compare
• String reversal

./common examples/strings.cm strings.asm && nasm -f elf32 strings.asm && gcc -m32 strings.o -o strings
./strings

calculator.cm

Expression calculator with global state. Demonstrates:

• Global variables
• Multiple function definitions
• Function composition
• Error handling
• State tracking

./common examples/calculator.cm calc.asm && nasm -f elf32 calc.asm && gcc -m32 calc.o -o calc
./calc

Common Language Quick Reference

Types

uint8, uint16, uint32, uint64
int8, int16, int32, int64
void

Variables

int32 x;           // Declaration
int32 y = 42;      // Declaration with initialization
int32 arr[10];     // Array declaration
int32 *ptr;        // Pointer declaration

Control Flow

if (condition) { ... }
if (condition) { ... } else { ... }
while (condition) { ... }
for (init; condition; increment) { ... }
switch (expr) {
    case value: ... break;
    default: ...
}

Operators

// Arithmetic: +, -, *, /, %
// Comparison: ==, !=, <, <=, >, >=
// Logical: &&, ||, !
// Bitwise: &, |, ^, ~, <<, >>
// Assignment: =, +=, -=, *=, /=, %=, &=, |=, ^=, <<=, >>=
// Increment/Decrement: ++, --
// Ternary: ? :
// Address: &, *

Functions

int32 function_name(int32 param1, uint8 *param2) {
    return value;
}

Comments

// Single line comment
/* Multi-line
   comment */

Requirements

• GCC with 32-bit support (gcc-multilib)
• NASM assembler
• Linux (or compatible environment)

On Ubuntu/Debian:

sudo apt-get install gcc-multilib nasm

Troubleshooting

Error: "cannot find -lgcc_s"

• Install 32-bit libraries: sudo apt-get install gcc-multilib

Error: "nasm: command not found"

• Install NASM: sudo apt-get install nasm

Test failures

• Ensure the compiler binary is in the current directory: ./common
• Check that you have write access to /tmp/
• Verify 32-bit support is installed

License

The test suite and examples are provided as-is for testing and demonstration purposes.